README.md

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