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

   1 == Authentication Service\r
   2 Authentication uses the credentials presented by a user to identify the user.\r
   3 \r
   4 === Authenthentication data model\r
   5 A user requests authentication within a domain in which the user has defined roles.\r
   6 The user chooses either of the following ways to request authentication:\r
   7 \r
   8 * Provides credentials\r
   9 * 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
  10 \r
  11 ==== Terms and definitions in the model\r
  12 Token:: A claim of access to a group of resources on the controller\r
  13 Domain:: A group or isolation of resources, direct or indirect, physical, logical, or virtual, for the purpose of access control\r
  14 User:: A person who either owns and has, or has, access to a resource or group of resources on the controller\r
  15 Role:: Opaque representation of a set of permissions, which is merely a unique string as admin or guest\r
  16 Credential:: Proof of identity such as username and password, OTP, biometrics, or others\r
  17 Client:: A service or application that requires access to the controller\r
  18 \r
  19 ==== Authentication methods\r
  20 There are three ways a user may authenticate in OpenDaylight: +\r
  21 \r
  22 * Token-based Authentication\r
  23 ** 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
  24 ** 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
  25 * Basic Authentication\r
  26 :: For backward compatibility with the ODL Hydrogen release, the controller also supports the normal basic authentication with username/password.\r
  27 \r
  28 ===== Example with token authentication using curl (username/password = admin/admin, domain = sdn):\r
  29 \r
  30                 # Create a token\r
  31                 curl -ik -d 'grant_type=password&username=admin&password=admin&scope=sdn' http://localhost:8181/oauth2/token\r
  32 \r
  33                 # Use the token (e.g.,  ed3e5e05-b5e7-3865-9f63-eb8ed5c87fb9) obtained from above (default token validity is 1 hour):\r
  34                 curl -ik -H 'Authorization:Bearer ed3e5e05-b5e7-3865-9f63-eb8ed5c87fb9' http://localhost:8181/restconf/config/toaster:toaster\r
  35 \r
  36 Example with basic auth using curl: +\r
  37 \r
  38                 curl -ik -u 'admin:admin' http://localhost:8181/restconf/config/toaster:toaster\r
  39 \r
  40 === How the ODL Authentication Service works\r
  41 In direct authentication, a service relationship exists between the user and the ODL controller. The user and the controller establish trust that allows them to use, and validate credentials.\r
  42 The user establishes user identity through credentials.\r
  43 \r
  44 In direct authentication, a user request progresses through the following steps:\r
  45 \r
  46 . The user requests the controller administrator for a  user account.  \r
  47 \r
  48 :: 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 included with ODL out-of-the-box the username and password for which are admin/admin.  \r
  49 In addition to creating the user account, the controller administrator also assigns roles to that account on one or more domains.  By default, there are two user roles:  admin and user.  By default, there is only one domain: sdn.\r
  50 [start=2]\r
  51 . The user presents the credentials to the service within a domain in a request for a token.  \r
  52 . The request is then passed on to the controller token endpoint.\r
  53 . The controller token endpoint sends it to the credential authentication entity which returns a claim for the client. \r
  54 . The controller token entity transforms the claim (for user, domain, and roles) into a token which it then provides to the user.\r
  55 \r
  56 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.  An example of an external  IdP is Linux SSSD (System Security Services Daemon) or Openstack Keystone.\r
  57 \r
  58 The user is authenticated by the trusted IdP and a claim is returned to the ODL authentication services upon successful authentication.  The claim is mapped into ODL users or roles and transformed into a token that is passed onto the user. The request is passed on to the claim authentication broker that transforms it to a claim. The controller turns the claim into a token that is passed on to the user.\r
  59 \r
  60 In a federated authentication set-up, the Opendaylight controller extends SSSD claim support. SSSD also provides mapping capabilities. SSSD maps users in an external LDAP server to users defined on the Opendaylight controller.\r
  61 \r
  62 === Configuring Authentication service\r
  63 Changes to AAA configurations can be made from the following:\r
  64 \r
  65 * Webconsole\r
  66 * CLI (config command in the Karaf shell)\r
  67 * Editing the etc/org.opendaylight.aaa.*.cfg files directly\r
  68 \r
  69 Every Authentication Service karaf feature has its configuration file. \r
  70 \r
  71 NOTE: Configurations for AAA are all dynamic and require no restart.\r
  72 \r
  73 To configure features from the Web console: +\r
  74 \r
  75 . Install the Web console:\r
  76 ----\r
  77 feature:install webconsole\r
  78 ----\r
  79 [start=2]\r
  80 . On the console (http://localhost:8181/system/console) (default Karaf username/password:  karaf/karaf), go to *OSGi* > *Configuration* > *ODL AAA Authentication Configuration*.\r
  81 .. *Authorized Clients*:  List of software clients that are authorized to access ODL NB APIs.\r
  82 .. *Enable Authentication*:  Enable or disable authentication. (The default is enable.)\r
  83 \r
  84 ==== Configuring tokens\r
  85 . On the console, click *ODL AAA Token Configuration*.\r
  86 :: The fields you can configure are as follows:\r
  87 .. *Memory Configuration*: Configure the maximum number of tokens to be retained in memory.\r
  88 .. *Disk Configuration*: The maximum number of tokens to be retained on the disk.\r
  89 \r
  90 NOTE: When Memory is exhausted, tokens are moved to the disk.\r
  91 [start=3]\r
  92 .. *Token Expiration*: The number of seconds that a token remains live irrespective of use.\r
  93 .. *Unused Token Expiration*: The number of seconds that a token is live without being accessed. \r
  94 (The default period for both Expiration fields is 1 hour or 3600 seconds.)\r
  95 \r
  96 ==== Configuring AAA federation\r
  97 \r
  98 . On the console, click *ODL AAA Federation Configuration*.\r
  99 . Use the *Custom HTTP Headers* or *Custom HTTP Attributes* fields to specify the HTTP headers or attributes for federated authentication. Normally, such specification is not required.\r
 100 \r
 101 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
 102 \r
 103 === How federated authentication is set up\r
 104 Use the following steps to set up federated authentication: +\r
 105 \r
 106 . Set up an Apache front-end and Apache mods for the ODL controller.\r
 107 . Set up mapping rules (from LDAP users to ODL users).\r
 108 . Use the ClaimAuthFilter in federation to allow claim transformation.\r
 109 \r
 110 === Mapping users to roles and domains\r
 111 The ODL authentication service transforms assertions from an external federated IdP into Authentication Service data: +\r
 112 \r
 113 . The Apache web server which fronts ODL AAA sends data to SssdAuthFilter.\r
 114 . SssdAuthFilter constructs a JSON document from the data.\r
 115 . ODL Authentication Service uses a general purpose transformation mapper to transform the JSON document.\r
 116 \r
 117 ==== Operational model\r
 118 The mapping model works as follows: +\r
 119 \r
 120 . Assertions from an IdP are stored in an associative array.\r
 121 . A sequence of rules is applied, and the first rule which returns success is considered a match.\r
 122 . Upon success, an associative array of mapped values is returned.\r
 123 \r
 124 ** The mapped values are taken from the local variables set during the rule execution.\r
 125 ** The definition of the rules and mapped results are expressed in JSON notation.\r
 126 \r
 127 ==== Operational Model: Sample code\r
 128 ----\r
 129 mapped = null\r
 130 foreach rule in rules {\r
 131     result = null\r
 132     initialize rule.variables with pre-defined values\r
 133 \r
 134     foreach block in rule.statement_blocks {\r
 135         for statement in block.statements {\r
 136             if statement.verb is exit {\r
 137                 result = exit.status\r
 138                 break\r
 139             }\r
 140             elif statement.verb is continue {\r
 141                 break\r
 142             }\r
 143         }\r
 144         if result {\r
 145             break\r
 146         }\r
 147     if result == null {\r
 148         result = success\r
 149     }\r
 150 if result == success {\r
 151     mapped = rule.mapping(rule.variables)\r
 152 }\r
 153 return mapped\r
 154 ----\r
 155 \r
 156 ==== Mapping Users\r
 157 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
 158 An example of a mapping template and rule variables in JSON: +\r
 159 Template: +\r
 160 ----\r
 161 {\r
 162     "organization": "BigCorp.com",\r
 163     "user: "$subject",\r
 164     "roles": "$roles"\r
 165 }\r
 166 ----\r
 167 Local variables: +\r
 168 ----\r
 169 {\r
 170     "subject": "Sally",\r
 171     "roles": ["user", "admin"]\r
 172 }\r
 173 ----\r
 174 The final mapped result will be: +\r
 175 ----\r
 176 {\r
 177     "organization": "BigCorp.com",\r
 178     "user: "Sally",\r
 179     "roles": ["user", "admin"]\r
 180 }\r
 181 ----\r
 182 \r
 183 ==== Example: Splitting a fully qualified username into user and realm components\r
 184 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
 185 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
 186 \r
 187 The mapping in JSON: +\r
 188 ----\r
 189 {\r
 190     "user": "$username",\r
 191     "realm": "$domain"\r
 192 }\r
 193 ----\r
 194 The assertion in JSON: +\r
 195 ----\r
 196 {\r
 197     "Principal": "bob@example.com"\r
 198 }\r
 199 ----\r
 200 The rule applied: +\r
 201 ----\r
 202 [\r
 203     [\r
 204         ["in", "Principal", "assertion"],\r
 205         ["exit", "rule_fails", "if_not_success"],\r
 206         ["regexp", "$assertion[Principal]", (?P<username>\\w+)@(?P<domain>.+)"],\r
 207         ["set", "$username", "$regexp_map[username]"],\r
 208         ["set", "$domain", "$regexp_map[domain]"],\r
 209         ["exit, "rule_succeeds", "always"]\r
 210     ]\r
 211 ]\r
 212 ----\r
 213 The mapped result in JSON: +\r
 214 ----\r
 215 {\r
 216     "user": "bob",\r
 217     "realm": "example.com"\r
 218 }\r
 219 ----\r
 220 Also, users may be granted roles based on their membership in certain groups.\r
 221 \r
 222 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
 223 \r
 224 === Actors in ODL Authentication Service\r
 225 *ODL Controller administrator* +\r
 226 The ODL Controller administrator has the following responsibilities:\r
 227 \r
 228 * Authors Authentication policies using the REST API\r
 229 * Provides credentials, usernames and passwords to users who request them\r
 230 \r
 231 *ODL resource owners* +\r
 232 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
 233 An ODL resource owner enjoys the following privileges:\r
 234 \r
 235 * Creates, refreshes, or deletes access tokens\r
 236 * Gets access tokens from the Secure Token Service\r
 237 * Passes secure tokens to resource users\r
 238 \r
 239 *ODL resource users* +\r
 240 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
 241 An ODL resource user does the following:\r
 242 \r
 243 *       Gets access tokens either from a resource owner or the controller administrator\r
 244 *       Uses tokens at access applications from the north-bound APIs\r
 245 \r
 246 === Sub-components of ODL Authentication Service\r
 247 AuthX authoring service:: Provides AuthN and AuthZ Authoring service\r
 248 Light-weight Identity Manager (IdmLight):: Stores local user authentication and authorization data, and roles +\r
 249 Provides an Admin REST API for CRUD users/roles/domains\r
 250 Pluggable authenticators:: Provides domain-specific authentication mechanisms\r
 251 Authenticator:: Authenticates users against the authentication policy and establishes claims\r
 252 Authentication Cache:: Caches all authentication states and tokens\r
 253 Authentication Filter:: Verifies tokens and extracts claims\r
 254 Authentication Manager:: Contains the session token and authentication claim store\r
 255 \r
 256 ==== ODL Authorization Service\r
 257 In progress is the addition of an authorization feature to the authentication service. Authorization will follow successful authentication. Modelled on the Role Based Access Control (RBAC) approach for authentication, the Authorization service will assign roles that define permissions and decide access levels.\r
 258 Authorization will do the following:\r
 259 \r
 260 * Verify the operations the user or service is authorized to do\r
 261 * Enforce policies to grant or deny access to resources\r