3 Authentication, Authorization and Accounting (AAA) Services
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/shiro.ini” 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 token endpoint /oauth2/token and receives an access
207 token, which then can be 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 “etc/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:
231 $ python etc/idmtool -h
232 usage: idmtool [-h] [--target-host TARGET_HOST]
234 {list-users,add-user,change-password,delete-user,list-domains,list-roles,add-role,delete-role,add-grant,get-grants,delete-grant}
237 positional arguments:
238 user username for BSC node
239 {list-users,add-user,change-password,delete-user,list-domains,list-roles,add-role,delete-role,add-grant,get-grants,delete-grant}
241 list-users list all users
243 change-password change a password
244 delete-user delete a user
245 list-domains list all domains
246 list-roles list all roles
248 delete-role delete a role
249 add-grant add a grant
250 get-grants get grants for userid on sdn
251 delete-grant delete a grant
254 -h, --help show this help message and exit
255 --target-host TARGET_HOST
263 python etc/idmtool admin add-user newUser
278 "password": "**********",
279 "salt": "**********",
280 "userid": "newUser@sdn"
285 AAA redacts the password and salt fields for security purposes.
292 $ python etc/idmtool admin delete-user newUser@sdn
294 delete_user(newUser@sdn)
303 $ python etc/idmtool admin list-users
313 "description": "user user",
318 "password": "**********",
319 "salt": "**********",
323 "description": "admin user",
328 "password": "**********",
329 "salt": "**********",
330 "userid": "admin@sdn"
335 Change a user’s password
336 ''''''''''''''''''''''''
340 $ python etc/idmtool admin change-password admin@sdn
344 change_password(admin)
350 "description": "admin user",
355 "password": "**********",
356 "salt": "**********",
357 "userid": "admin@sdn"
365 $ python etc/idmtool admin add-role network-admin
367 add_role(network-admin)
375 "name": "network-admin",
376 "roleid": "network-admin@sdn"
384 $ python etc/idmtool admin delete-role network-admin@sdn
386 delete_role(network-admin@sdn)
395 $ python etc/idmtool admin list-roles
405 "description": "a role for admins",
408 "roleid": "admin@sdn"
411 "description": "a role for users",
424 $ python etc/idmtool admin list-domains
434 "description": "default odl sdn domain",
447 $ python etc/idmtool admin add-grant user@sdn admin@sdn
449 add_grant(userid=user@sdn,roleid=admin@sdn)
456 "grantid": "user@sdn@admin@sdn@sdn",
457 "roleid": "admin@sdn",
466 $ python etc/idmtool admin delete-grant user@sdn admin@sdn
468 http://localhost:8181/auth/v1/domains/sdn/users/user@sdn/roles/admin@sdn
469 delete_grant(userid=user@sdn,roleid=admin@sdn)
473 Get grants for a user
474 '''''''''''''''''''''
478 python etc/idmtool admin get-grants admin@sdn
480 get_grants(admin@sdn)
488 "description": "a role for users",
494 "description": "a role for admins",
497 "roleid": "admin@sdn"
502 **Configuration using the RESTful Web Service**
503 ###############################################
505 The TokenAuthRealm IdM policy is fully configurable through a RESTful
506 web service. Full documentation for manipulating AAA IdM data is located
507 online (https://wiki.opendaylight.org/images/0/00/AAA_Test_Plan.docx),
508 and a few examples are included in this guide:
515 curl -u admin:admin http://localhost:8181/auth/v1/users
520 "description": "user user",
525 "password": "**********",
526 "salt": "**********",
530 "description": "admin user",
535 "password": "**********",
536 "salt": "**********",
537 "userid": "admin@sdn"
547 curl -u admin:admin -X POST -H "Content-Type: application/json" --data-binary @./user.json http://localhost:8181/auth/v1/users
551 "userid": "ryan@sdn",
554 "description": "Ryan's User Account",
555 "email": "ryandgoulding@gmail.com"
562 "description":"Ryan's User Account",
564 "email":"ryandgoulding@gmail.com",
565 "password":"**********",
570 Create an OAuth2 Token For Admin Scoped to SDN
571 ''''''''''''''''''''''''''''''''''''''''''''''
575 curl -d 'grant_type=password&username=admin&password=a&scope=sdn' http://localhost:8181/oauth2/token
580 "token_type":"Bearer",
581 "access_token":"5a615fbc-bcad-3759-95f4-ad97e831c730"
589 curl -H "Authorization: Bearer 5a615fbc-bcad-3759-95f4-ad97e831c730" http://localhost:8181/auth/v1/domains
596 "description":"default odl sdn domain",
602 **Token Store Configuration Parameters**
603 ########################################
605 Edit the file “etc/opendaylight/karaf/08-authn-config.xml” and edit the
606 following: .\ **timeToLive**: Configure the maximum time, in milliseconds,
607 that tokens are to be cached. Default is 360000. Save the file.
615 LDAP integration is provided in order to externalize identity
616 management. This configuration allows federation with an external LDAP server.
617 The user’s OpenDaylight role parameters are mapped to corresponding LDAP
618 attributes as specified by the groupRolesMap. Thus, an LDAP operator can
619 provision attributes for LDAP users that support different OpenDaylight role
622 Configuring ODLJndiLdapRealm
623 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
625 To configure LDAP parameters, modify "etc/shiro.ini"
626 parameters to include the ODLJndiLdapRealm:
630 # OpenDaylight provides a few LDAP implementations, which are disabled out of the box.
631 # ODLJndiLdapRealm includes authorization functionality based on LDAP elements
632 # extracted through and LDAP search. This requires a bit of knowledge about
633 # how your LDAP system is setup. An example is provided below:
634 ldapRealm = org.opendaylight.aaa.shiro.realm.ODLJndiLdapRealm
635 ldapRealm.userDnTemplate = uid={0},ou=People,dc=DOMAIN,dc=TLD
636 ldapRealm.contextFactory.url = ldap://<URL>:389
637 ldapRealm.searchBase = dc=DOMAIN,dc=TLD
638 ldapRealm.ldapAttributeForComparison = objectClass
639 ldapRealm.groupRolesMap = "Person":"admin"
641 # further down in the file...
642 # Stacked realm configuration; realms are round-robbined until authentication succeeds or realm sources are exhausted.
643 securityManager.realms = $tokenAuthRealm, $ldapRealm
645 ODLJndiLdapRealmAuthNOnly
646 ^^^^^^^^^^^^^^^^^^^^^^^^^
651 This is useful for setups where all LDAP users are allowed equal access.
653 Configuring ODLJndiLdapRealmAuthNOnly
654 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
656 Edit the "etc/shiro.ini" file and modify the following:
660 ldapRealm = org.opendaylight.aaa.shiro.realm.ODLJndiLdapRealm
661 ldapRealm.userDnTemplate = uid={0},ou=People,dc=DOMAIN,dc=TLD
662 ldapRealm.contextFactory.url = ldap://<URL>:389
664 # further down in the file...
665 # Stacked realm configuration; realms are round-robbined until authentication succeeds or realm sources are exhausted.
666 securityManager.realms = $tokenAuthRealm, $ldapRealm
674 This realm authenticates OpenDaylight users against the OpenStack's Keystone
675 server. This realm uses the
676 `Keystone's Identity API v3 <https://developer.openstack.org/api-ref/identity/v3/>`_
679 .. figure:: ./images/aaa/keystonerealm-authentication.png
680 :alt: KeystoneAuthRealm authentication mechanism
682 KeystoneAuthRealm authentication/authorization mechanism
684 As can shown on the above diagram, once configured, all the RESTCONF APIs calls
685 will require sending **user**, **password** and optionally **domain** (1). Those
686 credentials are used to authenticate the call against the Keystone server (2) and,
687 if the authentication succeeds, the call will proceed to the MDSAL (3). The
688 credentials must be provisioned in advance within the Keystone Server. The user
689 and password are mandatory, while the domain is optional, in case it is not
690 provided within the REST call, the realm will default to (**Default**),
691 which is hard-coded. The default domain can be also configured through the
692 *shiro.ini* file (see the :doc:`AAA User Guide <user-guide>`).
694 The protocol between the Controller and the Keystone Server (2) can be either
695 HTTPS or HTTP. In order to use HTTPS the Keystone Server's certificate
696 must be exported and imported on the Controller (see the :ref:`Certificate Management <certificate-management>` section).
698 Configuring KeystoneAuthRealm
699 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
701 Edit the "etc/shiro.ini" file and modify the following:
705 # The KeystoneAuthRealm allows for authentication/authorization against an
706 # OpenStack's Keystone server. It uses the Identity's API v3 or later.
707 keystoneAuthRealm = org.opendaylight.aaa.shiro.realm.KeystoneAuthRealm
708 # The URL where the Keystone server exposes the Identity's API v3 the URL
709 # can be either HTTP or HTTPS and it is mandatory for this realm.
710 keystoneAuthRealm.url = https://<host>:<port>
711 # Optional parameter to make the realm verify the certificates in case of HTTPS
712 #keystoneAuthRealm.sslVerification = true
713 # Optional parameter to set up a default domain for requests using credentials
714 # without domain, uncomment in case you want a different value from the hard-coded
716 #keystoneAuthRealm.defaultDomain = Default
718 Once configured the realm, the mandatory fields are the fully quallified name of
719 the class implementing the realm *keystoneAuthRealm* and the endpoint where the
720 Keystone Server is listening *keystoneAuthRealm.url*.
722 The optional parameter *keystoneAuthRealm.sslVerification* specifies whether the
723 realm has to verify the SSL certificate or not. The optional parameter
724 *keystoneAuthRealm.defaultDomain* allows to use a different default domain from
725 the hard-coded one *"Default"*.
727 Authorization Configuration
728 ---------------------------
730 OpenDaylight supports two authorization engines at present, both of which are
731 roughly similar in behavior:
733 - Shiro-Based Authorization
735 - MDSAL-Based Dynamic Authorization
739 The preferred mechanism for configuring AAA Authentication is the
740 MDSAL-Based Dynamic Authorization. Read the following section.
742 Shiro-Based Static Authorization
743 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
745 OpenDaylight AAA has support for Role Based Access Control (RBAC) based
746 on the Apache Shiro permissions system. Configuration of the authorization
747 system is done off-line; authorization currently cannot be configured
748 after the controller is started. The Authorization provided by this mechanism
749 is aimed towards supporting coarse-grained security policies, the MDSAL-Based
750 mechanism allows for a more robust configuration capabilities. `Shiro-based
751 Authorization <http://shiro.apache.org/web.html#Web-%7B%7B%5Curls%5C%7D%7D>`_
752 describes how to configure the Authentication feature in detail.
756 The Shiro-Based Authorization that uses the *shiro.ini* URLs section to
757 define roles requirements is **deprecated** and **discouraged** since the
758 changes made to the file are only honored on a controller restart.
760 Shiro-Based Authorization is not **cluster-aware**, so the changes made on
761 the *shiro.ini* file have to be replicated on every controller instance
762 belonging to the cluster.
764 The URL patterns are matched relative to the Servlet context leaving room
765 for ambiguity, since many endpoints may match (i.e., "/restconf/modules" and
766 "/auth/modules" would both match a "/modules/\**" rule).
768 Enable “admin” Role Based Access to the IdMLight RESTful web service
769 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
771 Edit the “etc/shiro.ini” configuration file and add “/auth/v1/\**=
772 authcBasic, roles[admin]” above the line “/\** = authcBasic” within the
777 /auth/v1/** = authcBasic, roles[admin]
780 This will restrict the idmlight rest endpoints so that a grant for admin
781 role must be present for the requesting user.
785 The ordering of the authorization rules above is important!
787 MDSAL-Based Dynamic Authorization
788 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
789 The MDSAL-Based Dynamic authorization uses the MDSALDynamicAuthorizationFilter
790 engine to restrict access to particular URL endpoint patterns. Users may define
791 a list of policies that are insertion-ordered. Order matters for that list of
792 policies, since the first matching policy is applied. This choice was made to
793 emulate behavior of the Shiro-Based Authorization mechanism.
795 A **policy** is a key/value pair, where the key is a **resource**
796 (i.e., a "URL pattern") and the value is a list of **permissions** for the
797 resource. The following describes the various elements of a policy:
799 - **Resource**: the resource is a string URL pattern as outlined by
800 Apache Shiro. For more information, see http://shiro.apache.org/web.html.
802 - **Description**: an optional description of the URL endpoint and why it is
805 - **Permissions list**: a list of permissions for a particular policy. If more
806 than one permission exists in the permissions list they are evaluated using
807 logical "OR". A permission describes the prerequisites to perform HTTP
808 operations on a particular endpoint. The following describes the various
809 elements of a permission:
811 + **Role**: the role required to access the target URL endpoint.
812 + **Actions list**: a leaf-list of HTTP permissions that are allowed for a
813 Subject possessing the required role.
815 This an example on how to limit access to the modules endpoint:
820 put URL: /restconf/config/aaa:http-authorization/policies
822 headers: Content-Type: application/json Accept: application/json
827 [ { "aaa:resource": "/restconf/modules/**",
828 "aaa:permissions": [ { "aaa:role": "admin",
829 "aaa:actions": [ "get",
842 The above example locks down access to the modules endpoint (and any URLS
843 available past modules) to the "admin" role. Thus, an attempt from the OOB
844 *admin* user will succeed with 2XX HTTP status code, while an attempt from the
845 OOB *user* user will fail with HTTP status code 401, as the user *user* is not
846 granted the "admin" role.
848 Accounting Configuration
849 ------------------------
851 Accounting is handled through the standard slf4j logging mechanisms used by the
852 rest of OpenDaylight. Thus, one can control logging verbosity through
853 manipulating the log levels for individual packages and classes directly through
854 the Karaf console, JMX, or etc/org.ops4j.pax.logging.cfg. In normal operations,
855 the default levels exposed do not provide much information about AAA services;
856 this is due to the fact that logging can severely degrade performance.
858 All AAA logging is output to the standard karaf.log file. For debugging purposes
859 (i.e., to enable maximum verbosity), issue the following command:
863 log:set TRACE org.opendaylight.aaa
865 Enable Successful/Unsuccessful Authentication Attempts Logging
866 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
868 By default, successful/unsuccessful authentication attempts are NOT logged. This
869 is due to the fact that logging can severely decrease REST performance.
870 To enable logging of successful/unsuccessful REST attempts, issue the following
871 command in Karaf's console:
875 log:set DEBUG org.opendaylight.aaa.shiro.filters.AuthenticationListener
877 It is possible to add custom AuthenticationListener(s) to the Shiro-based
878 configuration, allowing different ways to listen for successful/unsuccessful
879 authentication attempts. Custom AuthenticationListener(s) must implement
880 the org.apache.shiro.authc.AuthenticationListener interface.
882 .. _certificate-management:
884 Certificate Management
885 ----------------------
887 The **Certificate Management Service** is used to manage the keystores and
888 certificates at the OpenDaylight distribution to easily provides the TLS
891 The Certificate Management Service managing two keystores:
893 1. **OpenDaylight Keystore** which holds the OpenDaylight distribution
894 certificate self sign certificate or signed certificate from a root CA based
895 on generated certificate request.
897 2. **Trust Keystore** which holds all the network nodes certificates that shall
898 to communicate with the OpenDaylight distribution through TLS communication.
900 The Certificate Management Service stores the keystores (OpenDaylight & Trust)
901 as *.jks* files under configuration/ssl/ directory. Also the keystores
902 could be stored at the MD-SAL datastore in case OpenDaylight distribution
903 running at cluster environment. When the keystores are stored at MD-SAL,
904 the Certificate Management Service rely on the **Encryption-Service** to encrypt
905 the keystore data before storing it to MD-SAL and decrypted at runtime.
907 How to use the Certificate Management Service to manage the TLS communication
908 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
910 The following are the steps to configure the TLS communication:
912 1. After starting the distribution, the *odl-aaa-cert* feature has to get
913 installed. Use the following command at Karaf CLI to check.
917 opendaylight-user@root>feature:list -i | grep aaa-cert
918 odl-aaa-cert | 0.5.0-SNAPSHOT | x | odl-aaa-0.5.0-SNAPSHOT | OpenDaylight :: AAA :: aaa certificate Service
920 2. The initial configuration of the Certificate Manager Service exists under
921 the distribution directory etc/opendaylight/datastore/initial/config/aaa-cert-config.xml.
925 <aaa-cert-service-config xmlns="urn:opendaylight:yang:aaa:cert">
926 <use-config>false</use-config>
927 <use-mdsal>false</use-mdsal>
928 <bundle-name>opendaylight</bundle-name>
931 <alias>controller</alias>
933 <dname>CN=ODL, OU=Dev, O=LinuxFoundation, L=QC Montreal, C=CA</dname>
934 <validity>365</validity>
935 <key-alg>RSA</key-alg>
936 <sign-alg>SHA1WithRSAEncryption</sign-alg>
937 <keysize>1024</keysize>
943 <name>truststore.jks</name>
946 </aaa-cert-service-config>
949 Now as it is explained above, the Certificate Manager Service support two mode
950 of operations; cluster mode and single mode. To use the single mode change the
951 use-config to true and it is recommended as long as there is no need for
952 cluster environment. To use the cluster mode change the use-config and
953 use-mdsal configurations to true and the keystores will be stored and shard
954 across the cluster nodes within the MD-SAL datastore.
956 The initial password become randomly generated when the *aaa-cert* feature is
959 The cipher suites can be restricted by changing the **<cipher-suites>**
960 configuration, however, the JDK has to be upgraded by installing the `Java
961 Cryptography Extension
962 <http://www.oracle.com/technetwork/java/javase/downloads/jce8-download-2133166.html>`_
968 <suite-name>TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384</suite-name>
971 <suite-name>TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384</suite-name>
974 <suite-name>TLS_DHE_RSA_WITH_AES_256_GCM_SHA384</suite-name>
977 3. The new configurations will take affect after restarting the distribution.
979 4. Now to add or get certificate to the OpenDaylight and Trust keystores, the
980 Certificate Manager Service provides the following RPCs.
984 a) Set the node certificate that will communicate with OpeDaylight through TLS
986 POST /operations/aaa-cert-rpc:setNodeCertifcate
989 "node-cert": "string",
990 "node-alias": "string"
996 b) Get the node certificate based on node alias.
997 POST /operations/aaa-cert-rpc:getNodeCertifcate
1000 "node-alias": "string"
1006 c) Get the OpeDaylight keystore certificate.
1007 POST /operations/aaa-cert-rpc:getODLCertificate
1016 d) Generate a certificate request from the OpeDaylight keystore to be signed
1018 POST /operations/aaa-cert-rpc:getODLCertificateReq
1021 odl-cert-req "string"
1027 e) Set the OpeDaylight certificate, the certificate should be generated
1028 based on a certificate request generated from the ODL keystore otherwise the
1029 certificated will not be added.
1030 POST /operations/aaa-cert-rpc:setODLCertificate
1033 "odl-cert-alias": "string",
1034 "odl-cert": "string"
1040 The Certificate Manager Service RPCs are allowed only to the Role Admin Users
1041 and it could be completely disabled through the shiro.ini config file. Check
1042 the URL section at the shiro.ini.
1047 The **AAA Encryption Service** is used to encrypt the OpenDaylight's users'
1048 passwords and TLS communication certificates. This section shows how to use the
1049 AAA Encryption Service with an OpenDaylight distribution project to encrypt data.
1051 The following are the steps to configure the Encryption Service:
1053 1. After starting the distribution, the *aaa-encryption-service* feature has to
1054 get installed. Use the following command at Karaf CLI to check.
1056 .. code-block:: bash
1058 opendaylight-user@root>feature:list -i | grep aaa-encryption-service
1059 odl-aaa-encryption-service | 0.5.0-SNAPSHOT | x | odl-aaa-0.5.0-SNAPSHOT | OpenDaylight :: AAA :: Encryption Service
1061 2. The initial configuration of the Encryption Service exists under the
1062 distribution directory etc/opendaylight/datastore/initial/config/aaa-encrypt-service-config.xml
1066 <aaa-encrypt-service-config xmlns="config:aaa:authn:encrypt:service:config">
1069 <encrypt-method>PBKDF2WithHmacSHA1</encrypt-method>
1070 <encrypt-type>AES</encrypt-type>
1071 <encrypt-iteration-count>32768</encrypt-iteration-count>
1072 <encrypt-key-length>128</encrypt-key-length>
1073 <cipher-transforms>AES/CBC/PKCS5Padding</cipher-transforms>
1074 </aaa-encrypt-service-config>
1078 Both the initial encryption key and encryption salt become randomly generated
1079 when the *aaa-encryption-service* feature is installed.
1081 3. Finally the new configurations will take affect after restarting the
1084 Using the AAA Command Line Interface (CLI)
1085 ------------------------------------------
1086 The AAA offers a CLI through the Karaf's console. This CLI allows the user to
1087 configure and use some of the functionalities provided by AAA.
1089 The AAA CLI exists under the **odl-aaa-cli** feature. This feature can be
1090 installed by executing the following command.
1094 feature:install odl-aaa-cli
1096 To check that the installation of the feature succeeded type "aaa" and press
1097 *tab* to see the list of available commands under the *aaa* scope.
1101 opendaylight-user@root>aaa:
1102 aaa:add-domain aaa:add-grant aaa:add-role aaa:add-user
1103 aaa:change-user-pwd aaa:export-keystores aaa:gen-cert-req aaa:get-cipher-suites
1104 aaa:get-domains aaa:get-node-cert aaa:get-odl-cert aaa:get-roles
1105 aaa:get-tls-protocols aaa:get-users aaa:import-keystores aaa:remove-domain
1106 aaa:remove-grant aaa:remove-role aaa:remove-user
1111 The *add-user* command allows for adding an OpenDaylight user. The following
1112 user parameters can be specified.
1116 aaa:add-user --name <user name>
1118 --userDescription <user description>
1119 --email <user email>
1120 --domainName <domain name>
1122 List available Users
1123 ^^^^^^^^^^^^^^^^^^^^
1125 The *get-users* command list all the available users within the Controller.
1137 The *remove-user* command allows for removing an OpenDaylight user. The command
1138 needs the user name as parameter.
1142 aaa:remove-user --name <user name>
1144 Change the OpenDaylight user password
1145 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1147 The *change-user-pwd* command allows for changing the OpenDaylight user's
1148 password. It takes the user name as argument then will ask for the given user
1153 aaa:change-user-pwd -user admin
1154 Enter current password:
1156 admin's password has been changed
1161 The *add-role* command allows for adding a role to the Controller.
1165 aaa:add-role --name <role name>
1166 --desc <role description>
1167 --domainName <domain name>
1169 List available Roles
1170 ^^^^^^^^^^^^^^^^^^^^
1172 The *get-roles* command list all the available roles within the controller.
1184 The *remove-role* command allows for removing an OpenDaylight role. The command
1185 needs the role name as parameter. The role will be removed from those users who
1190 aaa:remove-role --name <role name>
1195 The *add-domain* command allows for adding a domain to the Controller.
1199 aaa:add-domain --name <domain name>
1200 --desc <domain description>
1202 List available Domains
1203 ^^^^^^^^^^^^^^^^^^^^^^
1205 The *get-domains* command list all the available domains within the controller.
1206 The system asks for the administrator credentials to execute this command.
1217 The *remove-domain* command allows for removing an OpenDaylight role. The command
1218 needs the domain name as parameter.
1222 aaa:remove-domain --name <domain name>
1227 The *add-grant* command allows for creating a grant for an existing user. The
1228 command returns a grant id for that user.
1232 aaa:add-grant --userName <user name>
1233 --domainName <domain name>
1234 --roleName <role name>
1239 The *remove-grant* command allows for removing an OpenDaylight grant. This command
1240 needs the user name, domain and and role as parameters.
1244 aaa:remove-grant --userName <user name>
1245 --domainName <domain name>
1246 --roleName <role name>
1248 Generate Certificate Request
1249 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1251 Generate certificate request command will generate a certificate request based
1252 on the generated OpenDaylight keystore and print it on the Karaf CLI. The system
1253 asks for the keystore password.
1259 -----BEGIN CERTIFICATE REQUEST-----
1260 MIIBlzCCAQACAQAwWTELMAkGA1UEBhMCQ0ExFDASBgNVBAcMC1FDIE1vbnRyZWFsMRgwFgYDVQQKDA
1261 9MaW51eEZvdW5kYXRpb24xDDAKBgNVBAsMA0RldjEMMAoGA1UEAwwDT0RMMIGfMA0GCSqGSIb3DQEB
1262 AQUAA4GNADCBiQKBgQCCmLW6j+JLYJM5yAMwscw/CHqPnp5elPa1YtQsHKEAvp1I+mLVtHKZeXeteA
1263 kyp6ORxw6KQ515fcDyQVrRJiSM15jUd27UaFq5ku0+qJeG+Qh2btx+cvNSE7/+cgUWWosKz4Aff5F5
1264 FqR62jLUTNzqCvoaTbZaOnLYVq+O2dYyZwIDAQABMA0GCSqGSIb3DQEBBQUAA4GBADhDr4Jm7gVm/o
1265 p861/FShyw1ZZscxOEl2TprJZiTO6sn3sLptQZv8v52Z+Jm5dAgr7L46c97Xfa+0j6Y4LXNb0f88lL
1266 RG8PxGbk6Tqbjqc0WS+U1Ibc/rcPK4HEN/bcYCn+Na1gLBaFXUPg08ozG6MwqFNeS5Z0jz1W0D9/oiao
1267 -----END CERTIFICATE REQUEST-----
1269 Get OpenDaylight Certificate
1270 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1272 The *get-odl-certificate* command will print the OpenDaylight certificate at the
1273 Karaf CLI. The system asks for the keystore password.
1277 aaa:get-odl-cert -storepass <store_password>
1279 -----BEGIN CERTIFICATE-----
1280 MIICKTCCAZKgAwIBAgIEI75RWDANBgkqhkiG9w0BAQUFADBZMQwwCgYDVQQDDANPREwxDDAKBgNVBA
1281 sMA0RldjEYMBYGA1UECgwPTGludXhGb3VuZGF0aW9uMRQwEgYDVQQHDAtRQyBNb250cmVhbDELMAkG
1282 A1UEBhMCQ0EwHhcNMTYxMTMwMTYyNDE3WhcNMTcxMTMwMTYyNDE3WjBZMQwwCgYDVQQDDANPREwxDD
1283 AKBgNVBAsMA0RldjEYMBYGA1UECgwPTGludXhGb3VuZGF0aW9uMRQwEgYDVQQHDAtRQyBNb250cmVh
1284 bDELMAkGA1UEBhMCQ0EwgZ8wDQYJKoZIhvcNAQEBBQADgY0AMIGJAoGBAIKYtbqP4ktgkznIAzCxzD
1285 8Ieo+enl6U9rVi1CwcoQC+nUj6YtW0cpl5d614CTKno5HHDopDnXl9wPJBWtEmJIzXmNR3btRoWrmS
1286 7T6ol4b5CHZu3H5y81ITv/5yBRZaiwrPgB9/kXkWpHraMtRM3OoK+hpNtlo6cthWr47Z1jJnAgMBAA
1287 EwDQYJKoZIhvcNAQEFBQADgYEAL9DK/P/yEBre3Mg3bICAUAvSvZic+ydDmigWLsY4J3UzKdV2f1jI
1288 s+rQTEgtlHShBf/ed546D49cp3XEzYrcxgILhGXDziCrUK0K1TiYqPTp6FLijjdydGlPpwuMyyV5Y0
1289 iDiRclWuPz2fHbs8WQOWNs6VQ+WaREXtEsEC4qgSo=
1290 -----END CERTIFICATE-----
1295 The *get-cipher-suites* command shows the cipher suites supported by the
1296 JVM used by the OpenDaylight controller in TLS communication. For example, here
1297 are the `Default Ciphers Suites in JDK 8 <http://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#ciphersuites>`_.
1301 aaa:get-cipher-suites
1303 TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
1304 TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
1305 TLS_DHE_RSA_WITH_AES_256_GCM_SHA384
1310 The *get-tls-protocols* command shows the TLS protocols supported by the
1311 JVM used by the OpenDaylight controller. For example, the JDK 8 supports the
1312 following TLS protocols: TLSv1.2 (default), TLSv1.1, TLSv1 and SSLv3.
1316 aaa:get-tls-protocols
1318 TLS_KRB5_WITH_RC4_128_SHA
1319 TLS_KRB5_WITH_RC4_128_MD5
1320 TLS_KRB5_WITH_3DES_EDE_CBC_SHA
1321 TLS_KRB5_WITH_3DES_EDE_CBC_MD5
1322 TLS_KRB5_WITH_DES_CBC_SHA
1324 Get Node Certificate
1325 ^^^^^^^^^^^^^^^^^^^^
1327 The *get-node-cert* command prints a certificate for a given network node alias.
1328 This command is useful to check if the network node certificate has been added
1329 properly to the truest keystore. It takes the certificate alias as arguments.
1333 aaa:get-node-cert -alias ovs1
1334 -----BEGIN CERTIFICATE-----
1335 MIICKTCCAZKgAwIBAgIEI75RWDANBgkqhkiG9w0BAQUFADBZMQwwCgYDVQQDDANPREwxDDAKBgNVBA
1336 sMA0RldjEYMBYGA1UECgwPTGludXhGb3VuZGF0aW9uMRQwEgYDVQQHDAtRQyBNb250cmVhbDELMAkG
1337 A1UEBhMCQ0EwHhcNMTYxMTMwMTYyNDE3WhcNMTcxMTMwMTYyNDE3WjBZMQwwCgYDVQQDDANPREwxDD
1338 AKBgNVBAsMA0RldjEYMBYGA1UECgwPTGludXhGb3VuZGF0aW9uMRQwEgYDVQQHDAtRQyBNb250cmVh
1339 bDELMAkGA1UEBhMCQ0EwgZ8wDQYJKoZIhvcNAQEBBQADgY0AMIGJAoGBAIKYtbqP4ktgkznIAzCxzD
1340 8Ieo+enl6U9rVi1CwcoQC+nUj6YtW0cpl5d614CTKno5HHDopDnXl9wPJBWtEmJIzXmNR3btRoWrmS
1341 7T6ol4b5CHZu3H5y81ITv/5yBRZaiwrPgB9/kXkWpHraMtRM3OoK+hpNtlo6cthWr47Z1jJnAgMBAA
1342 EwDQYJKoZIhvcNAQEFBQADgYEAL9DK/P/yEBre3Mg3bICAUAvSvZic+ydDmigWLsY4J3UzKdV2f1jI
1343 s+rQTEgtlHShBf/ed546D49cp3XEzYrcxgILhGXDziCrUK0K1TiYqPTp6FLijjdydGlPpwuMyyV5Y0
1344 iDiRclWuPz2fHbs8WQOWNs6VQ+WaREXtEsEC4qgSo=
1345 -----END CERTIFICATE-----
1350 The *export-keystores* command exports the default MD-SAL Keystores to .jks
1351 files in the default directory for keystores (configuration/ssl/).
1355 aaa:export-keystores
1357 Default directory for keystores is configuration/ssl/
1362 The *import-keystores* command imports the default MD-SAL Keystores. The
1363 keystores (odl and trust) should exist under default SSL directory
1364 (configuration/ssl/).
1366 .. code-block:: bash
1368 aaa:import-keystores --trustKeystoreName <name of the trust keystore>
1369 --trustKeystorePwd <password for the trust keystore>
1370 --odlKeystoreName <name of the ODL keystore>
1371 --odlKeystorePwd <password for the ODL keystore>
1372 --odlKeystoreAlias <alias of the ODL keystore>
1373 --tlsProtocols <list of TLS protocols separated by ','>
1374 --cipherSuites <list of Cipher suites separated by ','>
1378 It is strongly recommended to run the history clear command after you execute
1379 all the AAA CLI commands so Karaf logs stay clean from any adversary.