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 ## Caveats
  10 The following caveats are applicable to the current AAA implementation:
  11  - 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
  12  user file synchronised using out of band means.
  13
  14 ## Quick Start
  15
  16 ### Building
  17
  18 *Prerequisite:*  The followings are required for building AAA:
  19
  20 - Maven 3
  21 - Java 7
  22
  23 Get the code:
  24
  25     git clone https://git.opendaylight.org/gerrit/aaa
  26
  27 Build it:
  28
  29     cd aaa && mvn clean install
  30
  31 ### Installing
  32
  33 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).
  34
  35 Start the controller Karaf container:
  36
  37         bin/karaf
  38
  39 Install AAA repository from the Karaf shell:
  40
  41         repo-add mvn:org.opendaylight.aaa/features-aaa/0.1.0-SNAPSHOT/xml/features
  42
  43 Install AAA AuthN features:
  44
  45         feature:install odl-aaa-authn
  46
  47 ### Protecting your REST/RestConf resources
  48
  49 Add the AAA `TokeAuthFilter` filter to your REST resource (RESTconf example):
  50
  51     <servlet>
  52         <servlet-name>JAXRSRestconf</servlet-name>
  53         <servlet-class>com.sun.jersey.spi.container.servlet.ServletContainer</servlet-class>
  54         <init-param>
  55             <param-name>javax.ws.rs.Application</param-name>
  56             <param-value>org.opendaylight.controller.sal.rest.impl.RestconfApplication</param-value>
  57         </init-param>
  58
  59         <!-- Token Auth Filter -->
  60         <init-param>
  61             <param-name>com.sun.jersey.spi.container.ContainerRequestFilters</param-name>
  62             <param-value>
  63                 org.opendaylight.aaa.sts.TokenAuthFilter
  64             </param-value>
  65         </init-param>
  66
  67         <load-on-startup>1</load-on-startup>
  68     </servlet>
  69
  70 Rebuild and re-install your REST resource.
  71
  72 ### Running
  73
  74 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:
  75
  76     curl -s -d 'grant_type=password&username=admin&password=admin&scope=sdn' http://<controller>:<port>/oauth2/token
  77
  78 Upon successful authentication, the controller returns an access token with a configurable expiration in seconds, something similar to the followings:
  79
  80     {"expires_in":3600,"token_type":"Bearer","access_token":"d772d85e-34c7-3099-bea5-cfafd3c747cb"}
  81
  82 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:
  83
  84     curl -s -H 'Authorization: Bearer d772d85e-34c7-3099-bea5-cfafd3c747cb' http://<controller>:<port>/restconf/operational/opendaylight-inventory:nodes
  85
  86 The operational state of access tokens cached in the MD-SAL can also be obtained after enabling the restconf feature:
  87
  88     feature:install odl-aaa-all
  89
  90 At the following URL
  91
  92     http://controller:8181/restconf/operational/aaa-authn-model:tokencache/
  93
  94
  95 ## Framework Overview
  96
  97 ### Authentication
  98
  99 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.
 100
 101 #### Direct
 102
 103 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:
 104
 105 ![](https://wiki.opendaylight.org/images/c/cc/Direct_authn.png)
 106
 107 Here, the Opendaylight controller takes on 3 respective roles:
 108
 109 - *Identity Provider*:  Authenticates a user given some credentials.
 110 - *Authorization Server*:  Determines what roles/permissions an authenticated user has.
 111 - *Resource Provider*:  Provides access to a given resource based on the user's roles/permissions.
 112
 113 The built-in IdP for Opendaylight can be swapped out by a different implementation of the `org.opendaylight.aaa.api.CredentialAuth` API.
 114
 115 #### Federated
 116
 117 In the federated use-case, the responsibility of authentication is delegated to a third-party IdP (perhaps, an enterprise-level IdP):
 118
 119 ![](https://wiki.opendaylight.org/images/f/fd/Federated_authn1.png)
 120
 121 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.
 122
 123 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.
 124
 125 We can also take federation one step further and delegate token management and optionally part of the authorization responsibility to the third-party IdP:
 126
 127 ![](https://wiki.opendaylight.org/images/2/22/Federated_authn2.png)
 128
 129 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.
 130
 131 ### Authorization & Access Control
 132
 133 Authorization is implemented via the aaa-authz modules, comprising of a yang based AuthZ policy schema, an MD-SAL AuthZ capable broker, an AuthZ
 134 service engine invoked by the broker and executing policies.
 135
 136 NOTE: The Lithium release features a trail of Authz functionality, in particular longest string matching is not implemented.
 137
 138 Initially the AuthZ functionality is only able to handle RestConf requests, and to do so the Restconf connector configuration must
 139  be explicitly modified as follows:
 140
 141     0. Compile or obtain the ODL distribution
 142     1. Start karaf and install the odl-aaa-authz feature
 143
 144     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
 145
 146 Default authorization policies are loaded from the configuration subsystem (TODO: Provide a default set)
 147 They are accessible and editable via the restconf interface at:
 148
 149     http://<odl address>/restconf/configuration/authorization-schema:simple-authorization/
 150
 151 The schema for policies is a list consisting of the following items:
 152
 153   * Service : The application service that is the initiator of the request triggering an authorization check, eg Restconf.
 154   NOTE: The service field is currently not enforced, and a wildcard "*" is recommended.
 155   * Action: The action that is being authorized. Maps to one of: { create; read; update; delete; execute; subscribe; any }
 156   * Resource: The URI or Yang instance id of the resource, including wildcards (see examples below)
 157   * Role: The AuthN derived user role
 158
 159 Some examples of resources are:
 160
 161       Data : /operational/opendaylight-inventory:nodes/node/openflow:1/node-connector/openflow:1:1
 162
 163       Wildcarded data: /configuration/opendaylight-inventory:nodes/node/*/node-connector/*
 164
 165       RPC: /operations/example-ops:reboot
 166
 167       Wildcarded RPC: /operations/example-ops:*
 168
 169       Notification: /notifications/example-ops:startup
 170
 171
 172 *More on MD-SAL authorization later...*
 173
 174 ### Accounting
 175
 176 *More on Accounting later...*