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 - Maven 3
  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 Karaf installation.  If you don't have an Opendaylight installation, please refer to this [page](https://wiki.opendaylight.org/view/OpenDaylight_Controller:Installation).
  29
  30 Start the controller Karaf container:
  31
  32         bin/karaf
  33
  34 Install AAA repository from the Karaf shell:
  35
  36         repo-add mvn:org.opendaylight.aaa/features-aaa/0.1.0-SNAPSHOT/xml/features
  37
  38 Install all AAA features:
  39
  40         feature:install odl-aaa-all
  41
  42 ### Protecting your REST/RestConf resources
  43
  44 Add the AAA `TokeAuthFilter` filter to your REST resource (RESTconf example):
  45
  46     <servlet>
  47         <servlet-name>JAXRSRestconf</servlet-name>
  48         <servlet-class>com.sun.jersey.spi.container.servlet.ServletContainer</servlet-class>
  49         <init-param>
  50             <param-name>javax.ws.rs.Application</param-name>
  51             <param-value>org.opendaylight.controller.sal.rest.impl.RestconfApplication</param-value>
  52         </init-param>
  53
  54         <!-- Token Auth Filter -->
  55         <init-param>
  56             <param-name>com.sun.jersey.spi.container.ContainerRequestFilters</param-name>
  57             <param-value>
  58                 org.opendaylight.aaa.sts.TokenAuthFilter
  59             </param-value>
  60         </init-param>
  61
  62         <load-on-startup>1</load-on-startup>
  63     </servlet>
  64
  65 Rebuild and re-install your REST resource.
  66
  67 ### Running
  68
  69 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:
  70
  71     curl -s -d 'grant_type=password&username=admin&password=admin&scope=sdn' http://<controller>:<port>/oauth2/token
  72
  73 Upon successful authentication, the controller returns an access token with a configurable expiration in seconds, something similar to the followings:
  74
  75     {"expires_in":3600,"token_type":"Bearer","access_token":"d772d85e-34c7-3099-bea5-cfafd3c747cb"}
  76
  77 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:
  78
  79     curl -s -H 'Authorization: Bearer d772d85e-34c7-3099-bea5-cfafd3c747cb' http://<controller>:<port>/restconf/operational/opendaylight-inventory:nodes
  80
  81 ## Framework Overview
  82
  83 ### Authentication
  84
  85 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.
  86
  87 #### Direct
  88
  89 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:
  90
  91 ![](https://wiki.opendaylight.org/images/c/cc/Direct_authn.png)
  92
  93 Here, the Opendaylight controller takes on 3 respective roles:
  94
  95 - *Identity Provider*:  Authenticates a user given some credentials.
  96 - *Authorization Server*:  Determines what roles/permissions an authenticated user has.
  97 - *Resource Provider*:  Provides access to a given resource based on the user's roles/permissions.
  98
  99 The built-in IdP for Opendaylight can be swapped out by a different implementation of the `org.opendaylight.aaa.api.CredentialAuth` API.
 100
 101 #### Federated
 102
 103 In the federated use-case, the responsibility of authentication is delegated to a third-party IdP (perhaps, an enterprise-level IdP):
 104
 105 ![](https://wiki.opendaylight.org/images/f/fd/Federated_authn1.png)
 106
 107 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.
 108
 109 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.
 110
 111 We can also take federation one step further and delegate token management and optionally part of the authorization responsibility to the third-party IdP:
 112
 113 ![](https://wiki.opendaylight.org/images/2/22/Federated_authn2.png)
 114
 115 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.
 116
 117 ### Authorization & Access Control
 118
 119 Authorization is implemented via the aaa-authz modules, comprising of a yang based AuthZ policy schema, an MD-SAL AuthZ capable broker, an AuthZ
 120 service engine invoked by the broker and executing policies.
 121
 122 NOTE: The Helium release features a trail of Authz functionality, in particular longest string matching is not implemented.
 123
 124 Initially the AuthZ functionality is only able to handle RestConf requests, and to do so the Restconf connector configuration must
 125  be explicitly modified as follows:
 126
 127     0. Compile as per the above instructions
 128
 129     1. If you have already run ODL with Restconf or the mdsal-all feature package under karaf, then proceed as per 1b, otherwise skip to step 2.
 130
 131       1a.  consider deleting the assembly/data directory in your karaf install. This will require the re-activation of features at karaf startup.
 132
 133     2. Start karaf and install the odl-aaa-all feature as per the previous instructions
 134
 135     Note: At this stage, with a default configuration, there is no MD-SAL data to test against. To test you can install the toaster service using feature:install odl-toaster
 136
 137
 138 To uninstall authz:
 139
 140     1. Unistall the feature via "feature:uninstall feature:odl-aaa-authz"
 141     2. Delete the 09-rest-connector.xml configuration file in <your karaf distribution directory>/etc/opendaylight/karaf/.
 142     3. Reinstall resctonf via the command "feature:install odl-resctonf"
 143
 144 Legacy instructions for activating Authz in non karaf based ODL runtimes:
 145
 146     0. Build aaa project and copy all generated aaa jars to the plugins directory of your odl target install
 147     1. Locate and open in an editor the default 10-rest-connector.xml configuration file. Default location is at 'configuration/initial'
 148     2. Change the <dom-broker> configuration element
 149       FROM:
 150                     <dom-broker>
 151                          <type xmlns:dom="urn:opendaylight:params:xml:ns:yang:controller:md:sal:dom">dom:dom-broker-osgi-registry</type>
 152                          <name>dom-broker</name>
 153                      </dom-broker>
 154       TO:
 155                     <dom-broker>
 156                          <type xmlns:dom="urn:opendaylight:params:xml:ns:yang:controller:md:sal:dom">dom:dom-broker-osgi-registry</type>
 157                          <name>authz-connector-default</name>
 158                      </dom-broker>
 159     3. Restart ODL
 160
 161 Default authorization are loaded from the configuration subsystem (TODO: Provide a default set)
 162 They are accessible and editable via the restconf interface at:
 163
 164     http://<odl address>/restconf/configuration/authorization-schema:simple-authorization/
 165
 166 The schema for policies is a list consisting of the following items:
 167
 168   * Service : The application service that is the initiator of the request triggering an authorization check, eg Restconf.
 169   NOTE: The service field is currently not enforced, and a wildcard "*" is recommended.
 170   * Action: The action that is being authorized. Maps to one of: { create; read; update; delete; execute; subscribe; any }
 171   * Resource: The URI or Yang instance id of the resource, including wildcards (see examples below)
 172   * Role: The AuthN derived user role
 173
 174 Some examples of resources are:
 175
 176       Data : /operational/opendaylight-inventory:nodes/node/openflow:1/node-connector/openflow:1:1
 177
 178       Wildcarded data: /configuration/opendaylight-inventory:nodes/node/*/node-connector/*
 179
 180       RPC: /operations/example-ops:reboot
 181
 182       Wildcarded RPC: /operations/example-ops:*
 183
 184       Notification: /notifications/example-ops:startup
 185
 186
 187 *More on MD-SAL authorization later...*
 188
 189 ### Accounting
 190
 191 *More on Accounting later...*