README.md

   1 ## Welcome to the Opendaylight AAA Project!
   2
   3 This project is aimed at providing a flexible, pluggable framework with out-of-the-box capabilities for:
   4
   5 * *Authentication*:  Means to authenticate the identity of both human and machine users (direct or federated).
   6 * *Authorization*:  Means to authorize human or machine user access to resources including RPCs, notification subscriptions, and subsets of the datatree.
   7 * *Accounting*:  Means to record and access the records of human or machine user access to resources including RPCs, notifications, and subsets of the datatree
   8
   9 ## Quick Start
  10
  11 ### Building
  12
  13 *Prerequisite:*  The followings are required for building AAA:
  14
  15 - Maven3
  16 - Java 7
  17
  18 Get the code:
  19
  20     git clone https://git.opendaylight.org/gerrit/aaa
  21
  22 Build it:
  23
  24     cd aaa && mvn clean install
  25
  26 ### Installing
  27
  28 AAA installs into an existing Opendaylight controller installation.  If you don't have an Opendaylight installation, please refer to this [page](https://wiki.opendaylight.org/view/OpenDaylight_Controller:Installation).
  29
  30     ./install <your controller installation dir>/distribution/opendaylight/target/distribution.opendaylight-?.?.?-SNAPSHOT-osgipackage/opendaylight
  31
  32 ### Protecting your REST/RestConf resources
  33
  34 Add the AAA `TokeAuthFilter` filter to your REST resource (RESTconf example):
  35
  36     <servlet>
  37         <servlet-name>JAXRSRestconf</servlet-name>
  38         <servlet-class>com.sun.jersey.spi.container.servlet.ServletContainer</servlet-class>
  39         <init-param>
  40             <param-name>javax.ws.rs.Application</param-name>
  41             <param-value>org.opendaylight.controller.sal.rest.impl.RestconfApplication</param-value>
  42         </init-param>
  43
  44         <!-- Token Auth Filter -->
  45         <init-param>
  46             <param-name>com.sun.jersey.spi.container.ContainerRequestFilters</param-name>
  47             <param-value>
  48                 org.opendaylight.aaa.sts.TokenAuthFilter
  49             </param-value>
  50         </init-param>
  51
  52         <load-on-startup>1</load-on-startup>
  53     </servlet>
  54
  55 Rebuild and re-install your REST resource.
  56
  57 ### Running
  58
  59 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:
  60
  61     curl -s -d 'grant_type=password&username=admin&password=odl&scope=pepsi' http://localhost:8080/oauth2/token
  62
  63 Upon successful authentication, the controller returns an access token with a configurable expiration in seconds, something similar to the followings:
  64
  65     {"expires_in":3600,"token_type":"Bearer","access_token":"d772d85e-34c7-3099-bea5-cfafd3c747cb"}
  66
  67 The access token can then be used to access protected resources on the controller by passing it along in the standard HTTP Authorization header with the resource request.  Example:
  68
  69     curl -s -H 'Authorization: Bearer d772d85e-34c7-3099-bea5-cfafd3c747cb' http://localhost:8080/restconf/operational/opendaylight-inventory:nodes
  70
  71 ## Framework Overview
  72
  73 ### Authentication
  74
  75 AAA supports 2 main authentication use-cases:  *direct* and *federated* authentication, with direct authentication being the simpler to deploy (i.e., no external system dependency) and hence being the out-of-the-box authentication mechanism.
  76
  77 #### Direct
  78
  79 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:
  80
  81 ![](https://wiki.opendaylight.org/images/c/cc/Direct_authn.png)
  82
  83 Here, the Opendaylight controller takes on 3 respective roles:
  84
  85 - *Identity Provider*:  Authenticates a user given some credentials.
  86 - *Authorization Server*:  Determines what roles/permissions an authenticated user has.
  87 - *Resource Provider*:  Provides access to a given resource based on the user's roles/permissions.
  88
  89 The built-in IdP for Opendaylight can be swapped out by a different implementation of the `org.opendaylight.aaa.api.CredentialAuth` API.
  90
  91 #### Federated
  92
  93 In the federated use-case, the responsibility of authentication is delegated to a third-party IdP (perhaps, an enterprise-level IdP):
  94
  95 ![](https://wiki.opendaylight.org/images/f/fd/Federated_authn1.png)
  96
  97 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.
  98
  99 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.
 100
 101 We can also take federation one step further and delegate token management and optionally part of the authorization responsibility to the third-party IdP:
 102
 103 ![](https://wiki.opendaylight.org/images/2/22/Federated_authn2.png)
 104
 105 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.
 106
 107 ### Authorization & Access Control
 108
 109 Upon successful authentication, an authentication context is created and is available for access via the OSGi service `org.opendaylight.aaa.api.AuthenticationService`.  The authentication context consists of the following information:
 110
 111 * UserId/Name
 112 * DomainId/Name
 113 * Roles
 114
 115 Based on the current authentication context, it is the responsibility of the OSGi applications within the controller to provide the appropriate access control, via bespoke logic or the MD-SAL security framework.
 116
 117 *More on MD-SAL authorization later...*
 118
 119 ### Accounting
 120
 121 *More on Accounting later...*