## Opendaylight AAA
-This project is aimed at providing a flexible, pluggable framework with out-of-the-box capabilities for Authentication, Authorization and Accounting.
+This project is aimed at providing a flexible, pluggable framework with out-of-the-box capabilities for Authentication, Authorization and Accounting (AAA).
## Caveats
The following caveats are applicable to the current AAA implementation:
- - The database (H2) used by ODL AAA Authentication store is not-cluster enabled. When deployed in a clustered environment each node needs to have its AAA
- user file synchronised using out of band means.
+ - The database (H2) used by ODL AAA Authentication store is not-cluster enabled. When deployed in a clustered environment each node contains unique local credentials.
+ - AAA provides two local IdP Realm implementations; TokenAuthRealm and MdsalRealm. Although the use of both Realms at the same time is possible through Shiro's multi-realm approach, it is considered bad practice to provide two local identity stores. Thus, users should specify one or the other for $securityManager.realms entry in the aaa-app-config configuration.
+ - The MdsalRealm is not initialized with any Users, Roles, Domains, or Grants. The ability to add OOB Identity Information is considered separate work, and is targeted for the Oxygen release.
## Quick Start
- Maven 3.3.9+
- JDK8
+- Python 2.7+ (optional) for running wrapper scripts
Get the code:
+Using HTTPS:
git clone https://git.opendaylight.org/gerrit/aaa
+USING SSH:
+ git clone ssh://{USERNAME}@git.opendaylight.org:29418/aaa
+
Build it:
cd aaa && mvn clean install
### Installing
-AAA is automatically installed upon installation of odl-restconf. If you are using AAA from a non-RESTCONF context, you can install the necessary javax.servlet.Filter(s) through the following command:
+AAA is automatically installed upon installation of odl-restconf-noauth and enabled through aaa-shiro-act.
- feature:install odl-aaa-shiro
+If you are using AAA from a non-RESTCONF context, you can install the necessary javax.servlet.Filter(s) through the following command:
-### Protecting your REST/RestConf resources
-
-Add the AAA `AAAShiroFilter` filter to your REST resource (RESTconf example):
-
- <servlet>
- <servlet-name>JAXRSRestconf</servlet-name>
- <servlet-class>com.sun.jersey.spi.container.servlet.ServletContainer</servlet-class>
- <init-param>
- <param-name>javax.ws.rs.Application</param-name>
- <param-value>org.opendaylight.controller.sal.rest.impl.RestconfApplication</param-value>
- </init-param>
- <!-- Token Auth Filter -->
- <init-param>
- <param-name>com.sun.jersey.spi.container.ContainerRequestFilters</param-name>
- <param-value>
- org.opendaylight.aaa.shiro.filters.AAAShiroFilter
- </param-value>
- </init-param>
- <load-on-startup>1</load-on-startup>
- </servlet>
-
-Rebuild and re-install your REST resource.
+ feature:install odl-aaa-shiro
### Running
-Once the installation finishes, one can authenticates with the Opendaylight controller by presenting a username/password and a domain name (scope) to be logged into:
+Once the installation finishes, one can authenticate with the OpenDaylight controller by presenting a username/password and a domain name (scope):
curl -s -d 'grant_type=password&username=admin&password=admin&scope=sdn' http://<controller>:<port>/oauth2/token
curl -s -H 'Authorization: Bearer d772d85e-34c7-3099-bea5-cfafd3c747cb' http://<controller>:<port>/restconf/operational/opendaylight-inventory:nodes
+### Defaults
+
+Although it is poor security practice, AAA's TokenAuthRealm creates some defaults out of the box. In order to avoid default credentials, please see the aaa-cli-jar module, which allows installers to pre-install identity information. Due to the fact that OpenDaylight does not have a proper installer project, default credentials become a chicken/egg problem. The choice to utilize defaults was initially decided to help bootstrap interaction with ODL's restful web services. AAA's TokenAuthRealm creates:
+* the "sdn" domain
+* the "admin" and "user" roles
+* the "admin" user with "admin" password
+* 2 grants
+ * admin user is granted admin role priveledges on sdn domain
+ * admin user is granted user role priveledges on sdn domain
+
+TokenAuthRealm's H2 file-based database, which stores the identity information, is secured with default credentials "foo"/"bar". Default credentials on the local file-based database is a smaller concern, since without running an H2 Server instance on the local machine (ODL doesn't by default), the database is only accessible locally (i.e., user in front of keyboard). However, these credentials can be adjusted too by setting "dbUsername" and "dbPassword" within etc/org.opendaylight.aaa.h2.cfg.
+
## Framework Overview
### Authentication
#### Direct
-In this use-case, a user presents some credentials (e.g., username/password) directly to the Opendaylight (ODL) controller token endpoint `/oauth2/token` and receives an access token, which then can be used to access protected resources on the controller, similar to the example we saw in the Quickstart section:
-
-
+In this use-case, a user presents some credentials (e.g., username/password) directly to the Opendaylight (ODL) controller token endpoint `/oauth2/token` and receives an access token, which then can be used to access protected resources on the controller, similar to the example we saw in the Quickstart section.
#### Federated
-In the federated use-case, the responsibility of authentication is delegated to a third-party IdP (perhaps, an enterprise-level IdP):
-
-
-
-In the above use-case, the user authenticates with a third-party IdP (username/password is shown as an example, but it could be anything that the IdP supports, such as MFA, OTP, etc...). Upon successful authentication, the IdP returns back a claim about the identity of that user. The claim is then submitted to the Opendaylight token endpoint in exchange for an access token that can be used to access protected resources on the controller. The IdP claim must be mapped into a corresponding ODL claim (user/domain/role) before an access token can be granted.
-
-The Opendaylight controller comes with SSSD-based claim support, but other types of claim support can be also added with their implementation of the `org.opendaylight.aaa.api.ClaimAuth` API.
-
-We can also take federation one step further and delegate token management and optionally part of the authorization responsibility to the third-party IdP:
-
-
+In the federated use-case, the responsibility of authentication is delegated to a third-party IdP (perhaps, an enterprise-level IdP).
-In this case, we use the IdP token directly as an access token to access protected resources on the controller. The controller maintains only enough information needed for access control. Validation of the token is performed by implementation of the `org.opendaylight.aaa.api.TokenAuth` API and can be daisy-chained as resource filters on the controller, with the last filter being the controller's built-in `org.opendaylight.aaa.sts.DirectTokenAuthFilter` to properly register the authentication context.
+For more information, consult ODLJndiLdapRealm and ODLJndiLdapRealmAuthnOnly documentation.
### Authorization & Access Control
NOTE: "aaa:resource" value starts with "/restconf". Unlike the RolesAuthorizationFilter ("roles" in shiro.ini) which is relative to the ServletContext, The MDSALDyanmicAuthorizationFilter is relative to the Servlet Root (i.e., "/"). This is superior, as it is more specific and does not allow for ambiguity.
-2) shiro.ini urls section Authorization roles filter (i.e., "RolesAuthorizationFilter"). [DEPRECATED]
+2) aaa-app-config clustered application configuration "urls" section Authorization roles filter (i.e., "RolesAuthorizationFilter"). [DEPRECATED]
Authorization is implemented via the aaa-shiro modules. RolesAuthorizationFilter (roles filter) is limited purely to RESTCONF (HTTP) and does not focus on MD-SAL.
Code Review / aaa.git / blobdiff