Authentication, Authorization and Accounting (AAA) Services
===========================================================
-The Boron AAA services are based on the Apache Shiro Java Security
-Framework. The main configuration file for AAA is located at
-“etc/shiro.ini” relative to the ODL karaf home directory.
+Overview
+--------
+
+Authentication, Authorization and Accounting (AAA) is a term for a
+framework controlling access to resources, enforcing policies to use
+those resources and auditing their usage. These processes are the
+fundamental building blocks for effective network management and security.
+
+Authentication provides a way of identifying a user, typically by
+having the user enter a valid user name and valid password before access
+is granted. The process of authentication is based on each user having a unique
+set of criteria for gaining access. The AAA framework compares a user's
+authentication credentials with other user credentials stored in a database.
+If the credentials match, the user is granted access to the network.
+If the credentials don't match, authentication fails and access is denied.
+
+Authorization is the process of finding out what an authenticated user is
+allowed to do within the system, which tasks can do, which API can call, etc.
+The authorization process determines whether the user has the authority
+to perform such actions.
+
+Accounting is the process of logging the activity of an authenticated user,
+for example, the amount of data a user has sent and/or received during a
+session, which APIs called, etc.
Terms And Definitions
----------------------
+^^^^^^^^^^^^^^^^^^^^^
+
+AAA
+ Authentication, Authorization and Accounting.
Token
- A claim of access to a group of resources on the controller
+ A claim of access to a group of resources on the controller.
Domain
A group of resources, direct or indirect, physical, logical, or
- virtual, for the purpose of access control. ODL recommends using the
- default “sdn" domain in the Boron release.
+ virtual, for the purpose of access control.
User
A person who either owns or has access to a resource or group of
- resources on the controller
+ resources on the controller.
Role
Opaque representation of a set of permissions, which is merely a
- unique string as admin or guest
+ unique string as admin or guest.
Credential
- Proof of identity such as username and password, OTP, biometrics, or
- others
+ Proof of identity such as user name and password, OTP, biometrics, or
+ others.
Client
- A service or application that requires access to the controller
+ A service or application that requires access to the controller.
Claim
A data set of validated assertions regarding a user, e.g. the role,
domain, name, etc.
+IdP
+ Identity Provider.
+
+TLS
+ Transport Layer Security
+
+CLI
+ Command Line Interface
+
+Security Framework for AAA services
+-----------------------------------
+
+Since Boron release, the OpenDaylight's AAA services are based on the
+`Apache Shiro <https://shiro.apache.org/>`_ Java Security Framework. The main
+configuration file for AAA is located at “etc/shiro.ini” relative to the
+OpenDaylight Karaf home directory.
+
+
How to enable AAA
-----------------
-AAA is enabled through installing the odl-aaa-shiro feature.
-odl-aaa-shiro is automatically installed as part of the odl-restconf
-offering.
+AAA is enabled through installing the odl-aaa-shiro feature. The vast majority
+of OpenDaylight's northbound APIs (and all RESTCONF APIs) are protected by AAA
+by default when installing the +odl-restconf+ feature, since the odl-aaa-shiro
+is automatically installed as part of them. In the cases that APIs are *not*
+protected by AAA, this will be noted in the per-project release notes.
How to disable AAA
------------------
/** = anon
-Then restart the karaf process.
-
-How application developers can leverage AAA to provide servlet security
------------------------------------------------------------------------
-
-In order to provide security to a servlet, add the following to the
-servlet’s web.xml file as the first filter definition:
-
-::
-
- <context-param>
- <param-name>shiroEnvironmentClass</param-name>
- <param-value>org.opendaylight.aaa.shiro.web.env.KarafIniWebEnvironment</param-value>
- </context-param>
-
- <listener>
- <listener-class>org.apache.shiro.web.env.EnvironmentLoaderListener</listener-class>
- </listener>
-
- <filter>
- <filter-name>ShiroFilter</filter-name>
- <filter-class>org.opendaylight.aaa.shiro.filters.AAAShiroFilter</filter-class>
- </filter>
-
- <filter-mapping>
- <filter-name>AAAShiroFilter</filter-name>
- <url-pattern>/*</url-pattern>
- </filter-mapping>
-
-.. note::
-
- It is very important to place this AAAShiroFilter as the first
- javax.servlet.Filter, as Jersey applies Filters in the order they
- appear within web.xml. Placing the AAAShiroFilter first ensures
- incoming HTTP/HTTPS requests have proper credentials before any
- other filtering is attempted.
+Then restart the Karaf process.
AAA Realms
----------
-AAA plugin utilizes realms to support pluggable authentication &
+AAA plugin utilizes the Shiro Realms to support pluggable authentication &
authorization schemes. There are two parent types of realms:
- AuthenticatingRealm
based on roles.
- Useful for applications in which roles determine allowed
- cabilities.
+ capabilities.
-ODL Contains Four Implementations
+OpenDaylight contains five implementations:
- TokenAuthRealm
- A python script located at “etc/idmtool” is included to help
manipulate data contained in the TokenAuthRealm.
- - Enabled out of the box.
+ - Enabled out of the box. This is the realm configured by default.
- ODLJndiLdapRealm
- An AuthorizingRealm built to extract identity information from IdM
data contained on an LDAP server.
- - Extracts group information from LDAP, which is translated into ODL
- roles.
+ - Extracts group information from LDAP, which is translated into
+ OpenDaylight roles.
- Useful when federating against an existing LDAP server, in which
only certain types of users should have certain access privileges.
- Disabled out of the box.
-- ActiveDirectoryRealm
+- ODLActiveDirectoryRealm
+
+ - Wraps the generic ActiveDirectoryRealm provided by Shiro. This allows for
+ enhanced logging as well as isolation of all realms in a single package,
+ which enables easier import by consuming servlets.
+
+- KeystoneAuthRealm
+
+ - This realm authenticates OpenDaylight users against the OpenStack’s
+ Keystone server.
+
+ - Disabled out of the box.
.. note::
- More than one Realm implementation can be specified. Realms are
- attempted in order until authentication succeeds or all realm
- sources are exhausted.
+ More than one Realm implementation can be specified. Realms are attempted
+ in order until authentication succeeds or all realm sources are exhausted.
+ Edit the **securityManager.realms = $tokenAuthRealm** property in shiro.ini
+ and add all the realms needed separated by commas.
-TokenAuthRealm Configuration
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+TokenAuthRealm
+^^^^^^^^^^^^^^
-TokenAuthRealm stores IdM data in an h2 database on each node. Thus,
-configuration of a cluster currently requires configuring the desired
-IdM policy on each node. There are two supported methods to manipulate
-the TokenAuthRealm IdM configuration:
+How it works
+~~~~~~~~~~~~
-- idmtool Configuration
+The TokenAuthRealm is the default Authorization Realm deployed in OpenDaylight.
+TokenAuthRealm uses a direct authentication mechanism as shown in the following
+picture:
-- RESTful Web Service Configuration
+.. figure:: ./images/aaa/direct-authentication.png
+ :alt: TokenAuthRealm direct authentication mechanism
-idmtool Configuration
-^^^^^^^^^^^^^^^^^^^^^
+ TokenAuthRealm direct authentication mechanism
+
+A user presents some credentials (e.g., username/password) directly to the
+OpenDaylight controller token endpoint /oauth2/token and receives an access
+token, which then can be used to access protected resources on the controller.
+
+Configuring TokenAuthRealm
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The TokenAuthRealm stores IdM data in an h2 database on each node. Thus,
+configuration of a cluster currently requires configuring the desired IdM policy
+on each node. There are two supported methods to manipulate the TokenAuthRealm
+IdM configuration:
+
+- idmtool configuration tool
+
+- RESTful Web Service configuration
+
+**Idmtool**
+###########
A utility script located at “etc/idmtool” is used to manipulate the
-TokenAuthRealm IdM policy. idmtool assumes a single domain (sdn), since
-multiple domains are not leveraged in the Boron release. General usage
-information for idmtool is derived through issuing the following
-command:
+TokenAuthRealm IdM policy. idmtool assumes a single domain, the default one
+(sdn), since multiple domains are not supported in the Boron release. General
+usage information for idmtool is derived through issuing the following command:
::
]
}
-RESTful Web Service
-^^^^^^^^^^^^^^^^^^^
+**Configuration using the RESTful Web Service**
+###############################################
The TokenAuthRealm IdM policy is fully configurable through a RESTful
web service. Full documentation for manipulating AAA IdM data is located
]
}
-ODLJndiLdapRealm Configuration
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+**Token Store Configuration Parameters**
+########################################
+
+Edit the file “etc/opendaylight/karaf/08-authn-config.xml” and edit the
+following: .\ **timeToLive**: Configure the maximum time, in milliseconds,
+that tokens are to be cached. Default is 360000. Save the file.
+
+ODLJndiLdapRealm
+^^^^^^^^^^^^^^^^
+
+How it works
+~~~~~~~~~~~~
LDAP integration is provided in order to externalize identity
-management. To configure LDAP parameters, modify "etc/shiro.ini"
+management. This configuration allows federation with an external LDAP server.
+The user’s OpenDaylight role parameters are mapped to corresponding LDAP
+attributes as specified by the groupRolesMap. Thus, an LDAP operator can
+provision attributes for LDAP users that support different OpenDaylight role
+structures.
+
+Configuring ODLJndiLdapRealm
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To configure LDAP parameters, modify "etc/shiro.ini"
parameters to include the ODLJndiLdapRealm:
::
- # ODL provides a few LDAP implementations, which are disabled out of the box.
+ # OpenDaylight provides a few LDAP implementations, which are disabled out of the box.
# ODLJndiLdapRealm includes authorization functionality based on LDAP elements
# extracted through and LDAP search. This requires a bit of knowledge about
# how your LDAP system is setup. An example is provided below:
# Stacked realm configuration; realms are round-robbined until authentication succeeds or realm sources are exhausted.
securityManager.realms = $tokenAuthRealm, $ldapRealm
-This configuration allows federation with an external LDAP server, and
-the user’s ODL role parameters are mapped to corresponding LDAP
-attributes as specified by the groupRolesMap. Thus, an LDAP operator can
-provision attributes for LDAP users that support different ODL role
-structures.
+ODLJndiLdapRealmAuthNOnly
+^^^^^^^^^^^^^^^^^^^^^^^^^
-ODLJndiLdapRealmAuthNOnly Configuration
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+How it works
+~~~~~~~~~~~~
+
+This is useful for setups where all LDAP users are allowed equal access.
+
+Configuring ODLJndiLdapRealmAuthNOnly
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Edit the "etc/shiro.ini" file and modify the following:
# Stacked realm configuration; realms are round-robbined until authentication succeeds or realm sources are exhausted.
securityManager.realms = $tokenAuthRealm, $ldapRealm
-This is useful for setups where all LDAP users are allowed equal access.
+KeystoneAuthRealm
+^^^^^^^^^^^^^^^^^
-Token Store Configuration Parameters
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+How it works
+~~~~~~~~~~~~
-Edit the file “etc/opendaylight/karaf/08-authn-config.xml” and edit the
-following: .\ **timeToLive**: Configure the maximum time, in
-milliseconds, that tokens are to be cached. Default is 360000. Save the
-file.
+This realm authenticates OpenDaylight users against the OpenStack's Keystone
+server. This realm uses the
+`Keystone's Identity API v3 <https://developer.openstack.org/api-ref/identity/v3/>`_
+or later.
+
+.. figure:: ./images/aaa/keystonerealm-authentication.png
+ :alt: KeystoneAuthRealm authentication mechanism
+
+ KeystoneAuthRealm authentication/authorization mechanism
+
+As can shown on the above diagram, once configured, all the RESTCONF APIs calls
+will require sending **user**, **password** and optionally **domain** (1). Those
+credentials are used to authenticate the call against the Keystone server (2) and,
+if the authentication succeeds, the call will proceed to the MDSAL (3). The
+credentials must be provisioned in advance within the Keystone Server. The user
+and password are mandatory, while the domain is optional, in case it is not
+provided within the REST call, the realm will default to (**Default**),
+which is hard-coded. The default domain can be also configured through the
+*shiro.ini* file (see the :doc:`AAA User Guide <../user-guide/authentication-and-authorization-services>`).
+
+The protocol between the Controller and the Keystone Server (2) can be either
+HTTPS or HTTP. In order to use HTTPS the Keystone Server's certificate
+must be exported and imported on the Controller (see the :ref:`Certificate Management <certificate-management>` section).
+
+Configuring KeystoneAuthRealm
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Edit the "etc/shiro.ini" file and modify the following:
+
+::
+
+ # The KeystoneAuthRealm allows for authentication/authorization against an
+ # OpenStack's Keystone server. It uses the Identity's API v3 or later.
+ keystoneAuthRealm = org.opendaylight.aaa.shiro.realm.KeystoneAuthRealm
+ # The URL where the Keystone server exposes the Identity's API v3 the URL
+ # can be either HTTP or HTTPS and it is mandatory for this realm.
+ keystoneAuthRealm.url = https://<host>:<port>
+ # Optional parameter to make the realm verify the certificates in case of HTTPS
+ #keystoneAuthRealm.sslVerification = true
+ # Optional parameter to set up a default domain for requests using credentials
+ # without domain, uncomment in case you want a different value from the hard-coded
+ # one "Default"
+ #keystoneAuthRealm.defaultDomain = Default
+
+Once configured the realm, the mandatory fields are the fully quallified name of
+the class implementing the realm *keystoneAuthRealm* and the endpoint where the
+Keystone Server is listening *keystoneAuthRealm.url*.
+
+The optional parameter *keystoneAuthRealm.sslVerification* specifies whether the
+realm has to verify the SSL certificate or not. The optional parameter
+*keystoneAuthRealm.defaultDomain* allows to use a different default domain from
+the hard-coded one *"Default"*.
Authorization Configuration
---------------------------
-Shiro-Based Authorization
-~~~~~~~~~~~~~~~~~~~~~~~~~
+OpenDaylight supports two authorization engines at present, both of which are
+roughly similar in behavior:
-OpenDaylight AAA has support for Role Based Access Control based on the
-Apache Shiro permissions system. Configuration of the authorization
-system is done offline; authorization currently cannot be configured
-after the controller is started. Thus, Authorization in this
-release is aimed towards supporting coarse-grained security policies,
-with the aim to provide more robust configuration capabilities in the
-future. Shiro-based Authorization is documented on the Apache Shiro
-website (http://shiro.apache.org/web.html#Web-%7B%7B%5Curls%5C%7D%7D).
+- Shiro-Based Authorization
+
+- MDSAL-Based Dynamic Authorization
+
+.. note::
+
+ The preferred mechanism for configuring AAA Authentication is the
+ MDSAL-Based Dynamic Authorization. Read the following section.
+
+Shiro-Based Static Authorization
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+OpenDaylight AAA has support for Role Based Access Control (RBAC) based
+on the Apache Shiro permissions system. Configuration of the authorization
+system is done off-line; authorization currently cannot be configured
+after the controller is started. The Authorization provided by this mechanism
+is aimed towards supporting coarse-grained security policies, the MDSAL-Based
+mechanism allows for a more robust configuration capabilities. `Shiro-based
+Authorization <http://shiro.apache.org/web.html#Web-%7B%7B%5Curls%5C%7D%7D>`_
+describes how to configure the Authentication feature in detail.
+
+.. notes::
+
+ The Shiro-Based Authorization that uses the *shiro.ini* URLs section to
+ define roles requirements is **deprecated** and **discouraged** since the
+ changes made to the file are only honored on a controller restart.
+
+ Shiro-Based Authorization is not **cluster-aware**, so the changes made on
+ the *shiro.ini* file have to be replicated on every controller instance
+ belonging to the cluster.
+
+ The URL patterns are matched relative to the Servlet context leaving room
+ for ambiguity, since many endpoints may match (i.e., "/restconf/modules" and
+ "/auth/modules" would both match a "/modules/\**" rule).
Enable “admin” Role Based Access to the IdMLight RESTful web service
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Edit the “etc/shiro.ini” configuration file and add “/auth/v1/\ **=
-authcBasic, roles[admin]” above the line “/** = authcBasic” within the
+Edit the “etc/shiro.ini” configuration file and add “/auth/v1/\**=
+authcBasic, roles[admin]” above the line “/\** = authcBasic” within the
“urls” section.
::
The ordering of the authorization rules above is important!
-AuthZ Broker Facade
-~~~~~~~~~~~~~~~~~~~
+MDSAL-Based Dynamic Authorization
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+The MDSAL-Based Dynamic authorization uses the MDSALDynamicAuthorizationFilter
+engine to restrict access to particular URL endpoint patterns. Users may define
+a list of policies that are insertion-ordered. Order matters for that list of
+policies, since the first matching policy is applied. This choice was made to
+emulate behavior of the Shiro-Based Authorization mechanism.
-ODL includes an experimental Authorization Broker Facade, which allows
-finer grained access control for REST endpoints. Since this feature was
-not well tested in the Boron release, it is recommended to use the
-Shiro-based mechanism instead, and rely on the Authorization Broker
-Facade for POC use only.
+A **policy** is a key/value pair, where the key is a **resource**
+(i.e., a "URL pattern") and the value is a list of **permissions** for the
+resource. The following describes the various elements of a policy:
-AuthZ Broker Facade Feature Installation
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+- **Resource**: the resource is a string URL pattern as outlined by
+ Apache Shiro. For more information, see http://shiro.apache.org/web.html.
-To install the authorization broker facade, please issue the following
-command in the karaf shell:
+- **Description**: an optional description of the URL endpoint and why it is
+ being secured.
-::
+- **Permissions list**: a list of permissions for a particular policy. If more
+ than one permission exists in the permissions list they are evaluated using
+ logical "OR". A permission describes the prerequisites to perform HTTP
+ operations on a particular endpoint. The following describes the various
+ elements of a permission:
- feature:install odl-restconf odl-aaa-authz
+ + **Role**: the role required to access the target URL endpoint.
+ + **Actions list**: a leaf-list of HTTP permissions that are allowed for a
+ Subject possessing the required role.
-Add an Authorization Rule
-^^^^^^^^^^^^^^^^^^^^^^^^^
-
-The following shows how one might go about securing the controller so
-that only admins can access restconf.
+This an example on how to limit access to the modules endpoint:
::
- curl -u admin:admin -H “Content-Type: application/xml” --data-binary @./rule.json http://localhost:8181/restconf/config/authorization-schema:simple-authorization/policies/RestConfService/
- cat ./rule.json
- {
- "policies": {
- "resource": "*",
- "service":"RestConfService",
- "role": "admin"
+ HTTP Operation:
+ put URL: /restconf/config/aaa:http-authorization/policies
+
+ headers: Content-Type: application/json Accept: application/json
+
+ body:
+ { "aaa:policies":
+ { "aaa:policies":
+ [ { "aaa:resource": "/restconf/modules/**",
+ "aaa:permissions": [ { "aaa:role": "admin",
+ "aaa:actions": [ "get",
+ "post",
+ "put",
+ "patch",
+ "delete"
+ ]
+ }
+ ]
+ }
+ ]
}
- }
+ }
+
+The above example locks down access to the modules endpoint (and any URLS
+available past modules) to the "admin" role. Thus, an attempt from the OOB
+*admin* user will succeed with 2XX HTTP status code, while an attempt from the
+OOB *user* user will fail with HTTP status code 401, as the user *user* is not
+granted the "admin" role.
Accounting Configuration
------------------------
-All AAA logging is output to the standard karaf.log file.
+Accounting is handled through the standard slf4j logging mechanisms used by the
+rest of OpenDaylight. Thus, one can control logging verbosity through
+manipulating the log levels for individual packages and classes directly through
+the Karaf console, JMX, or etc/org.ops4j.pax.logging.cfg. In normal operations,
+the default levels exposed do not provide much information about AAA services;
+this is due to the fact that logging can severely degrade performance.
+
+All AAA logging is output to the standard karaf.log file. For debugging purposes
+(i.e., to enable maximum verbosity), issue the following command:
::
log:set TRACE org.opendaylight.aaa
-This command enables the most verbose level of logging for AAA
-components.
+Enable Successful/Unsuccessful Authentication Attempts Logging
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+By default, successful/unsuccessful authentication attempts are NOT logged. This
+is due to the fact that logging can severely decrease REST performance.
+To enable logging of successful/unsuccessful REST attempts, issue the following
+command in Karaf's console:
+
+::
+
+ log:set DEBUG org.opendaylight.aaa.shiro.filters.AuthenticationListener
+
+It is possible to add custom AuthenticationListener(s) to the Shiro-based
+configuration, allowing different ways to listen for successful/unsuccessful
+authentication attempts. Custom AuthenticationListener(s) must implement
+the org.apache.shiro.authc.AuthenticationListener interface.
+
+.. _certificate-management:
+Certificate Management
+----------------------
+
+The **Certificate Management Service** is used to manage the keystores and
+certificates at the OpenDaylight distribution to easily provides the TLS
+communication.
+
+The Certificate Management Service managing two keystores:
+
+1. **OpenDaylight Keystore** which holds the OpenDaylight distribution
+ certificate self sign certificate or signed certificate from a root CA based
+ on generated certificate request.
+
+2. **Trust Keystore** which holds all the network nodes certificates that shall
+ to communicate with the OpenDaylight distribution through TLS communication.
+
+The Certificate Management Service stores the keystores (OpenDaylight & Trust)
+as *.jks* files under configuration/ssl/ directory. Also the keystores
+could be stored at the MD-SAL datastore in case OpenDaylight distribution
+running at cluster environment. When the keystores are stored at MD-SAL,
+the Certificate Management Service rely on the **Encryption-Service** to encrypt
+the keystore data before storing it to MD-SAL and decrypted at runtime.
+
+How to use the Certificate Management Service to manage the TLS communication
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The following are the steps to configure the TLS communication:
+
+1. After starting the distribution, the *odl-aaa-cert* feature has to get
+installed. Use the following command at Karaf CLI to check.
+
+.. code-block:: bash
+
+ opendaylight-user@root>feature:list -i | grep aaa-cert
+ odl-aaa-cert | 0.5.0-SNAPSHOT | x | odl-aaa-0.5.0-SNAPSHOT | OpenDaylight :: AAA :: aaa certificate Service
+
+2. The initial configuration of the Certificate Manager Service exists under
+the distribution directory etc/opendaylight/datastore/initial/config/aaa-cert-config.xml.
+
+.. code-block:: xml
+
+ <aaa-cert-service-config xmlns="urn:opendaylight:yang:aaa:cert">
+ <use-config>false</use-config>
+ <use-mdsal>false</use-mdsal>
+ <bundle-name>opendaylight</bundle-name>
+ <ctlKeystore>
+ <name>ctl.jks</name>
+ <alias>controller</alias>
+ <store-password/>
+ <dname>CN=ODL, OU=Dev, O=LinuxFoundation, L=QC Montreal, C=CA</dname>
+ <validity>365</validity>
+ <key-alg>RSA</key-alg>
+ <sign-alg>SHA1WithRSAEncryption</sign-alg>
+ <keysize>1024</keysize>
+ <cipher-suites>
+ <suite-name />
+ </cipher-suites>
+ </ctlKeystore>
+ <trustKeystore>
+ <name>truststore.jks</name>
+ <store-password/>
+ </trustKeystore>
+ </aaa-cert-service-config>
+
+
+Now as it is explained above, the Certificate Manager Service support two mode
+of operations; cluster mode and single mode. To use the single mode change the
+use-config to true and it is recommended as long as there is no need for
+cluster environment. To use the cluster mode change the use-config and
+use-mdsal configurations to true and the keystores will be stored and shard
+across the cluster nodes within the MD-SAL datastore.
+
+The initial password become randomly generated when the *aaa-cert* feature is
+installed.
+
+The cipher suites can be restricted by changing the **<cipher-suites>**
+configuration, however, the JDK has to be upgraded by installing the `Java
+Cryptography Extension
+<http://www.oracle.com/technetwork/java/javase/downloads/jce8-download-2133166.html>`_
+policy.
+
+.. code-block:: xml
+
+ <cipher-suites>
+ <suite-name>TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384</suite-name>
+ </cipher-suites>
+ <cipher-suites>
+ <suite-name>TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384</suite-name>
+ </cipher-suites>
+ <cipher-suites>
+ <suite-name>TLS_DHE_RSA_WITH_AES_256_GCM_SHA384</suite-name>
+ </cipher-suites>
+
+3. The new configurations will take affect after restarting the distribution.
+
+4. Now to add or get certificate to the OpenDaylight and Trust keystores, the
+Certificate Manager Service provides the following RPCs.
+
+::
+
+ a) Set the node certificate that will communicate with OpeDaylight through TLS
+ connection.
+ POST /operations/aaa-cert-rpc:setNodeCertifcate
+ {
+ "input": {
+ "node-cert": "string",
+ "node-alias": "string"
+ }
+ }
+
+::
+
+ b) Get the node certificate based on node alias.
+ POST /operations/aaa-cert-rpc:getNodeCertifcate
+ {
+ "input": {
+ "node-alias": "string"
+ }
+ }
+
+::
+
+ c) Get the OpeDaylight keystore certificate.
+ POST /operations/aaa-cert-rpc:getODLCertificate
+ {
+ output {
+ odl-cert "string"
+ }
+ }
+
+::
+
+ d) Generate a certificate request from the OpeDaylight keystore to be signed
+ by a CA.
+ POST /operations/aaa-cert-rpc:getODLCertificateReq
+ {
+ output {
+ odl-cert-req "string"
+ }
+ }
+
+::
+
+ e) Set the OpeDaylight certificate, the certificate should be generated
+ based on a certificate request generated from the ODL keystore otherwise the
+ certificated will not be added.
+ POST /operations/aaa-cert-rpc:setODLCertificate
+ {
+ "input": {
+ "odl-cert-alias": "string",
+ "odl-cert": "string"
+ }
+ }
+
+.. note::
+
+ The Certificate Manager Service RPCs are allowed only to the Role Admin Users
+ and it could be completely disabled through the shiro.ini config file. Check
+ the URL section at the shiro.ini.
+
+Encryption Service
+------------------
+
+The **AAA Encryption Service** is used to encrypt the OpenDaylight's users'
+passwords and TLS communication certificates. This section shows how to use the
+AAA Encryption Service with an OpenDaylight distribution project to encrypt data.
+
+The following are the steps to configure the Encryption Service:
+
+1. After starting the distribution, the *aaa-encryption-service* feature has to
+ get installed. Use the following command at Karaf CLI to check.
+
+ .. code-block:: bash
+
+ opendaylight-user@root>feature:list -i | grep aaa-encryption-service
+ odl-aaa-encryption-service | 0.5.0-SNAPSHOT | x | odl-aaa-0.5.0-SNAPSHOT | OpenDaylight :: AAA :: Encryption Service
+
+2. The initial configuration of the Encryption Service exists under the
+ distribution directory etc/opendaylight/datastore/initial/config/aaa-encrypt-service-config.xml
+
+ .. code-block:: xml
+
+ <aaa-encrypt-service-config xmlns="config:aaa:authn:encrypt:service:config">
+ <encrypt-key/>
+ <encrypt-salt/>
+ <encrypt-method>PBKDF2WithHmacSHA1</encrypt-method>
+ <encrypt-type>AES</encrypt-type>
+ <encrypt-iteration-count>32768</encrypt-iteration-count>
+ <encrypt-key-length>128</encrypt-key-length>
+ <cipher-transforms>AES/CBC/PKCS5Padding</cipher-transforms>
+ </aaa-encrypt-service-config>
+
+ .. note::
+
+ Both the initial encryption key and encryption salt become randomly generated
+ when the *aaa-encryption-service* feature is installed.
+3. Finally the new configurations will take affect after restarting the
+ distribution.
Code Review / docs.git / blobdiff