The Identity service generates tokens in exchange for authentication credentials. A token represents the authenticated identity of a user and, optionally, grants authorization on a specific project, domain, or the deployment system.
The body of an authentication request must include a payload that specifies the authentication methods, which are normally just password or token, the credentials, and, optionally, the authorization scope. You can scope a token to a project, domain, the deployment system, or the token can be unscoped. You cannot scope a token to multiple scope targets.
Tokens have IDs, which the Identity API returns in the X-Subject-Token response header.
In the case of multi-factor authentication (MFA) more than one authentication method needs to be supplied to authenticate. As of v3.12 a failure due to MFA rules only partially being met will result in an auth receipt ID being returned in the response header Openstack-Auth-Receipt, and a response body that details the receipt itself and the missing authentication methods. Supplying the auth receipt ID in the Openstack-Auth-Receipt header in a follow-up authentication request, with the missing authentication methods, will result in a valid token by reusing the successful methods from the first request. This allows MFA authentication to be a multi-step process.
After you obtain an authentication token, you can:
- Make REST API requests to other OpenStack services. You supply the ID of your authentication token in the
X-Auth-Tokenrequest header. - Validate your authentication token and list the domains, projects, roles, and endpoints that your token gives you access to.
- Use your token to request another token scoped for a different domain and project.
- Force the immediate revocation of a token.
- List revoked public key infrastructure (PKI) tokens.
In v3.7 of the Identity API service, two new configuration options were added: [resource] admin_project_name and [resource] admin_project_domain_name. The options represent the project that only the cloud administrator should be able to access. When an authentication request for a token scoped to the admin project is processed, it will have an additional field in the token {is_admin_project: True}. The additional field can be used when writing policy rules that evaluate access control to APIs.
Alternatively, in v3.10 the Identity API service introduced the concept of system role assignments and system-scoped tokens. APIs that affect the deployment system require system-scoped tokens.
The Identity API considers expired tokens as invalid, which is determined by the deployment's configuration.
These authentication errors can occur:
Authentication errors
| Response code | Description |
Bad Request (400) |
The Identity service failed to parse the request as expected. One of the following errors occurred:
|
Unauthorized (401) |
One of the following errors occurred:
|
Forbidden (403) |
The identity was successfully authenticated but it is not authorized to perform the requested action. |
Not Found (404) |
An operation failed because a referenced entity cannot be found by ID. For a POST request, the referenced entity might be specified in the request body rather than in the resource path. |
Conflict (409) |
A POST or PATCH operation failed. For example, a client tried to update a unique attribute for an entity, which conflicts with that of another entity in the same collection. Or, a client issued a create operation twice on a collection with a user-defined, unique attribute. For example, a client made a POST |
Authenticates an identity and generates a token. Uses the password authentication method. Authorization is unscoped.
The request body must include a payload that specifies the authentication method, which is password, and the user, by ID or name, and password credentials.
Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/auth_tokens
./samples/admin/auth-password-unscoped-request-with-domain.json
./samples/admin/auth-password-unscoped-response.json
Authenticates an identity and generates a token. Uses the password authentication method and scopes authorization to a project, domain, or the system.
The request body must include a payload that specifies the password authentication method which includes the credentials in addition to a project, domain, or system authorization scope.
Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/auth_tokens
./samples/auth/requests/system-password.json
./samples/auth/requests/domain-id-password.json
./samples/auth/requests/domain-name-password.json
./samples/auth/requests/project-id-password.json
./samples/auth/requests/project-name-password.json
./samples/auth/responses/system-scoped-password.json
./samples/auth/responses/domain-scoped-password.json
./samples/auth/responses/project-scoped-password.json
Authenticates an identity and generates a token. Uses the password authentication method with explicit unscoped authorization.
The request body must include a payload that specifies the password authentication method, the credentials, and the unscoped authorization scope.
Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/auth_tokens
./samples/admin/auth-password-explicit-unscoped-request.json
./samples/admin/auth-password-explicit-unscoped-response.json
Authenticates an identity and generates a token. Uses the token authentication method. Authorization is unscoped.
In the request body, provide the token ID.
Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/auth_tokens
./samples/admin/auth-token-unscoped-request.json
./samples/admin/auth-token-unscoped-response.json
Authenticates an identity and generates a token. Uses the token authentication method and scopes authorization to a project, domain, or the system.
The request body must include a payload that specifies the token authentication method which includes the token in addition to a project, domain, or system authorization scope.
Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/auth_tokens
./samples/auth/requests/system-token.json
./samples/auth/requests/domain-id-token.json
./samples/auth/requests/domain-name-token.json
./samples/auth/requests/project-id-token.json
./samples/auth/requests/project-name-token.json
./samples/auth/responses/system-scoped-token.json
./samples/auth/responses/domain-scoped-token.json
./samples/auth/responses/project-scoped-token.json
Authenticates an identity and generates a token. Uses the token authentication method with explicit unscoped authorization.
In the request body, provide the token ID and the unscoped authorization scope.
Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/auth_tokens
./samples/admin/auth-token-explicit-unscoped-request.json
./samples/admin/auth-token-unscoped-response.json
Authenticates an identity and generates a token. Uses the password authentication method, then the totp method, with an auth receipt in between.
This assumes that MFA has been enabled for the user, and a rule has been defined requiring authentication with both password and totp.
The first request body must at least include a payload that specifies one of password or totp authentication methods which includes the credentials in addition to an optional scope. If only one method is supplied then an auth receipt will be returned. Scope is not retained in the receipt and must be resupplied in subsequent requests.
While it is very possible to supply all the required auth methods at once, this example shows the multi-step process which is likely to be more common.
More than 2 factors can be used but the same process applies to those as well; either all auth methods are supplied at once, or in steps with one or more auth receipts in between.
Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/auth_tokens
./samples/auth/requests/project-id-password.json
Here we are expecting a 401 status, and a returned auth receipt.
./samples/auth/responses/auth-receipt-password.json
./samples/auth/requests/project-id-totp.json
./samples/auth/responses/project-scoped-password-totp.json
Validates and shows information for a token, including its expiration date and authorization scope.
Pass your own token in the X-Auth-Token request header.
Pass the token that you want to validate in the X-Subject-Token request header.
Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/auth_tokens
./samples/auth/responses/unscoped-password.json
./samples/auth/responses/system-scoped-password.json
./samples/auth/responses/domain-scoped-password.json
./samples/auth/responses/project-scoped-password.json
Validates a token.
This call is similar to GET /auth/tokens but no response body is provided even in the X-Subject-Token header.
The Identity API returns the same response as when the subject token was issued by POST /auth/tokens even if an error occurs because the token is not valid. An HTTP 204 response code indicates that the X-Subject-Token is valid.
Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/auth_tokens
Revokes a token.
This call is similar to the HEAD /auth/tokens call except that the X-Subject-Token token is immediately not valid, regardless of the expires_at attribute value. An additional X-Auth-Token is not required.
Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/auth_tokens
New in version 3.3
This call returns a service catalog for the X-Auth-Token provided in the request, even if the token does not contain a catalog itself (for example, if it was generated using ?nocatalog).
The structure of the catalog object is identical to that contained in a token.
Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/auth_catalog
./samples/admin/get-service-catalog-response.json
New in version 3.3
This call returns the list of projects that are available to be scoped to based on the X-Auth-Token provided in the request.
The structure of the response is exactly the same as listing projects for a user.
Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/auth_projects
./samples/admin/get-available-project-scopes-response.json
New in version 3.3
This call returns the list of domains that are available to be scoped to based on the X-Auth-Token provided in the request.
The structure is the same as listing domains.
Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/auth_domains
./samples/admin/get-available-domain-scopes-response.json
New in version 3.10
This call returns the list of systems that are available to be scoped to based on the X-Auth-Token provided in the request.
Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/auth_system
./samples/admin/get-available-system-scopes-response.json