manuals/user-guide/src/main/asciidoc/aaa/aaa.adoc

   1 == Authentication and Authorization Services\r
   2 \r
   3 === Authentication Service\r
   4 Authentication uses the credentials presented by a user to identify the user.\r
   5 \r
   6 NOTE: The Authentication user store provided in the Lithium release does not fully support a clustered node deployment. Specifically, the AAA user store provided by the H2 database needs to be synchronized using out of band means. The AAA Token cache is however cluster-capable.\r
   7 \r
   8 ==== Authentication data model\r
   9 A user requests authentication within a domain in which the user has defined roles.\r
  10 The user chooses either of the following ways to request authentication:\r
  11 \r
  12 * Provides credentials\r
  13 * Creates a token scoped to a domain. In OpenDaylight, a domain is a grouping of resources (direct or indirect, physical, logical, or virtual) for the purpose of access control.\r
  14 \r
  15 ===== Terms and definitions in the model\r
  16 Token:: A claim of access to a group of resources on the controller\r
  17 Domain:: A group of resources, direct or indirect, physical, logical, or virtual, for the purpose of access control\r
  18 User:: A person who either owns or has  access to a resource or group of resources on the controller\r
  19 Role:: Opaque representation of a set of permissions, which is merely a unique string as admin or guest\r
  20 Credential:: Proof of identity such as username and password, OTP, biometrics, or others\r
  21 Client:: A service or application that requires access to the controller\r
  22 Claim:: A data set of validated assertions regarding a user, e.g. the role, domain, name, etc.\r
  23 \r
  24 ===== Authentication methods\r
  25 There are three ways a user may authenticate in OpenDaylight: +\r
  26 \r
  27 * Basic HTTP Authentication\r
  28 ** Regular, non-token based, authentication with username/password.\r
  29 * Token-based Authentication\r
  30 ** Direct authentication:  A user presents username/password and a domain the user wishes to access to the controller and obtains a timed (default is 1 hour) scoped access token.  The user then uses this token to access RESTCONF (for example).\r
  31 ** Federated authentication:  A user presents credentials to a third-party Identity Provider (for example, SSSD) trusted by the controller.  Upon successful authentication, the controller returns a refresh (unscoped) token with a list of domains that the user has access to.  The user then presents this refresh token scoped to a domain that the user has access to obtain a scoped access token.  The user then uses this access token to access RESTCONF (for example).\r
  32 \r
  33 \r
  34 ====== Example with token authentication using curl:\r
  35 \r
  36 (username/password = admin/admin, domain = sdn)\r
  37 \r
  38 [source,bash] \r
  39 ----\r
  40 # Create a token\r
  41 curl -ik -d 'grant_type=password&username=admin&password=admin&scope=sdn' http://localhost:8181/oauth2/token\r
  42 \r
  43 # Use the token (e.g.,  ed3e5e05-b5e7-3865-9f63-eb8ed5c87fb9) obtained from above (default token validity is 1 hour):\r
  44 curl -ik -H 'Authorization:Bearer ed3e5e05-b5e7-3865-9f63-eb8ed5c87fb9' http://localhost:8181/restconf/config/toaster:toaster\r
  45 ----\r
  46 \r
  47 ====== Example with basic HTTP auth using curl: +\r
  48 \r
  49 [source,bash] \r
  50 ---- \r
  51 curl -ik -u 'admin:admin' http://localhost:8181/restconf/config/toaster:toaster\r
  52 ----\r
  53 \r
  54 ==== How the OpenDaylight Authentication Service works\r
  55 In direct authentication, a service relationship exists between the user and the OpenDaylight controller. The user and the controller establish trust that allows them to use, and validate credentials.\r
  56 The user establishes user identity through credentials.\r
  57 \r
  58 In direct authentication, a user request progresses through the following steps:\r
  59 \r
  60 . The user requests the controller administrator for a  user account.  \r
  61 +\r
  62 :: Associated with the user account are user credentials, initially created by the administrator.  OpenDaylight supports only username/password credentials. By default, an administrator account is present in OpenDaylight out-of-the-box with the default username and password being admin/admin.  \r
  63 In addition to creating the user account, the controller administrator also assigns roles to that account on one or more domain.  By default, there are two user roles; admin, and user, and there is only one domain; sdn.\r
  64 +\r
  65 . The user presents credentials in a token request to the token service within a domain.  \r
  66 . The request is then passed on to the controller token endpoint.\r
  67 . The controller token endpoint uses the credential authentication entity which returns a claim for the client. \r
  68 . The controller token entity transforms the claim (user, domain, and roles) into a token which it then provides to the user.\r
  69 \r
  70 In federated authentication, with the absence of a direct trust relationship between the user and the service, a third-party Identity Provider (IdP) is used for authentication. Federated authentication relies on third-party identity providers (IdP) to authenticate the user.\r
  71 \r
  72 The user is authenticated by the trusted IdP and a claim is returned to the OpenDaylight authentication service.  The claim is transformed into an OpenDaylight claim and successively into a token that is passed on to the user. \r
  73 \r
  74 In a federated authentication set-up, the OpenDaylight controller AAA module provides SSSD claim support. SSSD can be used to map users in an external LDAP server to users defined on the OpenDaylight controller.\r
  75 \r
  76 ==== Configuring Authentication service\r
  77 Changes to AAA configurations can be made as follows:\r
  78 \r
  79 For Authentication functionality via one of:\r
  80 \r
  81 * Webconsole\r
  82 * CLI (config command in the Karaf shell)\r
  83 * Editing the etc/org.opendaylight.aaa.*.cfg files directly\r
  84 \r
  85 For Token Cache Store settings via one of:\r
  86 \r
  87 * Editing the 08-authn-config.xml configuration file in etc/opendaylight/karaf\r
  88 * Using RESTCONF\r
  89 \r
  90 NOTE: Configurations for AAA are all dynamic and require no restart.\r
  91 \r
  92 ===== Configuring Authentication\r
  93 \r
  94 To configure features from the Web console: +\r
  95 \r
  96 . Install the Web console:\r
  97 +\r
  98 ----\r
  99 feature:install webconsole\r
 100 ----\r
 101 +\r
 102 . On the console (http://localhost:8181/system/console) (default Karaf username/password:  karaf/karaf), go to *OSGi* > *Configuration* > *OpenDaylight AAA Authentication Configuration*.\r
 103 .. *Authorized Clients*:  List of software clients that are authorized to access OpenDaylight northbound APIs.\r
 104 .. *Enable Authentication*:  Enable or disable authentication. (The default is enable.)\r
 105 \r
 106 ===== Configuring the token store\r
 107 . Open in a text editor etc/opendaylight/karaf/08-authn-config.xml\r
 108 :: The fields you can configure are as follows:\r
 109 .. *timeToLive*: Configure the maximum time, in milliseconds, that tokens are to be cached. Default is 360000.\r
 110 . Save the file.\r
 111 \r
 112 NOTE: When token's are expired, they are lazily removed from the cache.\r
 113 \r
 114 ===== Configuring AAA federation\r
 115 \r
 116 . On the console, click *OpenDaylight AAA Federation Configuration*.\r
 117 . Use the *Custom HTTP Headers* or *Custom HTTP Attributes* fields to specify the HTTP headers or attributes for federated authentication. Normally, additional specification beyond the default is not \r
 118 required.\r
 119 \r
 120 NOTE: As the changes you make to the configurations are automatically committed when they are saved, no restart of the Authentication service is required.\r
 121 \r
 122 ====== Configuring federated authentication\r
 123 Use the following steps to set up federated authentication: +\r
 124 \r
 125 . Set up an Apache front-end and Apache mods for the OpenDaylight controller.\r
 126 . Set up mapping rules (from LDAP users to OpenDaylight users).\r
 127 . Use the ClaimAuthFilter in federation to allow claim transformation.\r
 128 \r
 129 ====== Mapping users to roles and domains\r
 130 The OpenDaylight authentication service transforms assertions from an external federated IdP into Authentication Service data: +\r
 131 \r
 132 . The Apache web server which fronts OpenDaylight AAA sends data to SssdAuthFilter.\r
 133 . SssdAuthFilter constructs a JSON document from the data.\r
 134 . OpenDaylight Authentication Service uses a general purpose transformation mapper to transform the JSON document.\r
 135 \r
 136 ====== Operational model\r
 137 The mapping model works as follows: +\r
 138 \r
 139 . Assertions from an IdP are stored in an associative array.\r
 140 . A sequence of rules is applied, and the first rule which returns success is considered a match.\r
 141 . Upon success, an associative array of mapped values is returned.\r
 142 \r
 143 ** The mapped values are taken from the local variables set during the rule execution.\r
 144 ** The definition of the rules and mapped results are expressed in JSON notation.\r
 145 \r
 146 ====== Operational Model: Sample code\r
 147 [source,java]\r
 148 ----\r
 149 mapped = null\r
 150 foreach rule in rules {\r
 151     result = null\r
 152     initialize rule.variables with pre-defined values\r
 153 \r
 154     foreach block in rule.statement_blocks {\r
 155         for statement in block.statements {\r
 156             if statement.verb is exit {\r
 157                 result = exit.status\r
 158                 break\r
 159             }\r
 160             elif statement.verb is continue {\r
 161                 break\r
 162             }\r
 163         }\r
 164         if result {\r
 165             break\r
 166         }\r
 167     if result == null {\r
 168         result = success\r
 169     }\r
 170 if result == success {\r
 171     mapped = rule.mapping(rule.variables)\r
 172 }\r
 173 return mapped\r
 174 ----\r
 175 \r
 176 ====== Mapping Users\r
 177 A JSON Object acts as a mapping template to produce the final associative array of name/value pairs. The value in a name/value pair can be a constant or a variable.\r
 178 An example of a mapping template and rule variables in JSON: +\r
 179 Template: +\r
 180 [source,json]\r
 181 ----\r
 182 {\r
 183     "organization": "BigCorp.com",\r
 184     "user: "$subject",\r
 185     "roles": "$roles"\r
 186 }\r
 187 ----\r
 188 Local variables: +\r
 189 [source,json]\r
 190 ----\r
 191 {\r
 192     "subject": "Sally",\r
 193     "roles": ["user", "admin"]\r
 194 }\r
 195 ----\r
 196 The final mapped result will be: +\r
 197 [source,json]\r
 198 ----\r
 199 {\r
 200     "organization": "BigCorp.com",\r
 201     "user: "Sally",\r
 202     "roles": ["user", "admin"]\r
 203 }\r
 204 ----\r
 205 \r
 206 ====== Example: Splitting a fully qualified username into user and realm components\r
 207 Some IdPs return a fully qualified username (for example, principal or subject). The fully qualified username is the concatenation of the user name, separator, and realm name.\r
 208 The following example shows the mapped result that returns the user and realm as independent values for the fully qualified username is bob@example.com .\r
 209 \r
 210 The mapping in JSON: +\r
 211 [source,json]\r
 212 ----\r
 213 {\r
 214     "user": "$username",\r
 215     "realm": "$domain"\r
 216 }\r
 217 ----\r
 218 The assertion in JSON: +\r
 219 [source,json]\r
 220 ----\r
 221 {\r
 222     "Principal": "bob@example.com"\r
 223 }\r
 224 ----\r
 225 The rule applied: +\r
 226 [source,json]\r
 227 ----\r
 228 [\r
 229     [\r
 230         ["in", "Principal", "assertion"],\r
 231         ["exit", "rule_fails", "if_not_success"],\r
 232         ["regexp", "$assertion[Principal]", (?P<username>\\w+)@(?P<domain>.+)"],\r
 233         ["set", "$username", "$regexp_map[username]"],\r
 234         ["set", "$domain", "$regexp_map[domain]"],\r
 235         ["exit, "rule_succeeds", "always"]\r
 236     ]\r
 237 ]\r
 238 ----\r
 239 The mapped result in JSON: +\r
 240 [source,json]\r
 241 ----\r
 242 {\r
 243     "user": "bob",\r
 244     "realm": "example.com"\r
 245 }\r
 246 ----\r
 247 Also, users may be granted roles based on their membership in certain groups.\r
 248 \r
 249 The Authentication Service allows white lists for users with specific roles. The white lists ensure that users are unconditionally accepted and authorized with specific roles. Users who must be unconditionally denied access can be placed in a black list.\r
 250 \r
 251 === Administering OpenDaylight Authentication Services\r
 252 \r
 253 ==== Actors in the System\r
 254 *OpenDaylight Controller administrator* +\r
 255 The OpenDaylight Controller administrator has the following responsibilities:\r
 256 \r
 257 * Author Authentication policies using the IdmLight Service API\r
 258 * Provides credentials, usernames and passwords to users who request them\r
 259 \r
 260 *OpenDaylight resource owners* +\r
 261 Resource owners authenticate (either by means of federation or directly providing their own credentials to the controller) to obtain an access token.  This access token can then be used to access resources on the controller.\r
 262 An OpenDaylight resource owner enjoys the following privileges:\r
 263 \r
 264 * Creates, refreshes, or deletes access tokens\r
 265 * Gets access tokens from the Secure Token Service\r
 266 * Passes secure tokens to resource users\r
 267 \r
 268 *OpenDaylight resource users* +\r
 269 Resource users do not need to authenticate: they can access resources if they are given an access tokens by the resource owner.  The default timeout for access tokens is 1 hour (This duration is configurable.).\r
 270 An OpenDaylight resource user does the following:\r
 271 \r
 272 *       Gets access tokens either from a resource owner or the controller administrator\r
 273 *       Uses tokens at access applications from the north-bound APIs\r
 274 \r
 275 ==== System Components\r
 276 IdmLight Identity manager:: Stores local user authentication and authorization data, provides an Admin REST API for CRUD operations.\r
 277 Pluggable authenticators:: Provides domain-specific authentication mechanisms\r
 278 Authenticator:: Authenticates users against and establishes claims\r
 279 Authentication Cache:: Caches all authentication states and tokens\r
 280 Authentication Filter:: Verifies tokens and extracts claims\r
 281 Authentication Manager:: Contains the session token and authentication claim store\r
 282 \r
 283 \r
 284 ===== IdmLight Identity manager\r
 285 The Light-weight Identity Manager (IdmLight) Stores local user authentication and authorization data, and roles and provides an Admin REST API for CRUD operations on the users/roles/domains database.\r
 286 The IdmLight REST API is by default accessed via the {controller baseURI:8181}/auth/v1/ API end point. \r
 287 Access to the API is restricted to authenticated clients only, or those possessing a token:\r
 288 \r
 289 Example: To retrieve the users list.\r
 290 \r
 291 [source,bash] \r
 292 ---- \r
 293 curl http://admin:admin@localhost:8181/auth/v1/users\r
 294 ----\r
 295 \r
 296 \r
 297 The following document contains a detailed list of supported CRUD operations allowed by the API:\r
 298 \r
 299  https://wiki.opendaylight.org/images/a/ad/AAA_Idmlight_REST_APIs.xlsx\r
 300 \r
 301 \r
 302 === OpenDaylight Authorization Service\r
 303 The authorization service currently included in OpenDaylight is of an experimental kind and only briefly documented here. \r
 304 Authorization follows successful authentication and is modeled on the Role Based Access Control (RBAC) approach for defining permissions and decide access levels to API resources on the controller.\r
 305 \r