+.. _aaa-user-guide:
+
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.
+Grant
+ It is the entity associating a user with his role and domain.
+
+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.
-
-.. note::
-
- This is a change from the Lithium release, in which
- “etc/org.opendaylight.aaa.authn.cfg” was edited to set
- “authEnabled=false”. Please use the “shiro.ini” mechanism to disable
- AAA going forward.
-
-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
- An AuthorizingRealm built to bridge the Shiro-based AAA service
- with the Lithium h2-based AAA implementation.
+ with the h2-based AAA implementation.
- Exposes a RESTful web service to manipulate IdM policy on a
per-node basis. If identical AAA policy is desired across a
- 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:
+
+- 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::
-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 the Beryllium
-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).
+ 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.
- feature:install odl-restconf odl-aaa-authz
+- **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:
-Add an Authorization Rule
-^^^^^^^^^^^^^^^^^^^^^^^^^
+ + **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.
-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.
+
+Using the AAA Command Line Interface (CLI)
+------------------------------------------
+The AAA offers a CLI through the Karaf's console. This CLI allows the user to
+configure and use some of the functionalities provided by AAA.
+
+The AAA CLI exists under the **odl-aaa-cli** feature. This feature can be
+installed by executing the following command.
+
+::
+
+ feature:install odl-aaa-cli
+
+To check that the installation of the feature succeeded type "aaa" and press
+*tab* to see the list of available commands under the *aaa* scope.
+
+::
+
+ opendaylight-user@root>aaa:
+ aaa:add-domain aaa:add-grant aaa:add-role aaa:add-user
+ aaa:change-user-pwd aaa:export-keystores aaa:gen-cert-req aaa:get-cipher-suites
+ aaa:get-domains aaa:get-node-cert aaa:get-odl-cert aaa:get-roles
+ aaa:get-tls-protocols aaa:get-users aaa:import-keystores aaa:remove-domain
+ aaa:remove-grant aaa:remove-role aaa:remove-user
+
+Add a User
+^^^^^^^^^^
+
+The *add-user* command allows for adding an OpenDaylight user. The following
+user parameters can be specified.
+
+::
+
+ aaa:add-user --name <user name>
+ --roleName <role>
+ --userDescription <user description>
+ --email <user email>
+ --domainName <domain name>
+
+List available Users
+^^^^^^^^^^^^^^^^^^^^
+
+The *get-users* command list all the available users within the Controller.
+
+::
+
+ aaa:get-users
+
+ user
+ admin
+
+Remove a User
+^^^^^^^^^^^^^
+
+The *remove-user* command allows for removing an OpenDaylight user. The command
+needs the user name as parameter.
+
+::
+
+ aaa:remove-user --name <user name>
+
+Change the OpenDaylight user password
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The *change-user-pwd* command allows for changing the OpenDaylight user's
+password. It takes the user name as argument then will ask for the given user
+current password.
+
+::
+
+ aaa:change-user-pwd -user admin
+ Enter current password:
+ Enter new password:
+ admin's password has been changed
+
+Add a Role
+^^^^^^^^^^
+
+The *add-role* command allows for adding a role to the Controller.
+
+::
+
+ aaa:add-role --name <role name>
+ --desc <role description>
+ --domainName <domain name>
+
+List available Roles
+^^^^^^^^^^^^^^^^^^^^
+
+The *get-roles* command list all the available roles within the controller.
+
+::
+
+ aaa:get-roles
+
+ user
+ admin
+
+Remove a Role
+^^^^^^^^^^^^^
+
+The *remove-role* command allows for removing an OpenDaylight role. The command
+needs the role name as parameter. The role will be removed from those users who
+have it.
+
+::
+
+ aaa:remove-role --name <role name>
+
+Add a Domain
+^^^^^^^^^^^^
+
+The *add-domain* command allows for adding a domain to the Controller.
+
+::
+
+ aaa:add-domain --name <domain name>
+ --desc <domain description>
+
+List available Domains
+^^^^^^^^^^^^^^^^^^^^^^
+
+The *get-domains* command list all the available domains within the controller.
+The system asks for the administrator credentials to execute this command.
+
+::
+
+ aaa:get-domains
+
+ sdn
+
+Remove a Domain
+^^^^^^^^^^^^^^^
+
+The *remove-domain* command allows for removing an OpenDaylight role. The command
+needs the domain name as parameter.
+
+::
+
+ aaa:remove-domain --name <domain name>
+
+Add a Grant
+^^^^^^^^^^^
+
+The *add-grant* command allows for creating a grant for an existing user. The
+command returns a grant id for that user.
+
+::
+
+ aaa:add-grant --userName <user name>
+ --domainName <domain name>
+ --roleName <role name>
+
+Remove a Grant
+^^^^^^^^^^^^^^
+
+The *remove-grant* command allows for removing an OpenDaylight grant. This command
+needs the user name, domain and and role as parameters.
+
+::
+
+ aaa:remove-grant --userName <user name>
+ --domainName <domain name>
+ --roleName <role name>
+
+Generate Certificate Request
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Generate certificate request command will generate a certificate request based
+on the generated OpenDaylight keystore and print it on the Karaf CLI. The system
+asks for the keystore password.
+
+::
+
+ aaa:gen-cert-req
+
+ -----BEGIN CERTIFICATE REQUEST-----
+ MIIBlzCCAQACAQAwWTELMAkGA1UEBhMCQ0ExFDASBgNVBAcMC1FDIE1vbnRyZWFsMRgwFgYDVQQKDA
+ 9MaW51eEZvdW5kYXRpb24xDDAKBgNVBAsMA0RldjEMMAoGA1UEAwwDT0RMMIGfMA0GCSqGSIb3DQEB
+ AQUAA4GNADCBiQKBgQCCmLW6j+JLYJM5yAMwscw/CHqPnp5elPa1YtQsHKEAvp1I+mLVtHKZeXeteA
+ kyp6ORxw6KQ515fcDyQVrRJiSM15jUd27UaFq5ku0+qJeG+Qh2btx+cvNSE7/+cgUWWosKz4Aff5F5
+ FqR62jLUTNzqCvoaTbZaOnLYVq+O2dYyZwIDAQABMA0GCSqGSIb3DQEBBQUAA4GBADhDr4Jm7gVm/o
+ p861/FShyw1ZZscxOEl2TprJZiTO6sn3sLptQZv8v52Z+Jm5dAgr7L46c97Xfa+0j6Y4LXNb0f88lL
+ RG8PxGbk6Tqbjqc0WS+U1Ibc/rcPK4HEN/bcYCn+Na1gLBaFXUPg08ozG6MwqFNeS5Z0jz1W0D9/oiao
+ -----END CERTIFICATE REQUEST-----
+
+Get OpenDaylight Certificate
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The *get-odl-certificate* command will print the OpenDaylight certificate at the
+Karaf CLI. The system asks for the keystore password.
+
+::
+
+ aaa:get-odl-cert -storepass <store_password>
+
+ -----BEGIN CERTIFICATE-----
+ MIICKTCCAZKgAwIBAgIEI75RWDANBgkqhkiG9w0BAQUFADBZMQwwCgYDVQQDDANPREwxDDAKBgNVBA
+ sMA0RldjEYMBYGA1UECgwPTGludXhGb3VuZGF0aW9uMRQwEgYDVQQHDAtRQyBNb250cmVhbDELMAkG
+ A1UEBhMCQ0EwHhcNMTYxMTMwMTYyNDE3WhcNMTcxMTMwMTYyNDE3WjBZMQwwCgYDVQQDDANPREwxDD
+ AKBgNVBAsMA0RldjEYMBYGA1UECgwPTGludXhGb3VuZGF0aW9uMRQwEgYDVQQHDAtRQyBNb250cmVh
+ bDELMAkGA1UEBhMCQ0EwgZ8wDQYJKoZIhvcNAQEBBQADgY0AMIGJAoGBAIKYtbqP4ktgkznIAzCxzD
+ 8Ieo+enl6U9rVi1CwcoQC+nUj6YtW0cpl5d614CTKno5HHDopDnXl9wPJBWtEmJIzXmNR3btRoWrmS
+ 7T6ol4b5CHZu3H5y81ITv/5yBRZaiwrPgB9/kXkWpHraMtRM3OoK+hpNtlo6cthWr47Z1jJnAgMBAA
+ EwDQYJKoZIhvcNAQEFBQADgYEAL9DK/P/yEBre3Mg3bICAUAvSvZic+ydDmigWLsY4J3UzKdV2f1jI
+ s+rQTEgtlHShBf/ed546D49cp3XEzYrcxgILhGXDziCrUK0K1TiYqPTp6FLijjdydGlPpwuMyyV5Y0
+ iDiRclWuPz2fHbs8WQOWNs6VQ+WaREXtEsEC4qgSo=
+ -----END CERTIFICATE-----
+
+Get Cipher Suites
+^^^^^^^^^^^^^^^^^
+
+The *get-cipher-suites* command shows the cipher suites supported by the
+JVM used by the OpenDaylight controller in TLS communication. For example, here
+are the `Default Ciphers Suites in JDK 8 <http://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#ciphersuites>`_.
+
+::
+
+ aaa:get-cipher-suites
+
+ TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
+ TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
+ TLS_DHE_RSA_WITH_AES_256_GCM_SHA384
+
+Get TLS Protocols
+^^^^^^^^^^^^^^^^^
+
+The *get-tls-protocols* command shows the TLS protocols supported by the
+JVM used by the OpenDaylight controller. For example, the JDK 8 supports the
+following TLS protocols: TLSv1.2 (default), TLSv1.1, TLSv1 and SSLv3.
+
+::
+
+ aaa:get-tls-protocols
+
+ TLS_KRB5_WITH_RC4_128_SHA
+ TLS_KRB5_WITH_RC4_128_MD5
+ TLS_KRB5_WITH_3DES_EDE_CBC_SHA
+ TLS_KRB5_WITH_3DES_EDE_CBC_MD5
+ TLS_KRB5_WITH_DES_CBC_SHA
+
+Get Node Certificate
+^^^^^^^^^^^^^^^^^^^^
+
+The *get-node-cert* command prints a certificate for a given network node alias.
+This command is useful to check if the network node certificate has been added
+properly to the truest keystore. It takes the certificate alias as arguments.
+
+::
+
+ aaa:get-node-cert -alias ovs1
+ -----BEGIN CERTIFICATE-----
+ MIICKTCCAZKgAwIBAgIEI75RWDANBgkqhkiG9w0BAQUFADBZMQwwCgYDVQQDDANPREwxDDAKBgNVBA
+ sMA0RldjEYMBYGA1UECgwPTGludXhGb3VuZGF0aW9uMRQwEgYDVQQHDAtRQyBNb250cmVhbDELMAkG
+ A1UEBhMCQ0EwHhcNMTYxMTMwMTYyNDE3WhcNMTcxMTMwMTYyNDE3WjBZMQwwCgYDVQQDDANPREwxDD
+ AKBgNVBAsMA0RldjEYMBYGA1UECgwPTGludXhGb3VuZGF0aW9uMRQwEgYDVQQHDAtRQyBNb250cmVh
+ bDELMAkGA1UEBhMCQ0EwgZ8wDQYJKoZIhvcNAQEBBQADgY0AMIGJAoGBAIKYtbqP4ktgkznIAzCxzD
+ 8Ieo+enl6U9rVi1CwcoQC+nUj6YtW0cpl5d614CTKno5HHDopDnXl9wPJBWtEmJIzXmNR3btRoWrmS
+ 7T6ol4b5CHZu3H5y81ITv/5yBRZaiwrPgB9/kXkWpHraMtRM3OoK+hpNtlo6cthWr47Z1jJnAgMBAA
+ EwDQYJKoZIhvcNAQEFBQADgYEAL9DK/P/yEBre3Mg3bICAUAvSvZic+ydDmigWLsY4J3UzKdV2f1jI
+ s+rQTEgtlHShBf/ed546D49cp3XEzYrcxgILhGXDziCrUK0K1TiYqPTp6FLijjdydGlPpwuMyyV5Y0
+ iDiRclWuPz2fHbs8WQOWNs6VQ+WaREXtEsEC4qgSo=
+ -----END CERTIFICATE-----
+
+Export Keystores
+^^^^^^^^^^^^^^^^
+
+The *export-keystores* command exports the default MD-SAL Keystores to .jks
+files in the default directory for keystores (configuration/ssl/).
+
+::
+
+ aaa:export-keystores
+
+ Default directory for keystores is configuration/ssl/
+
+Import Keystores
+^^^^^^^^^^^^^^^^
+
+The *import-keystores* command imports the default MD-SAL Keystores. The
+keystores (odl and trust) should exist under default SSL directory
+(configuration/ssl/).
+
+.. code-block:: bash
+
+ aaa:import-keystores --trustKeystoreName <name of the trust keystore>
+ --trustKeystorePwd <password for the trust keystore>
+ --odlKeystoreName <name of the ODL keystore>
+ --odlKeystorePwd <password for the ODL keystore>
+ --odlKeystoreAlias <alias of the ODL keystore>
+ --tlsProtocols <list of TLS protocols separated by ','>
+ --cipherSuites <list of Cipher suites separated by ','>
+
+.. warning::
+
+ It is strongly recommended to run the history clear command after you execute
+ all the AAA CLI commands so Karaf logs stay clean from any adversary.
+
+ ::
+ history -c