+.. _aaa-dev-guide:
+
Authentication, Authorization and Accounting (AAA) Services
===========================================================
Claim
A data set of validated assertions regarding a user, e.g. the role,
domain, name, etc.
+
IdP
Identity Provider.
^^^^^^^^
Get the code:
-::
+.. code-block:: bash
git clone https://git.opendaylight.org/gerrit/aaa
Build it:
-::
+.. code-block:: bash
cd aaa && mvn clean install
The following are basic instructions to push your contributions to the project's
GIT repository:
-::
+.. code-block:: bash
git add .
git commit -s
When deployed in a clustered environment each node needs to have its AAA user
file synchronized using out of band means.
-
How to enable AAA
-----------------
In order to provide security to a servlet, add the following to the
servlet’s web.xml file as the first filter definition:
-::
+.. code-block:: xml
<context-param>
<param-name>shiroEnvironmentClass</param-name>
based on roles.
- Useful for applications in which roles determine allowed
- cabilities.
+ capabilities.
-OpenDaylight contains four implementations:
+OpenDaylight contains five implementations:
- TokenAuthRealm
- 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.
+ - 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.
+
+ - Disabled out of the box.
+
+- KeystoneAuthRealm
+
+ - This realm authenticates OpenDaylight users against the OpenStack's
+ Keystone server by using the
+ `Keystone's Identity API v3 <https://developer.openstack.org/api-ref/identity/v3/>`_
+ or later.
+
+ - 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
^^^^^^^^^^^^^^
useful for new users. From the KARAF_HOME directory, you can run the following
command to enable the user interface:
-::
+.. code-block:: bash
java -cp ./data/cache/org.eclipse.osgi/bundles/217/1/.cp/h2-1.4.185.jar
org.h2.tools.Server -trace -pg -web -webAllowOthers -baseDir `pwd`
This is useful for setups where all LDAP users are allowed equal access.
+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 <aaa-certificate-management>` section).
+
Authorization Configuration
---------------------------
- Shiro-Based Authorization
-- MDAL-Based Dynamic Authorization
+- MDSAL-Based Dynamic Authorization
.. note::
Authorization <http://shiro.apache.org/web.html#Web-%7B%7B%5Curls%5C%7D%7D>`_
describes how to configure the Authentication feature in detail.
-.. notes::
+.. note::
The Shiro-Based Authorization that uses the *shiro.ini* URLs section to
define roles requirements is **deprecated** and **discouraged** since the
configuration, allowing different ways to listen for successful/unsuccessful
authentication attempts. Custom AuthenticationListener(s) must implement
the org.apache.shiro.authc.AuthenticationListener interface.
+
+.. _aaa-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 within your
+feature or module:
+
+1. It is assumed that there exists an already created OpenDaylight distribution
+ project following `this guide
+ <https://wiki.opendaylight.org/view/OpenDaylight_Controller:MD-SAL:Startup_Project_Archetype#Part_1_-_Build_with_a_simple_.27Example.27_module>`_.
+
+2. In the implementation bundle the following artifact must be added to its
+ *pom.xml* file as dependency.
+
+.. code-block:: xml
+
+ <dependency>
+ <groupId>org.opendaylight.aaa</groupId>
+ <artifactId>aaa-cert</artifactId>
+ <version>0.5.0-SNAPSHOT</version>
+ </dependency>
+
+3. Using the provider class in the implementation bundle needs to define a
+ variable holding the Certificate Manager Service as in the following example:
+
+.. code-block:: java
+
+ import org.opendaylight.aaa.cert.api.ICertificateManager;
+ import org.opendaylight.controller.md.sal.binding.api.DataBroker;
+
+ public class UseCertManagerExampleProvider {
+ private final DataBroker dataBroker;
+ private final ICertificateManager caManager;
+
+ public EncSrvExampleProvider(final DataBroker dataBroker, final ICertificateManager caManager) {
+ this.dataBroker = dataBroker;
+ this.caManager = caManager;
+ }
+ public SSLEngine createSSLEngine() {
+ final SSLContext sslContext = caManager.getServerContext();
+ if (sslContext != null) {
+ final SSLEngine sslEngine = sslContext.createSSLEngine();
+ sslEngine.setEnabledCipherSuites(caManager.getCipherSuites());
+ // DO the Implementation
+ return sslEngine;
+ }
+ }
+ public void init() {
+ // TODO
+ }
+ public void close() {
+ // TODO
+ }
+ }
+
+4. The Certificate Manager Service provides two main methods that are needed to
+ establish the *SSLEngine* object, *getServerContext()* and *getCipherSuites()*
+ as the above example shows. It also provides other methods such as
+ *getODLKeyStore()* and *getTrustKeyStore()* that gives access to the
+ OpenDaylight and Trust keystores.
+
+5. Now the *ICertificateManager* need to be passed as an argument to the
+ *UseCertManagerExampleProvider* within the implementation bundle blueprint
+ configuration. The following example shows how:
+
+.. code-block:: xml
+
+ <blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0"
+ xmlns:odl="http://opendaylight.org/xmlns/blueprint/v1.0.0"
+ odl:use-default-for-reference-types="true">
+ <reference id="dataBroker"
+ interface="org.opendaylight.controller.md.sal.binding.api.DataBroker"
+ odl:type="default" />
+ <reference id="aaaCertificateManager"
+ interface="org.opendaylight.aaa.cert.api.ICertificateManager"
+ odl:type="default-certificate-manager" />
+ <bean id="provider"
+ class="org.opendaylight.UseCertManagerExample.impl.UseCertManagerExampleProvider"
+ init-method="init" destroy-method="close">
+ <argument ref="dataBroker" />
+ <argument ref="aaaCertificateManager" />
+ </bean>
+ </blueprint>
+
+6. After finishing the bundle implementation the feature module needs to be
+ updated to include the *aaa-cert* feature in its feature bundle pom.xml file.
+
+.. code-block:: xml
+
+ <properties>
+ <aaa.version>0.5.0-SNAPSHOT</aaa.version>
+ </properties>
+ <dependency>
+ <groupId>org.opendaylight.aaa</groupId>
+ <artifactId>features-aaa</artifactId>
+ <version>${aaa.version}</version>
+ <classifier>features</classifier>
+ <type>xml</type>
+ </dependency>
+
+7. Now, in the feature.xml file add the Certificate Manager Service feature and
+ its repository.
+
+.. code-block:: xml
+
+ <repository>mvn:org.opendaylight.aaa/features-aaa/{VERSION}/xml/features</repository>
+
+The Certificate Manager Service feature can be included inside the
+implementation bundle feature as shown in the following example:
+
+.. code-block:: xml
+
+ <feature name='odl-UseCertManagerExample' version='${project.version}'
+ description='OpenDaylight :: UseCertManagerExample'>
+ <feature version='${mdsal.version}'>odl-mdsal-broker</feature>
+ <feature version='${aaa.version}'>odl-aaa-cert</feature>
+ <bundle>mvn:org.opendaylight.UseCertManagerExample/UseCertManagerExample-impl/{VERSION}</bundle>
+ </feature>
+
+8. Now the project can be built and the OpenDaylight distribution started to
+ continue with the configuration process. See the User Guide for more details.
+
+Encryption Service
+------------------
+
+The **AAA Encryption Service** is used to encrypt the OpenDaylight users'
+passwords and TLS communication certificates. This section shows how to use the
+AAA Encryption Service with an OpenDaylight distribution project to encrypt data.
+
+1. It is assumed that there exists an already created OpenDaylight distribution
+ project following `this guide
+ <https://wiki.opendaylight.org/view/OpenDaylight_Controller:MD-SAL:Startup_Project_Archetype#Part_1_-_Build_with_a_simple_.27Example.27_module>`_.
+
+2. In the implementation bundle the following artifact must be added to its
+ *pom.xml* file as dependency.
+
+.. code-block:: xml
+
+ <dependency>
+ <groupId>org.opendaylight.aaa</groupId>
+ <artifactId>aaa-encrypt-service</artifactId>
+ <version>0.5.0-SNAPSHOT</version>
+ </dependency>
+
+3. Using the provider class in the implementation bundle needs to define a
+ variable holding the Encryption Service as in the following example:
+
+.. code-block:: java
+
+ import org.opendaylight.aaa.encrypt.AAAEncryptionService;
+ import org.opendaylight.controller.md.sal.binding.api.DataBroker;
+
+ public class EncSrvExampleProvider {
+ private final DataBroker dataBroker;
+ private final AAAEncryptionService encryService;
+
+ public EncSrvExampleProvider(final DataBroker dataBroker, final AAAEncryptionService encryService) {
+ this.dataBroker = dataBroker;
+ this.encryService = encryService;
+ }
+ public void init() {
+ // TODO
+ }
+ public void close() {
+ // TODO
+ }
+ }
+
+The AAAEncryptionService can be used to encrypt and decrypt any data based on
+project's needs.
+
+4. Now the *AAAEncryptionService* needs to be passed as an argument to the
+ *EncSrvExampleProvider* within the implementation bundle blueprint
+ configuration. The following example shows how:
+
+.. code-block:: xml
+
+ <blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0"
+ xmlns:odl="http://opendaylight.org/xmlns/blueprint/v1.0.0"
+ odl:use-default-for-reference-types="true">
+ <reference id="dataBroker"
+ interface="org.opendaylight.controller.md.sal.binding.api.DataBroker"
+ odl:type="default" />
+ <reference id="encryService" interface="org.opendaylight.aaa.encrypt.AAAEncryptionService"/>
+ <bean id="provider"
+ class="org.opendaylight.EncSrvExample.impl.EncSrvExampleProvider"
+ init-method="init" destroy-method="close">
+ <argument ref="dataBroker" />
+ <argument ref="encryService" />
+ </bean>
+ </blueprint>
+
+5. After finishing the bundle implementation the feature module needs to be
+ updated to include the *aaa-encryption-service* feature in its feature bundle
+ pom.xml file.
+
+.. code-block:: xml
+
+ <dependency>
+ <groupId>org.opendaylight.aaa</groupId>
+ <artifactId>features-aaa</artifactId>
+ <version>${aaa.version}</version>
+ <classifier>features</classifier>
+ <type>xml</type>
+ </dependency>
+
+It is also necessary to add the *aaa.version* in the properties section:
+
+.. code-block:: xml
+
+ <properties>
+ <aaa.version>0.5.0-SNAPSHOT</aaa.version>
+ </properties>
+
+6. Now, in the feature.xml file add the Encryption Service feature and its
+ repository.
+
+.. code-block:: xml
+
+ <repository>mvn:org.opendaylight.aaa/features-aaa/{VERSION}/xml/features</repository>
+
+The Encryption Service feature can be included inside the implementation bundle
+feature as shown in the following example:
+
+.. code-block:: xml
+
+ <feature name='odl-EncSrvExample' version='${project.version}' description='OpenDaylight :: EncSrvExample'>
+ <feature version='${mdsal.version}'>odl-mdsal-broker</feature>
+ <feature version='${aaa.version}'>odl-aaa-encryption-service</feature>
+ <feature version='${project.version}'>odl-EncSrvExample-api</feature>
+ <bundle>mvn:org.opendaylight.EncSrvExample/EncSrvExample-impl/{VERSION}</bundle>
+ </feature>
+
+7. Now the project can be built and the OpenDaylight distribution started to
+ continue with the configuration process. See the User Guide for more details.
Code Review / docs.git / blobdiff