1 Authentication, Authorization and Accounting (AAA) Services
2 ===========================================================
4 The Boron AAA services are based on the Apache Shiro Java Security
5 Framework. The main configuration file for AAA is located at
6 “etc/shiro.ini” relative to the ODL karaf home directory.
12 A claim of access to a group of resources on the controller
15 A group of resources, direct or indirect, physical, logical, or
16 virtual, for the purpose of access control. ODL recommends using the
17 default “sdn" domain in the Boron release.
20 A person who either owns or has access to a resource or group of
21 resources on the controller
24 Opaque representation of a set of permissions, which is merely a
25 unique string as admin or guest
28 Proof of identity such as username and password, OTP, biometrics, or
32 A service or application that requires access to the controller
35 A data set of validated assertions regarding a user, e.g. the role,
41 AAA is enabled through installing the odl-aaa-shiro feature.
42 odl-aaa-shiro is automatically installed as part of the odl-restconf
48 Edit the “etc/shiro.ini” file and replace the following:
60 Then restart the karaf process.
62 How application developers can leverage AAA to provide servlet security
63 -----------------------------------------------------------------------
65 In order to provide security to a servlet, add the following to the
66 servlet’s web.xml file as the first filter definition:
71 <param-name>shiroEnvironmentClass</param-name>
72 <param-value>org.opendaylight.aaa.shiro.web.env.KarafIniWebEnvironment</param-value>
76 <listener-class>org.apache.shiro.web.env.EnvironmentLoaderListener</listener-class>
80 <filter-name>ShiroFilter</filter-name>
81 <filter-class>org.opendaylight.aaa.shiro.filters.AAAShiroFilter</filter-class>
85 <filter-name>AAAShiroFilter</filter-name>
86 <url-pattern>/*</url-pattern>
91 It is very important to place this AAAShiroFilter as the first
92 javax.servlet.Filter, as Jersey applies Filters in the order they
93 appear within web.xml. Placing the AAAShiroFilter first ensures
94 incoming HTTP/HTTPS requests have proper credentials before any
95 other filtering is attempted.
100 AAA plugin utilizes realms to support pluggable authentication &
101 authorization schemes. There are two parent types of realms:
103 - AuthenticatingRealm
105 - Provides no Authorization capability.
107 - Users authenticated through this type of realm are treated
112 - AuthorizingRealm is a more sophisticated AuthenticatingRealm,
113 which provides the additional mechanisms to distinguish users
116 - Useful for applications in which roles determine allowed
119 ODL Contains Four Implementations
123 - An AuthorizingRealm built to bridge the Shiro-based AAA service
124 with the h2-based AAA implementation.
126 - Exposes a RESTful web service to manipulate IdM policy on a
127 per-node basis. If identical AAA policy is desired across a
128 cluster, the backing data store must be synchronized using an out
131 - A python script located at “etc/idmtool” is included to help
132 manipulate data contained in the TokenAuthRealm.
134 - Enabled out of the box.
138 - An AuthorizingRealm built to extract identity information from IdM
139 data contained on an LDAP server.
141 - Extracts group information from LDAP, which is translated into ODL
144 - Useful when federating against an existing LDAP server, in which
145 only certain types of users should have certain access privileges.
147 - Disabled out of the box.
149 - ODLJndiLdapRealmAuthNOnly
151 - The same as ODLJndiLdapRealm, except without role extraction.
152 Thus, all LDAP users have equal authentication and authorization
155 - Disabled out of the box.
157 - ActiveDirectoryRealm
161 More than one Realm implementation can be specified. Realms are
162 attempted in order until authentication succeeds or all realm
163 sources are exhausted.
165 TokenAuthRealm Configuration
166 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
168 TokenAuthRealm stores IdM data in an h2 database on each node. Thus,
169 configuration of a cluster currently requires configuring the desired
170 IdM policy on each node. There are two supported methods to manipulate
171 the TokenAuthRealm IdM configuration:
173 - idmtool Configuration
175 - RESTful Web Service Configuration
177 idmtool Configuration
178 ^^^^^^^^^^^^^^^^^^^^^
180 A utility script located at “etc/idmtool” is used to manipulate the
181 TokenAuthRealm IdM policy. idmtool assumes a single domain (sdn), since
182 multiple domains are not leveraged in the Boron release. General usage
183 information for idmtool is derived through issuing the following
188 $ python etc/idmtool -h
189 usage: idmtool [-h] [--target-host TARGET_HOST]
191 {list-users,add-user,change-password,delete-user,list-domains,list-roles,add-role,delete-role,add-grant,get-grants,delete-grant}
194 positional arguments:
195 user username for BSC node
196 {list-users,add-user,change-password,delete-user,list-domains,list-roles,add-role,delete-role,add-grant,get-grants,delete-grant}
198 list-users list all users
200 change-password change a password
201 delete-user delete a user
202 list-domains list all domains
203 list-roles list all roles
205 delete-role delete a role
206 add-grant add a grant
207 get-grants get grants for userid on sdn
208 delete-grant delete a grant
211 -h, --help show this help message and exit
212 --target-host TARGET_HOST
220 python etc/idmtool admin add-user newUser
235 "password": "**********",
236 "salt": "**********",
237 "userid": "newUser@sdn"
242 AAA redacts the password and salt fields for security purposes.
249 $ python etc/idmtool admin delete-user newUser@sdn
251 delete_user(newUser@sdn)
260 $ python etc/idmtool admin list-users
270 "description": "user user",
275 "password": "**********",
276 "salt": "**********",
280 "description": "admin user",
285 "password": "**********",
286 "salt": "**********",
287 "userid": "admin@sdn"
292 Change a user’s password
293 ''''''''''''''''''''''''
297 $ python etc/idmtool admin change-password admin@sdn
301 change_password(admin)
307 "description": "admin user",
312 "password": "**********",
313 "salt": "**********",
314 "userid": "admin@sdn"
322 $ python etc/idmtool admin add-role network-admin
324 add_role(network-admin)
332 "name": "network-admin",
333 "roleid": "network-admin@sdn"
341 $ python etc/idmtool admin delete-role network-admin@sdn
343 delete_role(network-admin@sdn)
352 $ python etc/idmtool admin list-roles
362 "description": "a role for admins",
365 "roleid": "admin@sdn"
368 "description": "a role for users",
381 $ python etc/idmtool admin list-domains
391 "description": "default odl sdn domain",
404 $ python etc/idmtool admin add-grant user@sdn admin@sdn
406 add_grant(userid=user@sdn,roleid=admin@sdn)
413 "grantid": "user@sdn@admin@sdn@sdn",
414 "roleid": "admin@sdn",
423 $ python etc/idmtool admin delete-grant user@sdn admin@sdn
425 http://localhost:8181/auth/v1/domains/sdn/users/user@sdn/roles/admin@sdn
426 delete_grant(userid=user@sdn,roleid=admin@sdn)
430 Get grants for a user
431 '''''''''''''''''''''
435 python etc/idmtool admin get-grants admin@sdn
437 get_grants(admin@sdn)
445 "description": "a role for users",
451 "description": "a role for admins",
454 "roleid": "admin@sdn"
462 The TokenAuthRealm IdM policy is fully configurable through a RESTful
463 web service. Full documentation for manipulating AAA IdM data is located
464 online (https://wiki.opendaylight.org/images/0/00/AAA_Test_Plan.docx),
465 and a few examples are included in this guide:
472 curl -u admin:admin http://localhost:8181/auth/v1/users
477 "description": "user user",
482 "password": "**********",
483 "salt": "**********",
487 "description": "admin user",
492 "password": "**********",
493 "salt": "**********",
494 "userid": "admin@sdn"
504 curl -u admin:admin -X POST -H "Content-Type: application/json" --data-binary @./user.json http://localhost:8181/auth/v1/users
508 "userid": "ryan@sdn",
511 "description": "Ryan's User Account",
512 "email": "ryandgoulding@gmail.com"
519 "description":"Ryan's User Account",
521 "email":"ryandgoulding@gmail.com",
522 "password":"**********",
527 Create an OAuth2 Token For Admin Scoped to SDN
528 ''''''''''''''''''''''''''''''''''''''''''''''
532 curl -d 'grant_type=password&username=admin&password=a&scope=sdn' http://localhost:8181/oauth2/token
537 "token_type":"Bearer",
538 "access_token":"5a615fbc-bcad-3759-95f4-ad97e831c730"
546 curl -H "Authorization: Bearer 5a615fbc-bcad-3759-95f4-ad97e831c730" http://localhost:8181/auth/v1/domains
553 "description":"default odl sdn domain",
559 ODLJndiLdapRealm Configuration
560 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
562 LDAP integration is provided in order to externalize identity
563 management. To configure LDAP parameters, modify "etc/shiro.ini"
564 parameters to include the ODLJndiLdapRealm:
568 # ODL provides a few LDAP implementations, which are disabled out of the box.
569 # ODLJndiLdapRealm includes authorization functionality based on LDAP elements
570 # extracted through and LDAP search. This requires a bit of knowledge about
571 # how your LDAP system is setup. An example is provided below:
572 ldapRealm = org.opendaylight.aaa.shiro.realm.ODLJndiLdapRealm
573 ldapRealm.userDnTemplate = uid={0},ou=People,dc=DOMAIN,dc=TLD
574 ldapRealm.contextFactory.url = ldap://<URL>:389
575 ldapRealm.searchBase = dc=DOMAIN,dc=TLD
576 ldapRealm.ldapAttributeForComparison = objectClass
577 ldapRealm.groupRolesMap = "Person":"admin"
579 # further down in the file...
580 # Stacked realm configuration; realms are round-robbined until authentication succeeds or realm sources are exhausted.
581 securityManager.realms = $tokenAuthRealm, $ldapRealm
583 This configuration allows federation with an external LDAP server, and
584 the user’s ODL role parameters are mapped to corresponding LDAP
585 attributes as specified by the groupRolesMap. Thus, an LDAP operator can
586 provision attributes for LDAP users that support different ODL role
589 ODLJndiLdapRealmAuthNOnly Configuration
590 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
592 Edit the "etc/shiro.ini" file and modify the following:
596 ldapRealm = org.opendaylight.aaa.shiro.realm.ODLJndiLdapRealm
597 ldapRealm.userDnTemplate = uid={0},ou=People,dc=DOMAIN,dc=TLD
598 ldapRealm.contextFactory.url = ldap://<URL>:389
600 # further down in the file...
601 # Stacked realm configuration; realms are round-robbined until authentication succeeds or realm sources are exhausted.
602 securityManager.realms = $tokenAuthRealm, $ldapRealm
604 This is useful for setups where all LDAP users are allowed equal access.
606 Token Store Configuration Parameters
607 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
609 Edit the file “etc/opendaylight/karaf/08-authn-config.xml” and edit the
610 following: .\ **timeToLive**: Configure the maximum time, in
611 milliseconds, that tokens are to be cached. Default is 360000. Save the
614 Authorization Configuration
615 ---------------------------
617 Shiro-Based Authorization
618 ~~~~~~~~~~~~~~~~~~~~~~~~~
620 OpenDaylight AAA has support for Role Based Access Control based on the
621 Apache Shiro permissions system. Configuration of the authorization
622 system is done offline; authorization currently cannot be configured
623 after the controller is started. Thus, Authorization in this
624 release is aimed towards supporting coarse-grained security policies,
625 with the aim to provide more robust configuration capabilities in the
626 future. Shiro-based Authorization is documented on the Apache Shiro
627 website (http://shiro.apache.org/web.html#Web-%7B%7B%5Curls%5C%7D%7D).
629 Enable “admin” Role Based Access to the IdMLight RESTful web service
630 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
632 Edit the “etc/shiro.ini” configuration file and add “/auth/v1/\ **=
633 authcBasic, roles[admin]” above the line “/** = authcBasic” within the
638 /auth/v1/** = authcBasic, roles[admin]
641 This will restrict the idmlight rest endpoints so that a grant for admin
642 role must be present for the requesting user.
646 The ordering of the authorization rules above is important!
651 ODL includes an experimental Authorization Broker Facade, which allows
652 finer grained access control for REST endpoints. Since this feature was
653 not well tested in the Boron release, it is recommended to use the
654 Shiro-based mechanism instead, and rely on the Authorization Broker
655 Facade for POC use only.
657 AuthZ Broker Facade Feature Installation
658 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
660 To install the authorization broker facade, please issue the following
661 command in the karaf shell:
665 feature:install odl-restconf odl-aaa-authz
667 Add an Authorization Rule
668 ^^^^^^^^^^^^^^^^^^^^^^^^^
670 The following shows how one might go about securing the controller so
671 that only admins can access restconf.
675 curl -u admin:admin -H “Content-Type: application/xml” --data-binary @./rule.json http://localhost:8181/restconf/config/authorization-schema:simple-authorization/policies/RestConfService/
680 "service":"RestConfService",
685 Accounting Configuration
686 ------------------------
688 All AAA logging is output to the standard karaf.log file.
692 log:set TRACE org.opendaylight.aaa
694 This command enables the most verbose level of logging for AAA