TLS
Transport Layer Security
+CLI
+ Command Line Interface
+
Security Framework for AAA services
-----------------------------------
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
------------------
- Useful for applications in which roles determine allowed
capabilities.
-OpenDaylight contains four implementations:
+OpenDaylight contains five implementations:
- TokenAuthRealm
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.
-
+ Edit the **securityManager.realms = $tokenAuthRealm** property in shiro.ini
+ and add all the realms needed separated by commas.
TokenAuthRealm
^^^^^^^^^^^^^^
# Stacked realm configuration; realms are round-robbined until authentication succeeds or realm sources are exhausted.
securityManager.realms = $tokenAuthRealm, $ldapRealm
+KeystoneAuthRealm
+^^^^^^^^^^^^^^^^^
+
+How it works
+~~~~~~~~~~~~
+
+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
-- MDAL-Based Dynamic Authorization
+- MDSAL-Based Dynamic Authorization
.. note::
authentication attempts. Custom AuthenticationListener(s) must implement
the org.apache.shiro.authc.AuthenticationListener interface.
+.. _certificate-management:
Certificate Management
----------------------
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.