3 This project is aimed at providing a flexible, pluggable framework with out-of-the-box capabilities for Authentication,
4 Authorization and Accounting (AAA).
7 The following caveats are applicable to the current AAA implementation:
8 - The database (H2) used by ODL AAA Authentication store is not-cluster enabled. When deployed in a clustered
9 environment each node contains unique local credentials.
10 - AAA provides two local IdP Realm implementations; TokenAuthRealm and MdsalRealm. Although the use of both Realms at
11 the same time is possible through Shiro's multi-realm approach, it is considered bad practice to provide two local
12 identity stores. Thus, users should specify one or the other for $securityManager.realms entry in the aaa-app-config
14 - The MdsalRealm is not initialized with any Users, Roles, Domains, or Grants. The ability to add OOB Identity
15 Information is considered separate work, and is targeted for the Fluorine release.
21 *Prerequisite:* The followings are required for building AAA:
25 - Python 3.7+ (optional) for running wrapper scripts
30 git clone https://git.opendaylight.org/gerrit/aaa
33 git clone ssh://{USERNAME}@git.opendaylight.org:29418/aaa
37 cd aaa && mvn clean install
41 AAA is automatically installed upon installation of odl-restconf-noauth and enabled through aaa-shiro-act.
43 If you are using AAA from a non-RESTCONF context, you can install the necessary javax.servlet.Filter(s) through the
46 karaf> feature:install odl-aaa-shiro
50 Once the installation finishes, one can authenticate with the OpenDaylight controller by presenting a username/password
51 to access protected resources.
54 curl -s -H 'Authorization: Basic YWRtaW46YWRtaW4=' \
55 http://<controller>:<port>/rests/data/...?content=config
57 Upon successful authentication, session cookie will be created, which can be then used to access protected resources
58 during session, instead of providing username/password.
61 curl -s -H 'Cookie: JSESSIONID=node0x12lwsvqbaxx15981soehtqed1.node0' \
62 http://<controller>:<port>/rests/data/...?content=config
67 Although it is poor security practice, AAA's TokenAuthRealm creates some defaults out of the box. In order to avoid
68 default credentials, please see the aaa-cli-jar module, which allows installers to pre-install identity information.
69 Due to the fact that OpenDaylight does not have a proper installer project, default credentials become a
70 chicken/egg problem. The choice to utilize defaults was initially decided to help bootstrap interaction with ODL's
71 restful web services. AAA's TokenAuthRealm creates:
73 * the "admin" and "user" roles
74 * the "admin" user with "admin" password
76 * admin user is granted admin role privileges on sdn domain
77 * admin user is granted user role privileges on sdn domain
79 TokenAuthRealm's H2 file-based database, which stores the identity information, is secured with default credentials
80 "foo"/"bar". Default credentials on the local file-based database is a smaller concern, since without running an H2
81 Server instance on the local machine (ODL doesn't by default), the database is only accessible locally (i.e., user in
82 front of keyboard). However, these credentials can be adjusted too by setting "dbUsername" and "dbPassword" within
83 etc/org.opendaylight.aaa.h2.cfg.
89 AAA supports 2 main authentication use-cases: *direct* and *federated* authentication, with direct authentication being
90 the simpler to deploy (i.e., no external system dependency) and hence being the out-of-the-box authentication mechanism.
94 In this use-case, a user presents some credentials (e.g., username/password) directly to the Opendaylight (ODL)
95 controller and receives a session cookie, which can be then used to access protected resources on the controller,
96 similar to the example we saw in the Quickstart section.
100 In the federated use-case, the responsibility of authentication is delegated to a third-party IdP (perhaps, an
101 enterprise-level IdP).
103 For more information, consult ODLJndiLdapRealm and ODLJndiLdapRealmAuthNOnly documentation.
105 ### Authorization & Access Control
107 ODL supports two authorization engines at present, both of which are roughly similar in behavior. Namely, the two
108 authorization engines are the MDSALDynamicAuthorizationFilter(1) and the RolesAuthorizationFilter(2). For several
109 reasons explained further in this documentation, we STRONGLY encourage you to use the MDSALDyanmicAuthorizationFilter(1)
110 approach over the RolesAuthorizationFilter(2).
112 1) MDSALDyanmicAuthorizationFilter
114 The MDSALDynamicAuthorizationFilter is a mechanism used to restrict access to partcular URL endpoint patterns. Users
115 may define a list of policies that are insertion-ordered. Order matters for the list of policies, since the first
116 matching policy is applied. This choice was made to emulate behavior of the Apache Shiro RolesAuthorizationFilter.
118 A policy is a key/value pair, where the key is a resource (i.e., a "url pattern") and the value is a list of permissions
119 for the resource. The following describes the various elements of a policy:
121 resource: The resource is a string url pattern as outlined by Apache Shiro. For more information,
122 see http://shiro.apache.org/web.html.
123 description: An optional description of the URL endpoint and why it is being secured.
124 permissions list: A list of permissions for a particular policy. If more than one permission exists in the permissions
125 list, the permissions are evaluted using logical "OR".
127 A permission describes the prerequisites to perform HTTP operations on a particular endpoint. The following describes
128 the various elements of a permission:
130 role: The role required to access the target URL endpoint.
131 actions list: A leaf-list of HTTP permissions that are allowed for a Subject possessing the required role.
136 To limit access to the modules endpoint, issue the following:
139 URL: /restconf/config/aaa:http-authorization/policies
141 Content-Tye: application/json
142 Accept: application/json
150 "aaa:resource": "/restconf/modules/**",
155 "get","post","put","patch","delete"
165 The above example locks down access to the modules endpoint (and any URLS available past modules) to the "admin" role.
166 Thus, an attempt from the OOB admin user will succeed with 2XX HTTP status code, while an attempt from the OOB "user"
167 user will fail with HTTP status code 401, as the "user" user is not granted the "admin" role.
169 NOTE: "aaa:resource" value starts with "/restconf". Unlike the RolesAuthorizationFilter whichis relative to the
170 ServletContext, The MDSALDyanmicAuthorizationFilter is relative to the Servlet Root (i.e., "/"). This is superior, as it
171 is more specific and does not allow for ambiguity.
173 2) aaa-app-config clustered application configuration "urls" section Authorization roles filter (i.e.,
174 "RolesAuthorizationFilter"). [DEPRECATED]
176 Authorization is implemented via the aaa-shiro modules. RolesAuthorizationFilter (roles filter) is limited purely to
177 RESTCONF (HTTP) and does not focus on MD-SAL.
179 More information on how to configure authorization can be found on the Apache Shiro website: http://shiro.apache.org/web.html
181 NOTE: Use of aaa-app-config.xml urls section to define roles requirements is discouraged! This is due to the fact that
182 aaa-app-config.xml changes are only recognized on servlet container startup. Changes to aaa-app-config.xml are only
183 honored upon restart.
185 NOTE: Use of aaa-app-config.xml urls section to define roles requirements is discouraged! This is due to the fact that
186 url patterns are matched relative to the servlet context. This leaves room for ambiguity, since many endpoints may
187 match (i.e., "/restconf/modules" and "/auth/modules" would both match a "/modules/**" rule).
191 Accounting is handled through the standard slf4j logging mechanisms used by the rest of OpenDaylight. Thus, one can
192 control logging verbosity through manipulating the log levels for individual packages and classes directly through the
193 karaf shell, JMX, or etc/org.ops4j.pax.logging.cfg. In normal operations, the default levels exposed do not provide
194 much information about AAA services; this is due to the fact that logging can severely degrade performance.
196 Two noteworthy logging activities are:
197 1) Enable debugging logging
198 2) Enable successful/unsuccessful authentication attempts logging
200 #### Enable Debugging Logging
202 For debugging purposes (i.e., to enable maximum verbosity), issue the following command:
204 karaf> log:set TRACE org.opendaylight.aaa
206 #### Enable Successful/Unsuccessful Authentication Attempts Logging
207 By default, successful/unsuccessful authentication attempts are NOT logged. This is due to the fact that logging can
208 severely decrease REST performance. To enable logging of successful/unsuccessful REST attempts, issue the following
211 karaf> log:set DEBUG org.opendaylight.aaa.shiro.filters.AuthenticationListener
213 It is possible to add custom AuthenticationListener(s) to the Shiro based configuration, allowing different ways to
214 listen for successful/unsuccessful authentication attempts. Custom AuthenticationListener(s) must implement the
215 org.apache.shiro.authc.AuthenticationListener interface.