Merge "Fix note to setting permissions for locking branch"

[docs.git] / docs / user-guide / authentication-and-authorization-services.rst

diff --git a/docs/user-guide/authentication-and-authorization-services.rst b/docs/user-guide/authentication-and-authorization-services.rst
index 10b39bf2eb61731e11aef48a4dd7e44ddca21ebe..32fcd71a4c117c75e7aa43acc314f3a8fcd10c31 100644 (file)
--- a/docs/user-guide/authentication-and-authorization-services.rst
+++ b/docs/user-guide/authentication-and-authorization-services.rst
@@ -85,7 +85,6 @@ 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
 ------------------
 
@@ -125,7 +124,7 @@ authorization schemes. There are two parent types of realms:
    -  Useful for applications in which roles determine allowed
       capabilities.
 
-OpenDaylight contains four implementations:
+OpenDaylight contains five implementations:
 
 -  TokenAuthRealm
 
@@ -169,11 +168,19 @@ OpenDaylight contains four implementations:
      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
 ^^^^^^^^^^^^^^
@@ -653,6 +660,65 @@ 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
 
+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
 ---------------------------
 
@@ -661,7 +727,7 @@ roughly similar in behavior:
 
 - Shiro-Based Authorization
 
-- MDAL-Based Dynamic Authorization
+- MDSAL-Based Dynamic Authorization
 
 .. note::
 
@@ -808,6 +874,7 @@ 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
 ----------------------