README.md

   1 ## Opendaylight AAA
   2
   3 This project is aimed at providing a flexible, pluggable framework with out-of-the-box capabilities for Authentication, Authorization and Accounting (AAA).
   4
   5 ## Caveats
   6 The following caveats are applicable to the current AAA implementation:
   7  - 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.
   8
   9 ## Quick Start
  10
  11 ### Building
  12
  13 *Prerequisite:*  The followings are required for building AAA:
  14
  15 - Maven 3.3.9+
  16 - JDK8
  17 - Python 2.7+ (optional) for running wrapper scripts
  18
  19 Get the code:
  20
  21 Using HTTPS:
  22     git clone https://git.opendaylight.org/gerrit/aaa
  23
  24 USING SSH:
  25     git clone ssh://{USERNAME}@git.opendaylight.org:29418/aaa
  26
  27 Build it:
  28
  29     cd aaa && mvn clean install
  30
  31 ### Installing
  32
  33 AAA is automatically installed upon installation of odl-restconf-noauth and enabled through aaa-shiro-act.
  34
  35 If you are using AAA from a non-RESTCONF context, you can install the necessary javax.servlet.Filter(s) through the following command:
  36
  37         feature:install odl-aaa-shiro
  38
  39 ### Protecting your REST/RestConf resources
  40
  41 Add the `AAAShiroFilter` filter to your REST resource (RESTCONF example):
  42
  43     <servlet>
  44         <servlet-name>JAXRSRestconf</servlet-name>
  45         <servlet-class>com.sun.jersey.spi.container.servlet.ServletContainer</servlet-class>
  46         <init-param>
  47             <param-name>javax.ws.rs.Application</param-name>
  48             <param-value>org.opendaylight.controller.sal.rest.impl.RestconfApplication</param-value>
  49         </init-param>
  50         <!-- Token Auth Filter -->
  51         <init-param>
  52             <param-name>com.sun.jersey.spi.container.ContainerRequestFilters</param-name>
  53             <param-value>
  54                 org.opendaylight.aaa.shiro.filters.AAAShiroFilter
  55             </param-value>
  56         </init-param>
  57         <load-on-startup>1</load-on-startup>
  58     </servlet>
  59
  60 Rebuild and re-install your RESTFUL resource.
  61
  62 ### Running
  63
  64 Once the installation finishes, one can authenticate with the OpenDaylight controller by presenting a username/password and a domain name (scope):
  65
  66     curl -s -d 'grant_type=password&username=admin&password=admin&scope=sdn' http://<controller>:<port>/oauth2/token
  67
  68 Upon successful authentication, the controller returns an access token with a configurable expiration in seconds, something similar to the followings:
  69
  70     {"expires_in":3600,"token_type":"Bearer","access_token":"d772d85e-34c7-3099-bea5-cfafd3c747cb"}
  71
  72 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:
  73
  74     curl -s -H 'Authorization: Bearer d772d85e-34c7-3099-bea5-cfafd3c747cb' http://<controller>:<port>/restconf/operational/opendaylight-inventory:nodes
  75
  76 ## Framework Overview
  77
  78 ### Authentication
  79
  80 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.
  81
  82 #### Direct
  83
  84 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:
  85
  86 ![](https://wiki.opendaylight.org/images/c/cc/Direct_authn.png)
  87
  88 #### Federated
  89
  90 In the federated use-case, the responsibility of authentication is delegated to a third-party IdP (perhaps, an enterprise-level IdP).
  91
  92 For more information, consult ODLJndiLdapRealm and ODLJndiLdapRealmAuthnOnly documentation.
  93
  94 ### Authorization & Access Control
  95
  96 ODL supports two authorization engines at present, both of which are roughly similar in behavior.  Namely, the two authorization engines are the MDSALDynamicAuthorizationFilter(1) and the RolesAuthorizationFilter(2).  For several reasons explained further in this documentation, we STRONGLY encourage you to use the MDSALDyanmicAuthorizationFilter(1) approach over the RolesAuthorizationFilter(2).
  97
  98 1) MDSALDyanmicAuthorizationFilter
  99
 100 The MDSALDynamicAuthorizationFilter is a mechanism used to restrict access to partcular URL endpoint patterns.  Users may define a list of policies that are insertion-ordered.  Order matters for the list of policies, since the first matching policy is applied.  This choice was made to emulate behavior of the Apache Shiro RolesAuthorizationFilter.
 101
 102 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 for the resource.  The following describes the various elements of a policy:
 103
 104 resource:          The resource is a string url pattern as outlined by Apache Shiro.  For more information, see http://shiro.apache.org/web.html.
 105 description:       An optional description of the URL endpoint and why it is being secured.
 106 permissions list:  A list of permissions for a particular policy.  If more than one permission exists in the permissions list, the permissions are evaluted using logical "OR".
 107
 108 A permission describes the prerequisites to perform HTTP operations on a particular endpoint.  The following describes the various elements of a permission:
 109
 110 role:              The role required to access the target URL endpoint.
 111 actions list:      A leaf-list of HTTP permissions that are allowed for a Subject possessing the required role.
 112
 113 ---------
 114 Example:
 115
 116 To limit access to the modules endpoint, issue the following:
 117
 118 HTTP Operation:    put
 119 URL:               /restconf/config/aaa:http-authorization/policies
 120 Headers:
 121     Content-Tye:       application/json
 122     Accept:            application/json
 123
 124 Body:
 125
 126 {
 127   "aaa:policies": {
 128     "aaa:policies": [
 129       {
 130         "aaa:resource": "/restconf/modules/**",
 131         "aaa:permissions": [
 132           {
 133             "aaa:role": "admin",
 134             "aaa:actions": [
 135               "get","post","put","patch","delete"
 136             ]
 137           }
 138         ]
 139       }
 140     ]
 141   }
 142 }
 143 --------
 144 The above example locks down access to the modules endpoint (and any URLS available past modules) to the "admin" role.  Thus, an attempt from the OOB admin user will succeed with 2XX HTTP status code, while an attempt from the OOB "user" user will fail with HTTP status code 401, as the "user" user is not granted the "admin" role.
 145
 146 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.
 147
 148 2) aaa-app-config clustered application configuration "urls" section Authorization roles filter (i.e., "RolesAuthorizationFilter"). [DEPRECATED]
 149
 150 Authorization is implemented via the aaa-shiro modules.  RolesAuthorizationFilter (roles filter) is limited purely to RESTCONF (HTTP) and does not focus on MD-SAL.
 151
 152 More information on how to configure authorization can be found on the Apache Shiro website:
 153
 154     http://shiro.apache.org/web.html
 155
 156 NOTE:  Use of shiro.ini urls section to define roles requirements is discouraged!  This is due to the fact that shiro.ini changes are only recognized on servlet container startup.  Changes to shiro.ini are only honored upon restart.
 157
 158 NOTE:  Use of shiro.ini urls section to define roles requirements is discouraged!  This is due to the fact that url patterns are matched relative to the servlet context.  This leaves room for ambiguity, since many endpoints may match (i.e., "/restconf/modules" and "/auth/modules" would both match a "/modules/**" rule).
 159
 160 ### Accounting
 161
 162 Accounting is handled through the standard slf4j logging mechanisms used by the rest of OpenDaylight.  Thus, one can control logging verbosity through manipulating the log levels for individual packages and classes directly through the karaf shell, JMX, or etc/org.ops4j.pax.logging.cfg.  In normal operations, the default levels exposed do not provide much information about AAA services;  this is due to the fact that logging can severely degrade performance.
 163
 164 Two noteworthy logging activities are:
 165 1) Enable debugging logging
 166 2) Enable successful/unsuccessful authentication attempts logging
 167
 168 #### Enable Debugging Logging
 169
 170 For debugging purposes (i.e., to enable maximum verbosity), issue the following command:
 171
 172 karaf> log:set TRACE org.opendaylight.aaa
 173
 174 #### Enable Successful/Unsuccessful Authentication Attempts Logging
 175 By default, successful/unsuccessful authentication attempts are NOT logged.  This is due to the fact that logging can severely decrease REST performance.  To enable logging of successful/unsuccessful REST attempts, issue the following command:
 176
 177 karaf> log:set DEBUG org.opendaylight.aaa.shiro.filters.AuthenticationListener
 178
 179 It is possible to add custom AuthenticationListener(s) to the Shiro based configuration, allowing different ways to listen for successful/unsuccessful authentication attempts.  Custom AuthenticationListener(s) must implement the org.apache.shiro.authc.AuthenticationListener interface.