--- /dev/null
+== Authentication Service\r
+Authentication uses the credentials presented by a user to identify the user.\r
+\r
+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 synchronised using out of band means. The AAA Token cache is however cluster-capable.\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 of resources, direct or indirect, physical, logical, or virtual, for the purpose of access control\r
+User:: A person who either owns 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
+Claim:: A data set of validated assertions regarding a user, e.g. the role, domain, name, etc.\r
+\r
+==== Authentication methods\r
+There are three ways a user may authenticate in OpenDaylight: +\r
+\r
+* Basic HTTP Authentication\r
+** Regular, non-token based, authentication with username/password.\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
+\r
+\r
+===== Example with token authentication using curl:\r
+\r
+(username/password = admin/admin, domain = sdn)\r
+\r
+[source,bash] \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
+\r
+===== Example with basic HTTP auth using curl: +\r
+\r
+[source,bash] \r
+---- \r
+curl -ik -u 'admin:admin' http://localhost:8181/restconf/config/toaster:toaster\r
+----\r
+\r
+=== How the OpenDaylight Authentication Service works\r
+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
+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 present in OpenDaylight out-of-the-box with the default username and password being admin/admin. \r
+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
++\r
+. The user presents credentials in a token request to the token service within a domain. \r
+. The request is then passed on to the controller token endpoint.\r
+. The controller token endpoint uses the credential authentication entity which returns a claim for the client. \r
+. The controller token entity transforms the claim (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.\r
+\r
+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
+\r
+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
+\r
+=== Configuring Authentication service\r
+Changes to AAA configurations can be made as follows:\r
+\r
+For Authentication functionality via one of:\r
+\r
+* Webconsole\r
+* CLI (config command in the Karaf shell)\r
+* Editing the etc/org.opendaylight.aaa.*.cfg files directly\r
+\r
+For Token Cache Store settings via one of:\r
+\r
+* Editing the 08-authn-config.xml configuration file in etc/opendaylight/karaf\r
+* Using Restconf\r
+\r
+NOTE: Configurations for AAA are all dynamic and require no restart.\r
+\r
+==== Configuring Authentication\r
+\r
+To configure features from the Web console: +\r
+\r
+. Install the Web console:\r
++\r
+----\r
+feature:install webconsole\r
+----\r
++\r
+. On the console (http://localhost:8181/system/console) (default Karaf username/password: karaf/karaf), go to *OSGi* > *Configuration* > *OpenDaylight AAA Authentication Configuration*.\r
+.. *Authorized Clients*: List of software clients that are authorized to access OpenDaylight northbound APIs.\r
+.. *Enable Authentication*: Enable or disable authentication. (The default is enable.)\r
+\r
+==== Configuring the token store\r
+. Open in a text editor etc/opendaylight/karaf/08-authn-config.xml\r
+:: The fields you can configure are as follows:\r
+.. *timeToLive*: Configure the maximum time, in milliseconds, that tokens are to be cached. Default is 360000.\r
+. Save the file.\r
+\r
+NOTE: When token's are expired, they are lazily removed from the cache.\r
+\r
+==== Configuring AAA federation\r
+\r
+. On the console, click *OpenDaylight 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, additional specification beyond the default is not \r
+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
+=== Configuring federated authentication\r
+Use the following steps to set up federated authentication: +\r
+\r
+. Set up an Apache front-end and Apache mods for the OpenDaylight controller.\r
+. Set up mapping rules (from LDAP users to OpenDaylight users).\r
+. Use the ClaimAuthFilter in federation to allow claim transformation.\r
+\r
+=== Mapping users to roles and domains\r
+The OpenDaylight authentication service transforms assertions from an external federated IdP into Authentication Service data: +\r
+\r
+. The Apache web server which fronts OpenDaylight AAA sends data to SssdAuthFilter.\r
+. SssdAuthFilter constructs a JSON document from the data.\r
+. OpenDaylight 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
+[source,java]\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
+[source,json]\r
+----\r
+{\r
+ "organization": "BigCorp.com",\r
+ "user: "$subject",\r
+ "roles": "$roles"\r
+}\r
+----\r
+Local variables: +\r
+[source,json]\r
+----\r
+{\r
+ "subject": "Sally",\r
+ "roles": ["user", "admin"]\r
+}\r
+----\r
+The final mapped result will be: +\r
+[source,json]\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
+[source,json]\r
+----\r
+{\r
+ "user": "$username",\r
+ "realm": "$domain"\r
+}\r
+----\r
+The assertion in JSON: +\r
+[source,json]\r
+----\r
+{\r
+ "Principal": "bob@example.com"\r
+}\r
+----\r
+The rule applied: +\r
+[source,json]\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
+[source,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
+== Administering OpenDaylight Authentication Services\r
+\r
+=== Actors in the System\r
+*OpenDaylight Controller administrator* +\r
+The OpenDaylight Controller administrator has the following responsibilities:\r
+\r
+* Author Authentication policies using the IdmLight Service API\r
+* Provides credentials, usernames and passwords to users who request them\r
+\r
+*OpenDaylight 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 OpenDaylight 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
+*OpenDaylight 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 OpenDaylight 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
+=== System Components\r
+IdmLight Identity manager:: Stores local user authentication and authorization data, provides an Admin REST API for CRUD operations.\r
+Pluggable authenticators:: Provides domain-specific authentication mechanisms\r
+Authenticator:: Authenticates users against 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
+\r
+==== IdmLight Identity manager\r
+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
+The IdmLight REST API is by default accessed via the {controller baseURI:8181}/auth/v1/ API end point. \r
+Access to the API is restricted to authenticated clients only, or those possessing a token:\r
+\r
+Example: To retrieve the users list.\r
+\r
+[source,bash] \r
+---- \r
+curl http://admin:admin@localhost:8181/auth/v1/users\r
+----\r
+\r
+\r
+The following document contains a detailed list of supported CRUD operations allowed by the API:\r
+\r
+ https://wiki.opendaylight.org/images/a/ad/AAA_Idmlight_REST_APIs.xlsx\r
+\r
+\r
+== OpenDaylight Authorization Service\r
+The authorization service currently included in OpenDaylight is of an experimental kind and only briefly documented here. \r
+Authorization follows successful authentication and is modelled on the Role Based Access Control (RBAC) approach for defining permissions and decide access levels to API resources on the controller.\r
+\r
Code Review / docs.git / commitdiff