3 Authentication, Authorization and Accounting (AAA) Services - User guide
4 ========================================================================
9 Authentication, Authorization and Accounting (AAA) is a term for a
10 framework controlling access to resources, enforcing policies to use
11 those resources and auditing their usage. These processes are the
12 fundamental building blocks for effective network management and security.
14 Authentication provides a way of identifying a user, typically by
15 having the user enter a valid user name and valid password before access
16 is granted. The process of authentication is based on each user having a unique
17 set of criteria for gaining access. The AAA framework compares a user's
18 authentication credentials with other user credentials stored in a database.
19 If the credentials match, the user is granted access to the network.
20 If the credentials don't match, authentication fails and access is denied.
22 Authorization is the process of finding out what an authenticated user is
23 allowed to do within the system, which tasks can do, which API can call, etc.
24 The authorization process determines whether the user has the authority
25 to perform such actions.
27 Accounting is the process of logging the activity of an authenticated user,
28 for example, the amount of data a user has sent and/or received during a
29 session, which APIs called, etc.
35 Authentication, Authorization and Accounting.
38 A claim of access to a group of resources on the controller.
41 A group of resources, direct or indirect, physical, logical, or
42 virtual, for the purpose of access control.
45 A person who either owns or has access to a resource or group of
46 resources on the controller.
49 Opaque representation of a set of permissions, which is merely a
50 unique string as admin or guest.
53 Proof of identity such as user name and password, OTP, biometrics, or
57 A service or application that requires access to the controller.
60 A data set of validated assertions regarding a user, e.g. the role,
64 It is the entity associating a user with his role and domain.
70 Transport Layer Security
73 Command Line Interface
75 Security Framework for AAA services
76 -----------------------------------
78 Since Boron release, the OpenDaylight's AAA services are based on the
79 `Apache Shiro <https://shiro.apache.org/>`_ Java Security Framework. The main
80 configuration file for AAA is located at “etc/shiro.ini” relative to the
81 OpenDaylight Karaf home directory.
87 AAA is enabled through installing the odl-aaa-shiro feature. The vast majority
88 of OpenDaylight's northbound APIs (and all RESTCONF APIs) are protected by AAA
89 by default when installing the +odl-restconf+ feature, since the odl-aaa-shiro
90 is automatically installed as part of them. In the cases that APIs are *not*
91 protected by AAA, this will be noted in the per-project release notes.
96 Edit the “etc/opendaylight/datastore/initial/config/aaa-app-config.xml” file and replace the following:
108 Then restart the Karaf process.
113 AAA plugin utilizes the Shiro Realms to support pluggable authentication &
114 authorization schemes. There are two parent types of realms:
116 - AuthenticatingRealm
118 - Provides no Authorization capability.
120 - Users authenticated through this type of realm are treated
125 - AuthorizingRealm is a more sophisticated AuthenticatingRealm,
126 which provides the additional mechanisms to distinguish users
129 - Useful for applications in which roles determine allowed
132 OpenDaylight contains five implementations:
136 - An AuthorizingRealm built to bridge the Shiro-based AAA service
137 with the h2-based AAA implementation.
139 - Exposes a RESTful web service to manipulate IdM policy on a
140 per-node basis. If identical AAA policy is desired across a
141 cluster, the backing data store must be synchronized using an out
144 - A python script located at “etc/idmtool” is included to help
145 manipulate data contained in the TokenAuthRealm.
147 - Enabled out of the box. This is the realm configured by default.
151 - An AuthorizingRealm built to extract identity information from IdM
152 data contained on an LDAP server.
154 - Extracts group information from LDAP, which is translated into
157 - Useful when federating against an existing LDAP server, in which
158 only certain types of users should have certain access privileges.
160 - Disabled out of the box.
162 - ODLJndiLdapRealmAuthNOnly
164 - The same as ODLJndiLdapRealm, except without role extraction.
165 Thus, all LDAP users have equal authentication and authorization
168 - Disabled out of the box.
170 - ODLActiveDirectoryRealm
172 - Wraps the generic ActiveDirectoryRealm provided by Shiro. This allows for
173 enhanced logging as well as isolation of all realms in a single package,
174 which enables easier import by consuming servlets.
178 - This realm authenticates OpenDaylight users against the OpenStack’s
181 - Disabled out of the box.
185 More than one Realm implementation can be specified. Realms are attempted
186 in order until authentication succeeds or all realm sources are exhausted.
187 Edit the **securityManager.realms = $tokenAuthRealm** property in shiro.ini
188 and add all the realms needed separated by commas.
196 The TokenAuthRealm is the default Authorization Realm deployed in OpenDaylight.
197 TokenAuthRealm uses a direct authentication mechanism as shown in the following
200 .. figure:: ./images/aaa/direct-authentication.png
201 :alt: TokenAuthRealm direct authentication mechanism
203 TokenAuthRealm direct authentication mechanism
205 A user presents some credentials (e.g., username/password) directly to the
206 OpenDaylight controller and receives a session cookie, which can be then
207 used to access protected resources on the controller.
209 Configuring TokenAuthRealm
210 ~~~~~~~~~~~~~~~~~~~~~~~~~~
212 The TokenAuthRealm stores IdM data in an h2 database on each node. Thus,
213 configuration of a cluster currently requires configuring the desired IdM policy
214 on each node. There are two supported methods to manipulate the TokenAuthRealm
217 - idmtool configuration tool
219 - RESTful Web Service configuration
224 A utility script located at “karaf/target/assembly/bin/idmtool” is used to manipulate the
225 TokenAuthRealm IdM policy. idmtool assumes a single domain, the default one
226 (sdn), since multiple domains are not supported in the Boron release. General
227 usage information for idmtool is derived through issuing the following command:
232 usage: idmtool [-h] [--target-host TARGET_HOST] [-k]
234 {list-users,add-user,change-password,delete-user,list-domains,list-roles,add-role,delete-role,add-grant,get-grants,delete-grant,
235 change-jolokia-password}
238 positional arguments:
239 user username for ODL node
240 {list-users,add-user,change-password,delete-user,list-domains,list-roles,add-role,delete-role,add-grant,get-grants,delete-grant,
241 change-jolokia-password}
243 list-users list all users
245 change-password change a password
246 delete-user delete a user
247 list-domains list all domains
248 list-roles list all roles
250 delete-role delete a role
251 add-grant add a grant
252 get-grants get grants for userid on sdn
253 delete-grant delete a grant
254 change-jolokia-password
255 change the jolokia specific password
258 -h, --help show this help message and exit
259 --target-host TARGET_HOST
260 target host url in form protocol://host:port
261 -k, --insecure disable HTTPS certificate verification
269 python3 idmtool admin add-user newUser
270 Password: (default "admin")
275 Operation Successful!!
283 "password": "**********",
284 "salt": "**********",
285 "userid": "newUser@sdn"
290 AAA redacts the password and salt fields for security purposes.
297 $ python3 idmtool admin delete-user newUser@sdn
299 delete_user(newUser@sdn)
301 Operation Successful!!
308 $ python3 idmtool admin list-users
311 http://localhost:8181/auth/v1/users
313 Operation Successful!!
318 "description": "admin user",
323 "password": "**********",
324 "salt": "**********",
325 "userid": "admin@sdn"
330 Change a user’s password
331 ''''''''''''''''''''''''
335 $ python3 idmtool admin change-password admin@sdn
339 change_password(admin)
341 Operation Successful!!
344 "description": "admin user",
349 "password": "**********",
350 "salt": "**********",
351 "userid": "admin@sdn"
359 $ python3 idmtool admin add-role network-admin
361 add_role(network-admin)
363 Operation Successful!!
368 "name": "network-admin",
369 "roleid": "network-admin@sdn"
377 $ python3 idmtool admin delete-role network-admin@sdn
379 delete_role(network-admin@sdn)
381 Operation Successful!!
388 $ python3 idmtool admin list-roles
391 http://localhost:8181/auth/v1/roles
393 Operation Successful!!
398 "description": "a role for admins",
401 "roleid": "admin@sdn"
404 "description": "a role for users",
417 $ python3 idmtool admin list-domains
420 http://localhost:8181/auth/v1/domains
422 Operation Successful!!
427 "description": "default odl sdn domain",
440 $ python3 idmtool admin add-grant newUser@sdn admin@sdn
442 add_grant(userid=newUser@sdn,roleid=admin@sdn)
444 Operation Successful!!
448 "grantid": "newUser@sdn@admin@sdn@sdn",
449 "roleid": "admin@sdn",
450 "userid": "newUser@sdn"
458 $ python3 idmtool admin delete-grant newUser@sdn admin@sdn
460 http://localhost:8181/auth/v1/domains/sdn/users/newUser@sdn/roles/admin@sdn
461 delete_grant(userid=newUser@sdn,roleid=admin@sdn)
463 Operation Successful!!
465 Get grants for a user
466 '''''''''''''''''''''
470 python3 idmtool admin get-grants admin@sdn
472 get_grants(admin@sdn)
473 http://localhost:8181/auth/v1/domains/sdn/users/admin@sdn/roles
475 Operation Successful!!
480 "description": "a role for users",
486 "description": "a role for admins",
489 "roleid": "admin@sdn"
494 **Configuration using the RESTful Web Service**
495 ###############################################
497 The TokenAuthRealm IdM policy is fully configurable through a RESTful
498 web service. Few examples are included in this guide:
505 curl --request GET 'http://localhost:8181/auth/v1/users' --header 'Authorization: Basic YWRtaW46YWRtaW4='
510 "userid": "admin@sdn",
512 "description": "admin user",
515 "password": "**********",
516 "salt": "**********",
527 curl --request POST 'http://localhost:8181/auth/v1/users' \
528 --header 'Authorization: Basic YWRtaW46YWRtaW4=' \
529 --header 'Content-Type: application/json' \
534 "description": "Ryan'\''s User Account",
535 "email": "ryandgoulding@gmail.com"
540 "userid": "ryan@sdn",
542 "description": "Ryan's User Account",
544 "email": "ryandgoulding@gmail.com",
545 "password": "**********",
546 "salt": "**********",
550 Get grants for the new 'ryan' user
551 ''''''''''''''''''''''''''''''''''
555 curl --request GET 'http://localhost:8181/auth/v1/domains/sdn/users/ryan@sdn/roles' \
556 --header 'Authorization: Basic YWRtaW46YWRtaW4='
563 Add admin grants for the 'ryan' user
564 ''''''''''''''''''''''''''''''''''''
568 curl --request POST 'http://localhost:8181/auth/v1/domains/sdn/users/ryan@sdn/roles' \
569 --header 'Authorization: Basic YWRtaW46YWRtaW4=' \
570 --header 'Content-Type: application/json' \
572 "roleid": "admin@sdn",
574 "description": "a role for admins",
580 "grantid": "ryan@sdn@admin@sdn@sdn",
582 "userid": "ryan@sdn",
583 "roleid": "admin@sdn"
586 Remove admin grants for the 'ryan' user
587 '''''''''''''''''''''''''''''''''''''''
591 curl --request DELETE 'http://localhost:8181/auth/v1/domains/sdn/users/ryan@sdn/roles/admin@sdn' \
592 --header 'Authorization: Basic YWRtaW46YWRtaW4='
601 curl --request GET 'http://localhost:8181/auth/v1/domains' --header 'Authorization: Basic YWRtaW46YWRtaW4='
609 "description": "default odl sdn domain",
615 Create a new 'test' domain
616 ''''''''''''''''''''''''''
620 curl --request POST 'http://localhost:8181/auth/v1/domains' \
621 --header 'Authorization: Basic YWRtaW46YWRtaW4=' \
622 --header 'Content-Type: application/json' \
625 "description": "Odl test domain",
633 "description": "Odl test domain",
638 **Token Store Configuration Parameters**
639 ########################################
641 Edit the file “etc/opendaylight/karaf/08-authn-config.xml” and edit the
642 following: .\ **timeToLive**: Configure the maximum time, in milliseconds,
643 that tokens are to be cached. Default is 360000. Save the file.
651 LDAP integration is provided in order to externalize identity
652 management. This configuration allows federation with an external LDAP server.
653 The user’s OpenDaylight role parameters are mapped to corresponding LDAP
654 attributes as specified by the groupRolesMap. Thus, an LDAP operator can
655 provision attributes for LDAP users that support different OpenDaylight role
658 Configuring ODLJndiLdapRealm
659 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
661 To configure LDAP parameters, modify "etc/shiro.ini"
662 parameters to include the ODLJndiLdapRealm:
666 # OpenDaylight provides a few LDAP implementations, which are disabled out of the box.
667 # ODLJndiLdapRealm includes authorization functionality based on LDAP elements
668 # extracted through and LDAP search. This requires a bit of knowledge about
669 # how your LDAP system is setup. An example is provided below:
670 ldapRealm = org.opendaylight.aaa.shiro.realm.ODLJndiLdapRealm
671 ldapRealm.userDnTemplate = uid={0},ou=People,dc=DOMAIN,dc=TLD
672 ldapRealm.contextFactory.url = ldap://<URL>:389
673 ldapRealm.searchBase = dc=DOMAIN,dc=TLD
674 ldapRealm.ldapAttributeForComparison = objectClass
675 ldapRealm.groupRolesMap = "Person":"admin"
677 # further down in the file...
678 # Stacked realm configuration; realms are round-robbined until authentication succeeds or realm sources are exhausted.
679 securityManager.realms = $tokenAuthRealm, $ldapRealm
681 ODLJndiLdapRealmAuthNOnly
682 ^^^^^^^^^^^^^^^^^^^^^^^^^
687 This is useful for setups where all LDAP users are allowed equal access.
689 Configuring ODLJndiLdapRealmAuthNOnly
690 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
692 Edit the "etc/shiro.ini" file and modify the following:
696 ldapRealm = org.opendaylight.aaa.shiro.realm.ODLJndiLdapRealm
697 ldapRealm.userDnTemplate = uid={0},ou=People,dc=DOMAIN,dc=TLD
698 ldapRealm.contextFactory.url = ldap://<URL>:389
700 # further down in the file...
701 # Stacked realm configuration; realms are round-robbined until authentication succeeds or realm sources are exhausted.
702 securityManager.realms = $tokenAuthRealm, $ldapRealm
710 This realm authenticates OpenDaylight users against the OpenStack's Keystone
711 server. This realm uses the
712 `Keystone's Identity API v3 <https://developer.openstack.org/api-ref/identity/v3/>`_
715 .. figure:: ./images/aaa/keystonerealm-authentication.png
716 :alt: KeystoneAuthRealm authentication mechanism
718 KeystoneAuthRealm authentication/authorization mechanism
720 As can shown on the above diagram, once configured, all the RESTCONF APIs calls
721 will require sending **user**, **password** and optionally **domain** (1). Those
722 credentials are used to authenticate the call against the Keystone server (2) and,
723 if the authentication succeeds, the call will proceed to the MDSAL (3). The
724 credentials must be provisioned in advance within the Keystone Server. The user
725 and password are mandatory, while the domain is optional, in case it is not
726 provided within the REST call, the realm will default to (**Default**),
727 which is hard-coded. The default domain can be also configured through the
728 *shiro.ini* file (see the :doc:`AAA User Guide <user-guide>`).
730 The protocol between the Controller and the Keystone Server (2) can be either
731 HTTPS or HTTP. In order to use HTTPS the Keystone Server's certificate
732 must be exported and imported on the Controller (see the :ref:`Certificate Management <certificate-management>` section).
734 Configuring KeystoneAuthRealm
735 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
737 Edit the "etc/shiro.ini" file and modify the following:
741 # The KeystoneAuthRealm allows for authentication/authorization against an
742 # OpenStack's Keystone server. It uses the Identity's API v3 or later.
743 keystoneAuthRealm = org.opendaylight.aaa.shiro.realm.KeystoneAuthRealm
744 # The URL where the Keystone server exposes the Identity's API v3 the URL
745 # can be either HTTP or HTTPS and it is mandatory for this realm.
746 keystoneAuthRealm.url = https://<host>:<port>
747 # Optional parameter to make the realm verify the certificates in case of HTTPS
748 #keystoneAuthRealm.sslVerification = true
749 # Optional parameter to set up a default domain for requests using credentials
750 # without domain, uncomment in case you want a different value from the hard-coded
752 #keystoneAuthRealm.defaultDomain = Default
754 Once configured the realm, the mandatory fields are the fully quallified name of
755 the class implementing the realm *keystoneAuthRealm* and the endpoint where the
756 Keystone Server is listening *keystoneAuthRealm.url*.
758 The optional parameter *keystoneAuthRealm.sslVerification* specifies whether the
759 realm has to verify the SSL certificate or not. The optional parameter
760 *keystoneAuthRealm.defaultDomain* allows to use a different default domain from
761 the hard-coded one *"Default"*.
763 Authorization Configuration
764 ---------------------------
766 OpenDaylight supports two authorization engines at present, both of which are
767 roughly similar in behavior:
769 - Shiro-Based Authorization
771 - MDSAL-Based Dynamic Authorization
775 The preferred mechanism for configuring AAA Authentication is the
776 MDSAL-Based Dynamic Authorization. Read the following section.
778 Shiro-Based Static Authorization
779 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
781 OpenDaylight AAA has support for Role Based Access Control (RBAC) based
782 on the Apache Shiro permissions system. Configuration of the authorization
783 system is done off-line; authorization currently cannot be configured
784 after the controller is started. The Authorization provided by this mechanism
785 is aimed towards supporting coarse-grained security policies, the MDSAL-Based
786 mechanism allows for a more robust configuration capabilities. `Shiro-based
787 Authorization <http://shiro.apache.org/web.html#Web-%7B%7B%5Curls%5C%7D%7D>`_
788 describes how to configure the Authentication feature in detail.
792 The Shiro-Based Authorization that uses the *shiro.ini* URLs section to
793 define roles requirements is **deprecated** and **discouraged** since the
794 changes made to the file are only honored on a controller restart.
796 Shiro-Based Authorization is not **cluster-aware**, so the changes made on
797 the *shiro.ini* file have to be replicated on every controller instance
798 belonging to the cluster.
800 The URL patterns are matched relative to the Servlet context leaving room
801 for ambiguity, since many endpoints may match (i.e., "/restconf/modules" and
802 "/auth/modules" would both match a "/modules/\**" rule).
804 Enable “admin” Role Based Access to the IdMLight RESTful web service
805 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
807 Edit the “etc/shiro.ini” configuration file and add “/auth/v1/\**=
808 authcBasic, roles[admin]” above the line “/\** = authcBasic” within the
813 /auth/v1/** = authcBasic, roles[admin]
816 This will restrict the idmlight rest endpoints so that a grant for admin
817 role must be present for the requesting user.
821 The ordering of the authorization rules above is important!
823 MDSAL-Based Dynamic Authorization
824 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
825 The MDSAL-Based Dynamic authorization uses the MDSALDynamicAuthorizationFilter
826 engine to restrict access to particular URL endpoint patterns. Users may define
827 a list of policies that are insertion-ordered. Order matters for that list of
828 policies, since the first matching policy is applied. This choice was made to
829 emulate behavior of the Shiro-Based Authorization mechanism.
831 A **policy** is a key/value pair, where the key is a **resource**
832 (i.e., a "URL pattern") and the value is a list of **permissions** for the
833 resource. The following describes the various elements of a policy:
835 - **Resource**: the resource is a string URL pattern as outlined by
836 Apache Shiro. For more information, see http://shiro.apache.org/web.html.
838 - **Description**: an optional description of the URL endpoint and why it is
841 - **Permissions list**: a list of permissions for a particular policy. If more
842 than one permission exists in the permissions list they are evaluated using
843 logical "OR". A permission describes the prerequisites to perform HTTP
844 operations on a particular endpoint. The following describes the various
845 elements of a permission:
847 + **Role**: the role required to access the target URL endpoint.
848 + **Actions list**: a leaf-list of HTTP permissions that are allowed for a
849 Subject possessing the required role.
851 This an example on how to limit access to the modules endpoint:
856 put URL: /rests/data/aaa:http-authorization/policies
858 headers: Content-Type: application/json Accept: application/json
865 "aaa:resource": "/restconf/modules/**",
884 The above example locks down access to the modules endpoint (and any URLS
885 available past modules) to the "admin" role. Thus, an attempt from the OOB
886 *admin* user will succeed with 2XX HTTP status code, while an attempt from the
887 OOB *user* user will fail with HTTP status code 401, as the user *user* is not
888 granted the "admin" role.
890 Accounting Configuration
891 ------------------------
893 Accounting is handled through the standard slf4j logging mechanisms used by the
894 rest of OpenDaylight. Thus, one can control logging verbosity through
895 manipulating the log levels for individual packages and classes directly through
896 the Karaf console, JMX, or etc/org.ops4j.pax.logging.cfg. In normal operations,
897 the default levels exposed do not provide much information about AAA services;
898 this is due to the fact that logging can severely degrade performance.
900 All AAA logging is output to the standard karaf.log file. For debugging purposes
901 (i.e., to enable maximum verbosity), issue the following command:
905 log:set TRACE org.opendaylight.aaa
907 Enable Successful/Unsuccessful Authentication Attempts Logging
908 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
910 By default, successful/unsuccessful authentication attempts are NOT logged. This
911 is due to the fact that logging can severely decrease REST performance.
912 To enable logging of successful/unsuccessful REST attempts, issue the following
913 command in Karaf's console:
917 log:set DEBUG org.opendaylight.aaa.shiro.filters.AuthenticationListener
919 It is possible to add custom AuthenticationListener(s) to the Shiro-based
920 configuration, allowing different ways to listen for successful/unsuccessful
921 authentication attempts. Custom AuthenticationListener(s) must implement
922 the org.apache.shiro.authc.AuthenticationListener interface.
924 .. _certificate-management:
926 Certificate Management
927 ----------------------
929 The **Certificate Management Service** is used to manage the keystores and
930 certificates at the OpenDaylight distribution to easily provides the TLS
933 The Certificate Management Service managing two keystores:
935 1. **OpenDaylight Keystore** which holds the OpenDaylight distribution
936 certificate self sign certificate or signed certificate from a root CA based
937 on generated certificate request.
939 2. **Trust Keystore** which holds all the network nodes certificates that shall
940 to communicate with the OpenDaylight distribution through TLS communication.
942 The Certificate Management Service stores the keystores (OpenDaylight & Trust)
943 as *.jks* files under configuration/ssl/ directory. Also the keystores
944 could be stored at the MD-SAL datastore in case OpenDaylight distribution
945 running at cluster environment. When the keystores are stored at MD-SAL,
946 the Certificate Management Service rely on the **Encryption-Service** to encrypt
947 the keystore data before storing it to MD-SAL and decrypted at runtime.
949 How to use the Certificate Management Service to manage the TLS communication
950 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
952 The following are the steps to configure the TLS communication:
954 1. After starting the distribution, the *odl-aaa-cert* feature has to get
955 installed. Use the following command at Karaf CLI to check.
959 opendaylight-user@root>feature:list -i | grep aaa-cert
960 odl-aaa-cert | 0.5.0-SNAPSHOT | x | odl-aaa-0.5.0-SNAPSHOT | OpenDaylight :: AAA :: aaa certificate Service
962 2. The initial configuration of the Certificate Manager Service exists under
963 the distribution directory etc/opendaylight/datastore/initial/config/aaa-cert-config.xml.
967 <aaa-cert-service-config xmlns="urn:opendaylight:yang:aaa:cert">
968 <use-config>false</use-config>
969 <use-mdsal>false</use-mdsal>
970 <bundle-name>opendaylight</bundle-name>
973 <alias>controller</alias>
975 <dname>CN=ODL, OU=Dev, O=LinuxFoundation, L=QC Montreal, C=CA</dname>
976 <validity>365</validity>
977 <key-alg>RSA</key-alg>
978 <sign-alg>SHA1WithRSAEncryption</sign-alg>
979 <keysize>1024</keysize>
985 <name>truststore.jks</name>
988 </aaa-cert-service-config>
991 Now as it is explained above, the Certificate Manager Service support two mode
992 of operations; cluster mode and single mode. To use the single mode change the
993 use-config to true and it is recommended as long as there is no need for
994 cluster environment. To use the cluster mode change the use-config and
995 use-mdsal configurations to true and the keystores will be stored and shard
996 across the cluster nodes within the MD-SAL datastore.
998 The initial password become randomly generated when the *aaa-cert* feature is
1001 The cipher suites can be restricted by changing the **<cipher-suites>**
1002 configuration, however, the JDK has to be upgraded by installing the `Java
1003 Cryptography Extension
1004 <http://www.oracle.com/technetwork/java/javase/downloads/jce8-download-2133166.html>`_
1010 <suite-name>TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384</suite-name>
1013 <suite-name>TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384</suite-name>
1016 <suite-name>TLS_DHE_RSA_WITH_AES_256_GCM_SHA384</suite-name>
1019 3. The new configurations will take affect after restarting the distribution.
1021 4. Now to add or get certificate to the OpenDaylight and Trust keystores, the
1022 Certificate Manager Service provides the following RPCs.
1026 a) Set the node certificate that will communicate with OpeDaylight through TLS
1028 POST /operations/aaa-cert-rpc:setNodeCertifcate
1031 "node-cert": "string",
1032 "node-alias": "string"
1038 b) Get the node certificate based on node alias.
1039 POST /operations/aaa-cert-rpc:getNodeCertifcate
1042 "node-alias": "string"
1048 c) Get the OpeDaylight keystore certificate.
1049 POST /operations/aaa-cert-rpc:getODLCertificate
1058 d) Generate a certificate request from the OpeDaylight keystore to be signed
1060 POST /operations/aaa-cert-rpc:getODLCertificateReq
1063 odl-cert-req "string"
1069 e) Set the OpeDaylight certificate, the certificate should be generated
1070 based on a certificate request generated from the ODL keystore otherwise the
1071 certificated will not be added.
1072 POST /operations/aaa-cert-rpc:setODLCertificate
1075 "odl-cert-alias": "string",
1076 "odl-cert": "string"
1082 The Certificate Manager Service RPCs are allowed only to the Role Admin Users
1083 and it could be completely disabled through the shiro.ini config file. Check
1084 the URL section at the shiro.ini.
1089 The **AAA Encryption Service** is used to encrypt the OpenDaylight's users'
1090 passwords and TLS communication certificates. This section shows how to use the
1091 AAA Encryption Service with an OpenDaylight distribution project to encrypt data.
1093 The following are the steps to configure the Encryption Service:
1095 1. After starting the distribution, the *aaa-encryption-service* feature has to
1096 get installed. Use the following command at Karaf CLI to check.
1098 .. code-block:: bash
1100 opendaylight-user@root>feature:list -i | grep aaa-encryption-service
1101 odl-aaa-encryption-service | 0.5.0-SNAPSHOT | x | odl-aaa-0.5.0-SNAPSHOT | OpenDaylight :: AAA :: Encryption Service
1103 2. The initial configuration of the Encryption Service exists under the
1104 distribution directory etc/opendaylight/datastore/initial/config/aaa-encrypt-service-config.xml
1108 <aaa-encrypt-service-config xmlns="config:aaa:authn:encrypt:service:config">
1111 <encrypt-method>PBKDF2WithHmacSHA1</encrypt-method>
1112 <encrypt-type>AES</encrypt-type>
1113 <encrypt-iteration-count>32768</encrypt-iteration-count>
1114 <encrypt-key-length>128</encrypt-key-length>
1115 <cipher-transforms>AES/CBC/PKCS5Padding</cipher-transforms>
1116 </aaa-encrypt-service-config>
1120 Both the initial encryption key and encryption salt become randomly generated
1121 when the *aaa-encryption-service* feature is installed.
1123 3. Finally the new configurations will take affect after restarting the
1126 Using the AAA Command Line Interface (CLI)
1127 ------------------------------------------
1128 The AAA offers a CLI through the Karaf's console. This CLI allows the user to
1129 configure and use some of the functionalities provided by AAA.
1131 The AAA CLI exists under the **odl-aaa-cli** feature. This feature can be
1132 installed by executing the following command.
1136 feature:install odl-aaa-cli
1138 To check that the installation of the feature succeeded type "aaa" and press
1139 *tab* to see the list of available commands under the *aaa* scope.
1143 opendaylight-user@root>aaa:
1144 aaa:add-domain aaa:add-grant aaa:add-role aaa:add-user
1145 aaa:change-user-pwd aaa:export-keystores aaa:gen-cert-req aaa:get-cipher-suites
1146 aaa:get-domains aaa:get-node-cert aaa:get-odl-cert aaa:get-roles
1147 aaa:get-tls-protocols aaa:get-users aaa:import-keystores aaa:remove-domain
1148 aaa:remove-grant aaa:remove-role aaa:remove-user
1153 The *add-user* command allows for adding an OpenDaylight user. The following
1154 user parameters can be specified.
1158 aaa:add-user --userName <user name>
1160 --userDescription <user description>
1161 --userEmail <user email>
1162 --domainName <domain name>
1164 List available Users
1165 ^^^^^^^^^^^^^^^^^^^^
1167 The *get-users* command list all the available users within the Controller.
1179 The *remove-user* command allows for removing an OpenDaylight user. The command
1180 needs the user name as parameter.
1184 aaa:remove-user --name <user name>
1186 Change the OpenDaylight user password
1187 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1189 The *change-user-pwd* command allows for changing the OpenDaylight user's
1190 password. It takes the user name as argument then will ask for the given user
1195 aaa:change-user-pwd --userName admin
1196 Enter current password:
1198 admin's password has been changed
1203 The *add-role* command allows for adding a role to the Controller.
1207 aaa:add-role --roleName <role name>
1208 --roleDescription <role description>
1209 --domainName <domain name>
1211 List available Roles
1212 ^^^^^^^^^^^^^^^^^^^^
1214 The *get-roles* command list all the available roles within the controller.
1226 The *remove-role* command allows for removing an OpenDaylight role. The command
1227 needs the role name as parameter. The role will be removed from those users who
1232 aaa:remove-role --roleName <role name>
1237 The *add-domain* command allows for adding a domain to the Controller.
1241 aaa:add-domain --domainName <domain name>
1242 --domainDescription <domain description>
1244 List available Domains
1245 ^^^^^^^^^^^^^^^^^^^^^^
1247 The *get-domains* command list all the available domains within the controller.
1248 The system asks for the administrator credentials to execute this command.
1259 The *remove-domain* command allows for removing an OpenDaylight role. The command
1260 needs the domain name as parameter.
1264 aaa:remove-domain --domainName <domain name>
1269 The *add-grant* command allows for creating a grant for an existing user. The
1270 command returns a grant id for that user.
1274 aaa:add-grant --userName <user name>
1275 --domainName <domain name>
1276 --roleName <role name>
1281 The *remove-grant* command allows for removing an OpenDaylight grant. This command
1282 needs the user name, domain and and role as parameters.
1286 aaa:remove-grant --userName <user name>
1287 --domainName <domain name>
1288 --roleName <role name>
1290 Generate Certificate Request
1291 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1293 Generate certificate request command will generate a certificate request based
1294 on the generated OpenDaylight keystore and print it on the Karaf CLI. The system
1295 asks for the keystore password.
1301 -----BEGIN CERTIFICATE REQUEST-----
1302 MIIBlzCCAQACAQAwWTELMAkGA1UEBhMCQ0ExFDASBgNVBAcMC1FDIE1vbnRyZWFsMRgwFgYDVQQKDA
1303 9MaW51eEZvdW5kYXRpb24xDDAKBgNVBAsMA0RldjEMMAoGA1UEAwwDT0RMMIGfMA0GCSqGSIb3DQEB
1304 AQUAA4GNADCBiQKBgQCCmLW6j+JLYJM5yAMwscw/CHqPnp5elPa1YtQsHKEAvp1I+mLVtHKZeXeteA
1305 kyp6ORxw6KQ515fcDyQVrRJiSM15jUd27UaFq5ku0+qJeG+Qh2btx+cvNSE7/+cgUWWosKz4Aff5F5
1306 FqR62jLUTNzqCvoaTbZaOnLYVq+O2dYyZwIDAQABMA0GCSqGSIb3DQEBBQUAA4GBADhDr4Jm7gVm/o
1307 p861/FShyw1ZZscxOEl2TprJZiTO6sn3sLptQZv8v52Z+Jm5dAgr7L46c97Xfa+0j6Y4LXNb0f88lL
1308 RG8PxGbk6Tqbjqc0WS+U1Ibc/rcPK4HEN/bcYCn+Na1gLBaFXUPg08ozG6MwqFNeS5Z0jz1W0D9/oiao
1309 -----END CERTIFICATE REQUEST-----
1311 Get OpenDaylight Certificate
1312 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1314 The *get-odl-certificate* command will print the OpenDaylight certificate at the
1315 Karaf CLI. The system asks for the keystore password.
1319 aaa:get-odl-cert -storepass <store_password>
1321 -----BEGIN CERTIFICATE-----
1322 MIICKTCCAZKgAwIBAgIEI75RWDANBgkqhkiG9w0BAQUFADBZMQwwCgYDVQQDDANPREwxDDAKBgNVBA
1323 sMA0RldjEYMBYGA1UECgwPTGludXhGb3VuZGF0aW9uMRQwEgYDVQQHDAtRQyBNb250cmVhbDELMAkG
1324 A1UEBhMCQ0EwHhcNMTYxMTMwMTYyNDE3WhcNMTcxMTMwMTYyNDE3WjBZMQwwCgYDVQQDDANPREwxDD
1325 AKBgNVBAsMA0RldjEYMBYGA1UECgwPTGludXhGb3VuZGF0aW9uMRQwEgYDVQQHDAtRQyBNb250cmVh
1326 bDELMAkGA1UEBhMCQ0EwgZ8wDQYJKoZIhvcNAQEBBQADgY0AMIGJAoGBAIKYtbqP4ktgkznIAzCxzD
1327 8Ieo+enl6U9rVi1CwcoQC+nUj6YtW0cpl5d614CTKno5HHDopDnXl9wPJBWtEmJIzXmNR3btRoWrmS
1328 7T6ol4b5CHZu3H5y81ITv/5yBRZaiwrPgB9/kXkWpHraMtRM3OoK+hpNtlo6cthWr47Z1jJnAgMBAA
1329 EwDQYJKoZIhvcNAQEFBQADgYEAL9DK/P/yEBre3Mg3bICAUAvSvZic+ydDmigWLsY4J3UzKdV2f1jI
1330 s+rQTEgtlHShBf/ed546D49cp3XEzYrcxgILhGXDziCrUK0K1TiYqPTp6FLijjdydGlPpwuMyyV5Y0
1331 iDiRclWuPz2fHbs8WQOWNs6VQ+WaREXtEsEC4qgSo=
1332 -----END CERTIFICATE-----
1337 The *get-cipher-suites* command shows the cipher suites supported by the
1338 JVM used by the OpenDaylight controller in TLS communication. For example, here
1339 are the `Default Ciphers Suites in JDK 8 <http://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#ciphersuites>`_.
1343 aaa:get-cipher-suites
1345 TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
1346 TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
1347 TLS_DHE_RSA_WITH_AES_256_GCM_SHA384
1352 The *get-tls-protocols* command shows the TLS protocols supported by the
1353 JVM used by the OpenDaylight controller. For example, the JDK 8 supports the
1354 following TLS protocols: TLSv1.2 (default), TLSv1.1, TLSv1 and SSLv3.
1358 aaa:get-tls-protocols
1360 TLS_KRB5_WITH_RC4_128_SHA
1361 TLS_KRB5_WITH_RC4_128_MD5
1362 TLS_KRB5_WITH_3DES_EDE_CBC_SHA
1363 TLS_KRB5_WITH_3DES_EDE_CBC_MD5
1364 TLS_KRB5_WITH_DES_CBC_SHA
1366 Get Node Certificate
1367 ^^^^^^^^^^^^^^^^^^^^
1369 The *get-node-cert* command prints a certificate for a given network node alias.
1370 This command is useful to check if the network node certificate has been added
1371 properly to the truest keystore. It takes the certificate alias as arguments.
1375 aaa:get-node-cert -alias ovs1
1376 -----BEGIN CERTIFICATE-----
1377 MIICKTCCAZKgAwIBAgIEI75RWDANBgkqhkiG9w0BAQUFADBZMQwwCgYDVQQDDANPREwxDDAKBgNVBA
1378 sMA0RldjEYMBYGA1UECgwPTGludXhGb3VuZGF0aW9uMRQwEgYDVQQHDAtRQyBNb250cmVhbDELMAkG
1379 A1UEBhMCQ0EwHhcNMTYxMTMwMTYyNDE3WhcNMTcxMTMwMTYyNDE3WjBZMQwwCgYDVQQDDANPREwxDD
1380 AKBgNVBAsMA0RldjEYMBYGA1UECgwPTGludXhGb3VuZGF0aW9uMRQwEgYDVQQHDAtRQyBNb250cmVh
1381 bDELMAkGA1UEBhMCQ0EwgZ8wDQYJKoZIhvcNAQEBBQADgY0AMIGJAoGBAIKYtbqP4ktgkznIAzCxzD
1382 8Ieo+enl6U9rVi1CwcoQC+nUj6YtW0cpl5d614CTKno5HHDopDnXl9wPJBWtEmJIzXmNR3btRoWrmS
1383 7T6ol4b5CHZu3H5y81ITv/5yBRZaiwrPgB9/kXkWpHraMtRM3OoK+hpNtlo6cthWr47Z1jJnAgMBAA
1384 EwDQYJKoZIhvcNAQEFBQADgYEAL9DK/P/yEBre3Mg3bICAUAvSvZic+ydDmigWLsY4J3UzKdV2f1jI
1385 s+rQTEgtlHShBf/ed546D49cp3XEzYrcxgILhGXDziCrUK0K1TiYqPTp6FLijjdydGlPpwuMyyV5Y0
1386 iDiRclWuPz2fHbs8WQOWNs6VQ+WaREXtEsEC4qgSo=
1387 -----END CERTIFICATE-----
1392 The *export-keystores* command exports the default MD-SAL Keystores to .jks
1393 files in the default directory for keystores (configuration/ssl/).
1397 aaa:export-keystores
1399 Default directory for keystores is configuration/ssl/
1404 The *import-keystores* command imports the default MD-SAL Keystores. The
1405 keystores (odl and trust) should exist under default SSL directory
1406 (configuration/ssl/).
1408 .. code-block:: bash
1410 aaa:import-keystores --trustKeystoreName <name of the trust keystore>
1411 --trustKeystorePwd <password for the trust keystore>
1412 --odlKeystoreName <name of the ODL keystore>
1413 --odlKeystorePwd <password for the ODL keystore>
1414 --odlKeystoreAlias <alias of the ODL keystore>
1415 --tlsProtocols <list of TLS protocols separated by ','>
1416 --cipherSuites <list of Cipher suites separated by ','>
1420 It is strongly recommended to run the history clear command after you execute
1421 all the AAA CLI commands so Karaf logs stay clean from any adversary.