-== AAA service
-
-Chapter on AAA service.
-
+== OpenDaylight Authentication Service Developers' Guide\r
+Authentication uses the credentials presented by a user to identify the user.\r
+\r
+=== Authenthentication data model\r
+A user requests authentication within a domain in which the user has defined roles.\r
+The user chooses either of the following ways to request authentication:\r
+\r
+* Provides credentials\r
+* 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
+\r
+==== Terms and definitions in the model\r
+Token:: A claim of access to a group of resources on the controller\r
+Domain:: A group or isolation of resources, direct or indirect, physical, logical, or virtual, for the purpose of access control\r
+User:: A person who either owns and has, or has, access to a resource or group of resources on the controller\r
+Role:: Opaque representation of a set of permissions, which is merely a unique string as admin or guest\r
+Credential:: Proof of identity such as username and password, OTP, biometrics, or others\r
+Client:: A service or application that requires access to the controller\r
+\r
+==== Authentication methods\r
+There are three ways a user may authenticate in OpenDaylight: +\r
+\r
+* Token-based Authentication\r
+** 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
+** 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
+* Basic Authentication\r
+:: For backward compatibility with the ODL Hydrogen release, the controller also supports the normal basic authentication with username/password.\r
+\r
+===== Example with token authentication using curl (username/password = admin/admin, domain = sdn):\r
+\r
+ # Create a token\r
+ curl -ik -d 'grant_type=password&username=admin&password=admin&scope=sdn' http://localhost:8181/oauth2/token\r
+\r
+ # Use the token (e.g., ed3e5e05-b5e7-3865-9f63-eb8ed5c87fb9) obtained from above (default token validity is 1 hour):\r
+ curl -ik -H 'Authorization:Bearer ed3e5e05-b5e7-3865-9f63-eb8ed5c87fb9' http://localhost:8181/restconf/config/toaster:toaster\r
+\r
+Example with basic auth using curl: +\r
+\r
+ curl -ik -u 'admin:admin' http://localhost:8181/restconf/config/toaster:toaster\r
+\r
+=== How the ODL Authentication Service works\r
+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
+The user establishes user identity through credentials.\r
+\r
+In direct authentication, a user request progresses through the following steps:\r
+\r
+. The user requests the controller administrator for a user account. \r
+\r
+:: 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
+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
+[start=2]\r
+. The user presents the credentials to the service within a domain in a request for a token. \r
+. The request is then passed on to the controller token endpoint.\r
+. The controller token endpoint sends it to the credential authentication entity which returns a claim for the client. \r
+. The controller token entity transforms the claim (for user, domain, and roles) into a token which it then provides to the user.\r
+\r
+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
+\r
+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
+\r
+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
+\r
+=== Configuring Authentication service\r
+Changes to AAA configurations can be made from the following:\r
+\r
+* Webconsole\r
+* CLI (config command in the Karaf shell)\r
+* Editing the etc/org.opendaylight.aaa.*.cfg files directly\r
+\r
+Every Authentication Service karaf feature has its configuration file. \r
+\r
+NOTE: Configurations for AAA are all dynamic and require no restart.\r
+\r
+To configure features from the Web console: +\r
+\r
+. Install the Web console:\r
+----\r
+feature:install webconsole\r
+----\r
+[start=2]\r
+. On the console (http://localhost:8181/system/console) (default Karaf username/password: karaf/karaf), go to *OSGi* > *Configuration* > *ODL AAA Authentication Configuration*.\r
+.. *Authorized Clients*: List of software clients that are authorized to access ODL NB APIs.\r
+.. *Enable Authentication*: Enable or disable authentication. (The default is enable.)\r
+\r
+==== Configuring tokens\r
+. On the console, click *ODL AAA Token Configuration*.\r
+:: The fields you can configure are as follows:\r
+.. *Memory Configuration*: Configure the maximum number of tokens to be retained in memory.\r
+.. *Disk Configuration*: The maximum number of tokens to be retained on the disk.\r
+\r
+NOTE: When Memory is exhausted, tokens are moved to the disk.\r
+[start=3]\r
+.. *Token Expiration*: The number of seconds that a token remains live irrespective of use.\r
+.. *Unused Token Expiration*: The number of seconds that a token is live without being accessed. \r
+(The default period for both Expiration fields is 1 hour or 3600 seconds.)\r
+\r
+==== Configuring AAA federation\r
+\r
+. On the console, click *ODL AAA Federation Configuration*.\r
+. 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
+\r
+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
+\r
+=== How federated authentication is set up\r
+Use the following steps to set up federated authentication: +\r
+\r
+. Set up an Apache front-end and Apache mods for the ODL controller.\r
+. Set up mapping rules (from LDAP users to ODL users).\r
+. Use the ClaimAuthFilter in federation to allow claim transformation.\r
+\r
+=== Mapping users to roles and domains\r
+The ODL authentication service transforms assertions from an external federated IdP into Authentication Service data: +\r
+\r
+. The Apache web server which fronts ODL AAA sends data to SssdAuthFilter.\r
+. SssdAuthFilter constructs a JSON document from the data.\r
+. ODL Authentication Service uses a general purpose transformation mapper to transform the JSON document.\r
+\r
+===== Operational model\r
+The mapping model works as follows: +\r
+\r
+. Assertions from an IdP are stored in an associative array.\r
+. A sequence of rules is applied, and the first rule which returns success is considered a match.\r
+. Upon success, an associative array of mapped values is returned.\r
+\r
+** The mapped values are taken from the local variables set during the rule execution.\r
+** The definition of the rules and mapped results are expressed in JSON notation.\r
+\r
+===== Operational Model: Sample code\r
+----\r
+mapped = null\r
+foreach rule in rules {\r
+ result = null\r
+ initialize rule.variables with pre-defined values\r
+\r
+ foreach block in rule.statement_blocks {\r
+ for statement in block.statements {\r
+ if statement.verb is exit {\r
+ result = exit.status\r
+ break\r
+ }\r
+ elif statement.verb is continue {\r
+ break\r
+ }\r
+ }\r
+ if result {\r
+ break\r
+ }\r
+ if result == null {\r
+ result = success\r
+ }\r
+if result == success {\r
+ mapped = rule.mapping(rule.variables)\r
+}\r
+return mapped\r
+----\r
+\r
+===== Mapping Users\r
+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
+An example of a mapping template and rule variables in JSON: +\r
+Template: +\r
+----\r
+{\r
+ "organization": "BigCorp.com",\r
+ "user: "$subject",\r
+ "roles": "$roles"\r
+}\r
+----\r
+Local variables: +\r
+----\r
+{\r
+ "subject": "Sally",\r
+ "roles": ["user", "admin"]\r
+}\r
+----\r
+The final mapped result will be: +\r
+----\r
+{\r
+ "organization": "BigCorp.com",\r
+ "user: "Sally",\r
+ "roles": ["user", "admin"]\r
+}\r
+----\r
+\r
+===== Example: Splitting a fully qualified username into user and realm components\r
+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
+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
+\r
+The mapping in JSON: +\r
+----\r
+{\r
+ "user": "$username",\r
+ "realm": "$domain"\r
+}\r
+----\r
+The assertion in JSON: +\r
+----\r
+{\r
+ "Principal": "bob@example.com"\r
+}\r
+----\r
+The rule applied: +\r
+----\r
+[\r
+ [\r
+ ["in", "Principal", "assertion"],\r
+ ["exit", "rule_fails", "if_not_success"],\r
+ ["regexp", "$assertion[Principal]", (?P<username>\\w+)@(?P<domain>.+)"],\r
+ ["set", "$username", "$regexp_map[username]"],\r
+ ["set", "$domain", "$regexp_map[domain]"],\r
+ ["exit, "rule_succeeds", "always"]\r
+ ]\r
+]\r
+----\r
+The mapped result in JSON: +\r
+----\r
+{\r
+ "user": "bob",\r
+ "realm": "example.com"\r
+}\r
+----\r
+Also, users may be granted roles based on their membership in certain groups.\r
+\r
+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
+\r
+=== Actors in ODL Authentication Service\r
+*ODL Controller administrator* +\r
+The ODL Controller administrator has the following responsibilities:\r
+\r
+* Authors Authentication policies using the REST API\r
+* Provides credentials, usernames and passwords to users who request them\r
+\r
+*ODL resource owners* +\r
+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
+An ODL resource owner enjoys the following privileges:\r
+\r
+* Creates, refreshes, or deletes access tokens\r
+* Gets access tokens from the Secure Token Service\r
+* Passes secure tokens to resource users\r
+\r
+*ODL resource users* +\r
+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
+An ODL resource user does the following:\r
+\r
+* Gets access tokens either from a resource owner or the controller administrator\r
+* Uses tokens at access applications from the north-bound APIs\r
+\r
+=== Sub-components of ODL Authentication Service\r
+AuthX authoring service:: Provides AuthN and AuthZ Authoring service\r
+Light-weight Identity Manager (IdmLight):: Stores local user authentication and authorization data, and roles +\r
+Provides an Admin REST API for CRUD users/roles/domains\r
+Pluggable authenticators:: Provides domain-specific authentication mechanisms\r
+Authenticator:: Authenticates users against the authentication policy and establishes claims\r
+Authentication Cache:: Caches all authentication states and tokens\r
+Authentication Filter:: Verifies tokens and extracts claims\r
+Authentication Manager:: Contains the session token and authentication claim store\r
+\r
+==== ODL Authorization Service\r
+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
+Authorization will do the following:\r
+\r
+* Verify the operations the user or service is authorized to do\r
+* Enforce policies to grant or deny access to resources\r
+\r
+\r
+\r
+\r
+\r
+\r
+\r
+\r
+\r
Code Review / docs.git / commitdiff