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,
   4 Authorization and Accounting (AAA).
   5
   6 ## Caveats
   7 The following caveats are applicable to the current AAA implementation:
   8  - The database (H2) used by ODL AAA Authentication store is not-cluster enabled. When deployed in a clustered
   9  environment each node contains unique local credentials.
  10  - AAA provides two local IdP Realm implementations; TokenAuthRealm and MdsalRealm.  Although the use of both Realms at
  11  the same time is possible through Shiro's multi-realm approach, it is considered bad practice to provide two local
  12  identity stores.  Thus, users should specify one or the other for $securityManager.realms entry in the aaa-app-config
  13  configuration.
  14  - The MdsalRealm is not initialized with any Users, Roles, Domains, or Grants.  The ability to add OOB Identity
  15  Information is considered separate work, and is targeted for the Fluorine release.
  16
  17 ## Quick Start
  18
  19 ### Building
  20
  21 *Prerequisite:*  The followings are required for building AAA:
  22
  23 - Maven 3.5.2+
  24 - JDK8
  25 - Python 2.7+ (optional) for running wrapper scripts
  26
  27 Get the code:
  28
  29 Using HTTPS:
  30     git clone https://git.opendaylight.org/gerrit/aaa
  31
  32 USING SSH:
  33     git clone ssh://{USERNAME}@git.opendaylight.org:29418/aaa
  34
  35 Build it:
  36
  37     cd aaa && mvn clean install
  38
  39 ### Installing
  40
  41 AAA is automatically installed upon installation of odl-restconf-noauth and enabled through aaa-shiro-act.
  42
  43 If you are using AAA from a non-RESTCONF context, you can install the necessary javax.servlet.Filter(s) through the
  44 following command:
  45
  46         karaf> feature:install odl-aaa-shiro
  47
  48 ### Running
  49
  50 Once the installation finishes, one can authenticate with the OpenDaylight controller by presenting a username/password
  51 and a domain name (scope):
  52
  53     curl -s -d 'grant_type=password&username=admin&password=admin&scope=sdn' http://<controller>:<port>/oauth2/token
  54
  55 Upon successful authentication, the controller returns an access token with a configurable expiration in seconds,
  56 something similar to the followings:
  57 ```json
  58 {
  59   "expires_in": 3600,
  60   "token_type": "Bearer",
  61   "access_token": "d772d85e-34c7-3099-bea5-cfafd3c747cb"
  62 }
  63 ```
  64 The access token can then be used to access protected resources on the controller by passing it along in the standard
  65 HTTP Authorization header with the resource request.  Example:
  66
  67     curl -s -H 'Authorization: Bearer d772d85e-34c7-3099-bea5-cfafd3c747cb' \
  68     http://<controller>:<port>/restconf/operational/opendaylight-inventory:nodes
  69
  70 ### Defaults
  71
  72 Although it is poor security practice, AAA's TokenAuthRealm creates some defaults out of the box.  In order to avoid
  73 default credentials, please see the aaa-cli-jar module, which allows installers to pre-install identity information.
  74 Due to the fact that OpenDaylight does not have a proper installer project, default credentials become a
  75 chicken/egg problem.  The choice to utilize defaults was initially decided to help bootstrap interaction with ODL's
  76 restful web services.  AAA's TokenAuthRealm creates:
  77 * the "sdn" domain
  78 * the "admin" and "user" roles
  79 * the "admin" user with "admin" password
  80 * 2 grants
  81   * admin user is granted admin role privileges on sdn domain
  82   * admin user is granted user role privileges on sdn domain
  83
  84 TokenAuthRealm's H2 file-based database, which stores the identity information, is secured with default credentials
  85 "foo"/"bar".  Default credentials on the local file-based database is a smaller concern, since without running an H2
  86 Server instance on the local machine (ODL doesn't by default), the database is only accessible locally (i.e., user in
  87 front of keyboard).  However, these credentials can be adjusted too by setting "dbUsername" and "dbPassword" within
  88 etc/org.opendaylight.aaa.h2.cfg.
  89
  90 ## Framework Overview
  91
  92 ### Authentication
  93
  94 AAA supports 2 main authentication use-cases:  *direct* and *federated* authentication, with direct authentication being
  95 the simpler to deploy (i.e., no external system dependency) and hence being the out-of-the-box authentication mechanism.
  96
  97 #### Direct
  98
  99 In this use-case, a user presents some credentials (e.g., username/password) directly to the Opendaylight (ODL)
 100 controller token endpoint `/oauth2/token` and receives an access token, which then can be used to access protected
 101 resources on the controller, similar to the example we saw in the Quickstart section.
 102
 103 #### Federated
 104
 105 In the federated use-case, the responsibility of authentication is delegated to a third-party IdP (perhaps, an
 106 enterprise-level IdP).
 107
 108 For more information, consult ODLJndiLdapRealm and ODLJndiLdapRealmAuthnOnly documentation.
 109
 110 ### Authorization & Access Control
 111
 112 ODL supports two authorization engines at present, both of which are roughly similar in behavior.  Namely, the two
 113 authorization engines are the MDSALDynamicAuthorizationFilter(1) and the RolesAuthorizationFilter(2).  For several
 114 reasons explained further in this documentation, we STRONGLY encourage you to use the MDSALDyanmicAuthorizationFilter(1)
 115 approach over the RolesAuthorizationFilter(2).
 116
 117 1) MDSALDyanmicAuthorizationFilter
 118
 119 The MDSALDynamicAuthorizationFilter is a mechanism used to restrict access to partcular URL endpoint patterns.  Users
 120 may define a list of policies that are insertion-ordered.  Order matters for the list of policies, since the first
 121 matching policy is applied.  This choice was made to emulate behavior of the Apache Shiro RolesAuthorizationFilter.
 122
 123 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
 124 for the resource.  The following describes the various elements of a policy:
 125
 126 resource:          The resource is a string url pattern as outlined by Apache Shiro.  For more information,
 127                    see http://shiro.apache.org/web.html.
 128 description:       An optional description of the URL endpoint and why it is being secured.
 129 permissions list:  A list of permissions for a particular policy.  If more than one permission exists in the permissions
 130                    list, the permissions are evaluted using logical "OR".
 131
 132 A permission describes the prerequisites to perform HTTP operations on a particular endpoint.  The following describes
 133 the various elements of a permission:
 134
 135 role:              The role required to access the target URL endpoint.
 136 actions list:      A leaf-list of HTTP permissions that are allowed for a Subject possessing the required role.
 137
 138 ---------
 139 Example:
 140
 141 To limit access to the modules endpoint, issue the following:
 142
 143 HTTP Operation:    put
 144 URL:               /restconf/config/aaa:http-authorization/policies
 145 Headers:
 146     Content-Tye:       application/json
 147     Accept:            application/json
 148
 149 Body:
 150 ```json
 151 {
 152   "aaa:policies": {
 153     "aaa:policies": [
 154       {
 155         "aaa:resource": "/restconf/modules/**",
 156         "aaa:permissions": [
 157           {
 158             "aaa:role": "admin",
 159             "aaa:actions": [
 160               "get","post","put","patch","delete"
 161             ]
 162           }
 163         ]
 164       }
 165     ]
 166   }
 167 }
 168 ```
 169 --------
 170 The above example locks down access to the modules endpoint (and any URLS available past modules) to the "admin" role.
 171 Thus, an attempt from the OOB admin user will succeed with 2XX HTTP status code, while an attempt from the OOB "user"
 172 user will fail with HTTP status code 401, as the "user" user is not granted the "admin" role.
 173
 174 NOTE:  "aaa:resource" value starts with "/restconf".  Unlike the RolesAuthorizationFilter whichis relative to the
 175 ServletContext, The MDSALDyanmicAuthorizationFilter is relative to the Servlet Root (i.e., "/"). This is superior, as it
 176 is more specific and does not allow for ambiguity.
 177
 178 2) aaa-app-config clustered application configuration "urls" section Authorization roles filter (i.e.,
 179 "RolesAuthorizationFilter"). [DEPRECATED]
 180
 181 Authorization is implemented via the aaa-shiro modules.  RolesAuthorizationFilter (roles filter) is limited purely to
 182 RESTCONF (HTTP) and does not focus on MD-SAL.
 183
 184 More information on how to configure authorization can be found on the Apache Shiro website: http://shiro.apache.org/web.html
 185
 186 NOTE:  Use of aaa-app-config.xml urls section to define roles requirements is discouraged!  This is due to the fact that
 187 aaa-app-config.xml changes are only recognized on servlet container startup.  Changes to aaa-app-config.xml are only
 188 honored upon restart.
 189
 190 NOTE:  Use of aaa-app-config.xml urls section to define roles requirements is discouraged!  This is due to the fact that
 191 url patterns are matched relative to the servlet context.  This leaves room for ambiguity, since many endpoints may
 192 match (i.e., "/restconf/modules" and "/auth/modules" would both match a "/modules/**" rule).
 193
 194 ### Accounting
 195
 196 Accounting is handled through the standard slf4j logging mechanisms used by the rest of OpenDaylight.  Thus, one can
 197 control logging verbosity through manipulating the log levels for individual packages and classes directly through the
 198 karaf shell, JMX, or etc/org.ops4j.pax.logging.cfg.  In normal operations, the default levels exposed do not provide
 199 much information about AAA services;  this is due to the fact that logging can severely degrade performance.
 200
 201 Two noteworthy logging activities are:
 202 1) Enable debugging logging
 203 2) Enable successful/unsuccessful authentication attempts logging
 204
 205 #### Enable Debugging Logging
 206
 207 For debugging purposes (i.e., to enable maximum verbosity), issue the following command:
 208
 209     karaf> log:set TRACE org.opendaylight.aaa
 210
 211 #### Enable Successful/Unsuccessful Authentication Attempts Logging
 212 By default, successful/unsuccessful authentication attempts are NOT logged.  This is due to the fact that logging can
 213 severely decrease REST performance.  To enable logging of successful/unsuccessful REST attempts, issue the following
 214 command:
 215
 216     karaf> log:set DEBUG org.opendaylight.aaa.shiro.filters.AuthenticationListener
 217
 218 It is possible to add custom AuthenticationListener(s) to the Shiro based configuration, allowing different ways to
 219 listen for successful/unsuccessful authentication attempts.  Custom AuthenticationListener(s) must implement the
 220 org.apache.shiro.authc.AuthenticationListener interface.