OpenStack Identity API v3 (CURRENT)

2019年12月10日 阅读数:69
这篇文章主要向大家介绍OpenStack Identity API v3 (CURRENT),主要内容包括基础应用、实用技巧、原理机制等方面,希望对大家有所帮助。

Table Of Contents

Previous topic

Identity API v2.0 extensions (SUPPORTED)javascript

Next topic

Identity API v3 extensions (CURRENT)html

Other Versions

Project Source

This Page


 

 

The Identity service generates authentication tokens that permit access to the OpenStack services REST APIs. Clients obtain this token and the URL endpoints for other service APIs by supplying their valid credentials to the authentication service.java

Each time you make a REST API request to an OpenStack service, you supply your authentication token in the X-Auth-Token request header.python

Like most OpenStack projects, OpenStack Identity protects its APIs by defining policy rules based on a role-based access control (RBAC) approach.git

The Identity service configuration file sets the name and location of a JSON policy file that stores these rules.web

For information about Identity API protection, see Identity API protection with role-based access control (RBAC) in the OpenStack Cloud Administrator Guide.json

This page lists the Identity API operations in the following order:swift

 
 

Authentication and token management

In exchange for a set of authentication credentials, the Identity service generates tokens. A token represents the authenticated identity of a user and, optionally, grants authorization on a specific project or domain.api

The body of an authentication request must include a payload that specifies the authentication method, which is password or token, the credentials, and, optionally, the authorization scope. You can scope a token to a project or domain, or the token can be unscoped. You cannot scope a token to both a project and domain.app

Tokens have IDs, which the Identity API returns in the X-Subject-Token response header.

Also, validates an authentication token and lists the domains, projects, roles, and endpoints to which the token gives access. Forces the immediate revocation of a token.

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-Token request 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.

The Identity API treats expired tokens as no longer valid tokens. The deployment determines how long expired tokens are stored.

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:

  • A required attribute was missing.
  • An attribute that is not allowed was specified, such as an ID on a POST request in a basic CRUD operation.
  • An attribute of an unexpected data type was specified.
Unauthorized (401)

One of the following errors occurred:

  • Authentication was not performed.
  • The specified X-Auth-Token header is not valid.
  • The authentication credentials are not valid.
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 /users request two times for the unique, user-defined name attribute for a user entity.

POST
/v3/auth/tokens
Password authentication with unscoped authorization
 
 

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.

Normal response codes: 201 Error response codes: 413,415,405,404,403,401,400,503,409

Request

Name In Type Description
domain body object A domain object, containing:
name (Optional) body string The user name. Required if you do not specify the ID of the user. If you specify the user name, you must also specify the domain, by ID or name.
auth body object An auth object.
user body object A user object.
password body string The user password.
id (Optional) body string The ID of the user. Required if you do not specify the user name.
identity body object An identity object.
methods body array The authentication method. For password authentication, specify password.
nocatalog (Optional) query string (Since v3.1) The authentication response excludes the service catalog. By default, the response includes the service catalog.

Request Example

{
    "auth": {
        "identity": { "methods": [ "password" ], "password": { "user": { "name": "admin", "domain": { "id": "default" }, "password": "devstacker" } } } } } 

Response Parameters

Name In Type Description
X-Subject-Token header string The authentication token. An authentication response returns the token ID in this header rather than in the response body.
domain body object A domain object, containing:
methods body array The authentication method. For password authentication, specify password.
expires_at body string

The date and time when the token expires.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

A null value indicates that the token never expires.

token body object A token object.
extras body object A set of metadata key and value pairs, if any.
user body object A user object.
audit_ids body array A list of one or two audit IDs. An audit ID is a unique, randomly generated, URL-safe string that you can use to track a token. The first audit ID is the current audit ID for the token. The second audit ID is present for only re-scoped tokens and is the audit ID from the token before it was re-scoped. A re- scoped token is one that was exchanged for another token of the same or different scope. You can use these audit IDs to track the use of a token or chain of tokens across multiple requests and endpoints without exposing the token ID to non-privileged users.
issued_at body string

The date and time when the token was issued.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

id (Optional) body string The ID of the user. Required if you do not specify the user name.
name (Optional) body string The user name. Required if you do not specify the ID of the user. If you specify the user name, you must also specify the domain, by ID or name.
POST
/v3/auth/tokens
Password authentication with scoped authorization
 
 

Authenticates an identity and generates a token. Uses the password authentication method and scopes authorization to a project or domain.

The request body must include a payload that specifies the password authentication method, the credentials, and the project or domain authorization scope.

Normal response codes: 201 Error response codes: 413,415,405,404,403,401,400,503,409

Request

Name In Type Description
name (Optional) body string The user name. Required if you do not specify the ID of the user. If you specify the user name, you must also specify the domain, by ID or name.
auth body object An auth object.
user body object A user object.
scope (Optional) body string The authorization scope. (Since v3.4) Specify unscoped to make an explicit unscoped token request, which returns an unscoped response without any authorization. This request behaves the same as a token request with no scope where the user has no default project defined. If you do not make an explicit unscoped token request and your role has a default project, the response might return a project- scoped token. If a default project is not defined, a token is issued without an explicit scope of authorization, which is the same as asking for an explicit unscoped token.
password body string The user password.
id (Optional) body string The ID of the user. Required if you do not specify the user name.
identity body object An identity object.
methods body array The authentication method. For password authentication, specify password.
nocatalog (Optional) query string (Since v3.1) The authentication response excludes the service catalog. By default, the response includes the service catalog.

Request Example

{
    "auth": {
        "identity": { "methods": [ "password" ], "password": { "user": { "id": "ee4dfb6e5540447cb3741905149d9b6e", "password": "devstacker" } } }, "scope": { "project": { "id": "a6944d763bf64ee6a275f1263fae0352" } } } } 

Response Parameters

Name In Type Description
X-Subject-Token header string The authentication token. An authentication response returns the token ID in this header rather than in the response body.
domain body object A domain object, containing:
region_id body string (Since v3.2) The ID of the region that contains the service endpoint.
methods body array The authentication method. For password authentication, specify password.
roles body array A list of role objects, each containing:
url body string The endpoint URL.
region body string (Deprecated in v3.2) The geographic location of the service endpoint.
token body object A token object.
expires_at body string

The date and time when the token expires.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

A null value indicates that the token never expires.

project body object A project object, containing:
issued_at body string

The date and time when the token was issued.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

catalog body array A catalog object.
extras body object A set of metadata key and value pairs, if any.
user body object A user object.
audit_ids body array A list of one or two audit IDs. An audit ID is a unique, randomly generated, URL-safe string that you can use to track a token. The first audit ID is the current audit ID for the token. The second audit ID is present for only re-scoped tokens and is the audit ID from the token before it was re-scoped. A re- scoped token is one that was exchanged for another token of the same or different scope. You can use these audit IDs to track the use of a token or chain of tokens across multiple requests and endpoints without exposing the token ID to non-privileged users.
interface body string The interface type, which describes the visibility of the endpoint. Value is: - public. Visible by end users on a publicly available network interface. - internal. Visible by end users on an unmetered internal network interface. - admin. Visible by administrative users on a secure network interface.
endpoints body array An endpoints object.
type body string The endpoint type.
id (Optional) body string The ID of the user. Required if you do not specify the user name.
name (Optional) body string The user name. Required if you do not specify the ID of the user. If you specify the user name, you must also specify the domain, by ID or name.
POST
/v3/auth/tokens
Password authentication with explicit unscoped authorization
 
 

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.

Normal response codes: 201 Error response codes: 413,415,405,404,403,401,400,503,409

Request

Name In Type Description
name (Optional) body string The user name. Required if you do not specify the ID of the user. If you specify the user name, you must also specify the domain, by ID or name.
auth body object An auth object.
user body object A user object.
scope (Optional) body string The authorization scope. (Since v3.4) Specify unscoped to make an explicit unscoped token request, which returns an unscoped response without any authorization. This request behaves the same as a token request with no scope where the user has no default project defined. If you do not make an explicit unscoped token request and your role has a default project, the response might return a project- scoped token. If a default project is not defined, a token is issued without an explicit scope of authorization, which is the same as asking for an explicit unscoped token.
password body string The user password.
id (Optional) body string The ID of the user. Required if you do not specify the user name.
identity body object An identity object.
methods body array The authentication method. For password authentication, specify password.
nocatalog (Optional) query string (Since v3.1) The authentication response excludes the service catalog. By default, the response includes the service catalog.

Request Example

{
    "auth": {
        "identity": { "methods": [ "password" ], "password": { "user": { "id": "ee4dfb6e5540447cb3741905149d9b6e", "password": "devstacker" } } }, "scope": "unscoped" } } 

Response Parameters

Name In Type Description
X-Subject-Token header string The authentication token. An authentication response returns the token ID in this header rather than in the response body.
domain body object A domain object, containing:
methods body array The authentication method. For password authentication, specify password.
roles body array A list of role objects, each containing:
expires_at body string

The date and time when the token expires.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

A null value indicates that the token never expires.

token body object A token object.
extras body object A set of metadata key and value pairs, if any.
user body object A user object.
audit_ids body array A list of one or two audit IDs. An audit ID is a unique, randomly generated, URL-safe string that you can use to track a token. The first audit ID is the current audit ID for the token. The second audit ID is present for only re-scoped tokens and is the audit ID from the token before it was re-scoped. A re- scoped token is one that was exchanged for another token of the same or different scope. You can use these audit IDs to track the use of a token or chain of tokens across multiple requests and endpoints without exposing the token ID to non-privileged users.
issued_at body string

The date and time when the token was issued.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

id (Optional) body string The ID of the user. Required if you do not specify the user name.
name (Optional) body string The user name. Required if you do not specify the ID of the user. If you specify the user name, you must also specify the domain, by ID or name.
POST
/v3/auth/tokens
Token authentication with unscoped authorization
 
 

Authenticates an identity and generates a token. Uses the token authentication method. Authorization is unscoped.

In the request body, provide the token ID.

Normal response codes: 201 Error response codes: 413,415,405,404,403,401,400,503,409

Request

Name In Type Description
identity body object An identity object.
token body object A token object.
id (Optional) body string The ID of the user. Required if you do not specify the user name.
auth body object An auth object.
methods body array The authentication method. For password authentication, specify password.
nocatalog (Optional) query string (Since v3.1) The authentication response excludes the service catalog. By default, the response includes the service catalog.

Request Example

{
    "auth": {
        "identity": { "methods": [ "token" ], "token": { "id": "'$OS_TOKEN'" } } } } 

Response Parameters

Name In Type Description
X-Subject-Token header string The authentication token. An authentication response returns the token ID in this header rather than in the response body.
X-Auth-Token header string A valid authentication token for an administrative user.
POST
/v3/auth/tokens
Token authentication with scoped authorization
 
 

Authenticates an identity and generates a token. Uses the token authentication method and scopes authorization to a project or domain.

In the request body, provide the token ID and the project or domain authorization scope.

Normal response codes: 201 Error response codes: 413,415,405,404,403,401,400,503,409

Request

Name In Type Description
methods body array The authentication method. For password authentication, specify password.
auth body object An auth object.
token body object A token object.
audit_ids body array A list of one or two audit IDs. An audit ID is a unique, randomly generated, URL-safe string that you can use to track a token. The first audit ID is the current audit ID for the token. The second audit ID is present for only re-scoped tokens and is the audit ID from the token before it was re-scoped. A re- scoped token is one that was exchanged for another token of the same or different scope. You can use these audit IDs to track the use of a token or chain of tokens across multiple requests and endpoints without exposing the token ID to non-privileged users.
scope (Optional) body string The authorization scope. (Since v3.4) Specify unscoped to make an explicit unscoped token request, which returns an unscoped response without any authorization. This request behaves the same as a token request with no scope where the user has no default project defined. If you do not make an explicit unscoped token request and your role has a default project, the response might return a project- scoped token. If a default project is not defined, a token is issued without an explicit scope of authorization, which is the same as asking for an explicit unscoped token.
id (Optional) body string The ID of the user. Required if you do not specify the user name.
identity body object An identity object.
nocatalog (Optional) query string (Since v3.1) The authentication response excludes the service catalog. By default, the response includes the service catalog.

Request Example

{
    "auth": {
        "identity": { "methods": [ "token" ], "token": { "id": "'$OS_TOKEN'" } }, "scope": { "project": { "id": "5b50efd009b540559104ee3c03bbb2b7" } } } } 

Response Parameters

Name In Type Description
X-Subject-Token header string The authentication token. An authentication response returns the token ID in this header rather than in the response body.
X-Auth-Token header string A valid authentication token for an administrative user.
GET
/v3/auth/tokens
Validate and show information for token
 
 

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.

Normal response codes: 200 Error response codes: 413,405,404,403,401,400,503

Request

Name In Type Description
X-Auth-Token header string A valid authentication token for an administrative user.
X-Subject-Token header string The authentication token. An authentication response returns the token ID in this header rather than in the response body.

Response Parameters

Name In Type Description
X-Subject-Token header string The authentication token. An authentication response returns the token ID in this header rather than in the response body.
X-Auth-Token header string A valid authentication token for an administrative user.
domain body object A domain object, containing:
methods body array The authentication method. For password authentication, specify password.
links body object The links for the credential resource.
user body object A user object.
token body object A token object.
expires_at body string

The date and time when the token expires.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

A null value indicates that the token never expires.

project body object A project object, containing:
catalog body array A catalog object.
extras body object A set of metadata key and value pairs, if any.
roles body array A list of role objects, each containing:
audit_ids body array A list of one or two audit IDs. An audit ID is a unique, randomly generated, URL-safe string that you can use to track a token. The first audit ID is the current audit ID for the token. The second audit ID is present for only re-scoped tokens and is the audit ID from the token before it was re-scoped. A re- scoped token is one that was exchanged for another token of the same or different scope. You can use these audit IDs to track the use of a token or chain of tokens across multiple requests and endpoints without exposing the token ID to non-privileged users.
issued_at body string

The date and time when the token was issued.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

id (Optional) body string The ID of the user. Required if you do not specify the user name.
name (Optional) body string The user name. Required if you do not specify the ID of the user. If you specify the user name, you must also specify the domain, by ID or name.

Response Example

{
    "token": {
        "methods": [ "token" ], "expires_at": "2015-11-05T22:00:11.000000Z", "extras": {}, "user": { "domain": { "id": "default", "name": "Default" }, "id": "10a2e6e717a245d9acad3e5f97aeca3d", "name": "admin" }, "audit_ids": [ "mAjXQhiYRyKwkB4qygdLVg" ], "issued_at": "2015-11-05T21:00:33.819948Z" } } 
HEAD
/v3/auth/tokens
Check token
 
 

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.

Normal response codes: 200 Error response codes: 413,405,404,403,401,400,503

Request

Name In Type Description
X-Auth-Token header string A valid authentication token for an administrative user.
X-Subject-Token header string The authentication token. An authentication response returns the token ID in this header rather than in the response body.
DELETE
/v3/auth/tokens
Revoke token
 
 

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.

Normal response codes: 204 Error response codes: 413,415,405,404,403,401,400,503,409

Request

Name In Type Description
X-Auth-Token header string A valid authentication token for an administrative user.
X-Subject-Token header string The authentication token. An authentication response returns the token ID in this header rather than in the response body.

Credentials

In exchange for a set of authentication credentials that the user submits, the Identity service generates and returns a token. A token represents the authenticated identity of a user and, optionally, grants authorization on a specific project or domain.

You can list all credentials, and create, show details for, update, and delete a credential.

POST
/v3/credentials
Create credential
 
 

Creates a credential.

The following example shows how to create an EC2-style credential. The credential blob is a string that contains a JSON-serialized dictionary with the access and secret keys. This format is required when you specify the ec2 type. To specify other credentials, such as access_key, change the type and contents of the data blob.

Normal response codes: 201 Error response codes: 413,415,405,404,403,401,400,503,409

Request

Name In Type Description
credential body object A credential object.
project_id path string The project ID.
type body string The endpoint type.
blob body string The credential itself, as a serialized blob.
user_id path string The user ID.

Request Example

{
    "credential": {
        "blob": "{\"access\":\"181920\",\"secret\":\"secretKey\"}", "project_id": "731fc6f265cd486d900f16e84c5cb594", "type": "ec2", "user_id": "bb5476fd12884539b41d5a88f838d773" } } 

Response Parameters

Name In Type Description
credential body object A credential object.
user_id path string The user ID.
links body object The links for the credential resource.
blob body string The credential itself, as a serialized blob.
project_id path string The project ID.
type body string The endpoint type.
id (Optional) body string The ID of the user. Required if you do not specify the user name.
GET
/v3/credentials
List credentials
 
 

Lists all credentials.

Optionally, you can include the user_id query parameter in the URI to filter the response by a user.

Normal response codes: 200 Error response codes: 413,405,404,403,401,400,503

Request

Name In Type Description
user_id path string The user ID.

Response Parameters

Name In Type Description
user_id path string The user ID.
links body object The links for the credential resource.
blob body string The credential itself, as a serialized blob.
credentials body array A credentials object.
project_id path string The project ID.
type body string The endpoint type.
id (Optional) body string The ID of the user. Required if you do not specify the user name.

Response Example

{
    "credentials": [
        {
            "user_id": "bb5476fd12884539b41d5a88f838d773", "links": { "self": "http://example.com/identity/v3/credentials/207e9b76935efc03804d3dd6ab52d22e9b22a0711e4ada4ff8b76165a07311d7" }, "blob": "{\"access\": \"a42a27755ce6442596b049bd7dd8a563\", \"secret\": \"71faf1d40bb24c82b479b1c6fbbd9f0c\", \"trust_id\": null}", "project_id": "6e01855f345f4c59812999b5e459137d", "type": "ec2", "id": "207e9b76935efc03804d3dd6ab52d22e9b22a0711e4ada4ff8b76165a07311d7" }, { "user_id": "6f556708d04b4ea6bc72d7df2296b71a", "links": { "self": "http://example.com/identity/v3/credentials/2441494e52ab6d594a34d74586075cb299489bdd1e9389e3ab06467a4f460609" }, "blob": "{\"access\": \"7da79ff0aa364e1396f067e352b9b79a\", \"secret\": \"7a18d68ba8834b799d396f3ff6f1e98c\", \"trust_id\": null}", "project_id": "1a1d14690f3c4ec5bf5f321c5fde3c16", "type": "ec2", "id": "2441494e52ab6d594a34d74586075cb299489bdd1e9389e3ab06467a4f460609" }, { "user_id": "c14107e65d5c4a7f8894fc4b3fc209ff", "links": { "self": "http://example.com/identity/v3/credentials/3397b204b5f04c495bcdc8f34c8a39996f280f9172658241873e15f070ec79d7" }, "blob": "{\"access\": \"db9c58a558534a10a070110de4f9f20c\", \"secret\": \"973e790b88db447ba6f93bca02bc745b\", \"trust_id\": null}", "project_id": "7396e43183db40dcbf40dd727637b548", "type": "ec2", "id": "3397b204b5f04c495bcdc8f34c8a39996f280f9172658241873e15f070ec79d7" }, { "user_id": "915cc5f8cca6466aba6c6be06cbabfdf", "links": { "self": "http://example.com/identity/v3/credentials/352d5dd7a4aa19c4f2f23ee288bf65dc23a0bc293f40ffd2128ffe6a8cf3e871" }, "blob": "{\"access\": \"817c6c3487a440c1a0b1d3f92b30ca37\", \"secret\": \"47d681117d1c46e69a0c9ec811dae2e9\", \"trust_id\": null}", "project_id": "2bf9767f9db949ee8364262a28a23062", "type": "ec2", "id": "352d5dd7a4aa19c4f2f23ee288bf65dc23a0bc293f40ffd2128ffe6a8cf3e871" }, { "user_id": "bb5476fd12884539b41d5a88f838d773", "links": { "self": "http://example.com/identity/v3/credentials/3d3367228f9c7665266604462ec60029bcd83ad89614021a80b2eb879c572510" }, "blob": "{\"access\":\"181920\",\"secret\":\"secretKey\"}", "project_id": "731fc6f265cd486d900f16e84c5cb594", "type": "ec2", "id": "3d3367228f9c7665266604462ec60029bcd83ad89614021a80b2eb879c572510" }, { "user_id": "bb5476fd12884539b41d5a88f838d773", "links": { "self": "http://example.com/identity/v3/credentials/6b7d803fc03b85866904b6b79e0a8fa1f4013b584163b4477eed96717eb402c0" }, "blob": "{\"access\": \"f2ba45670b504a518b46e920d760fde2\", \"secret\": \"bf7fff2b3a844730b2db793411756e55\", \"trust_id\": null}", "project_id": "731fc6f265cd486d900f16e84c5cb594", "type": "ec2", "id": "6b7d803fc03b85866904b6b79e0a8fa1f4013b584163b4477eed96717eb402c0" }, { "user_id": "2b657f6742ac416697e6821b3b2ee785", "links": { "self": "http://example.com/identity/v3/credentials/7d391b869631e5c4836708ea3bb3e0a5cbe0481201b5f0ddd5685ad3b3faa564" }, "blob": "{\"access\": \"a1525da4e7c0438ebf3058372d637b59\", \"secret\": \"c9165d2542b141e8b2a1ff61a5f5487c\", \"trust_id\": null}", "project_id": "2bf9767f9db949ee8364262a28a23062", "type": "ec2", "id": "7d391b869631e5c4836708ea3bb3e0a5cbe0481201b5f0ddd5685ad3b3faa564" }, { "user_id": "bb5476fd12884539b41d5a88f838d773", "links": { "self": "http://example.com/identity/v3/credentials/7ef4faa904ae7b8b4ddc7bad15b05ee359dad7d7a9b82861d4ad92fdbbb2eb4e" }, "blob": "{\"access\": \"7d7559359b57419eb5f5f5dcd65ab57d\", \"secret\": \"570652bcf8c2483c86eb29e9734eed3c\", \"trust_id\": null}", "project_id": "731fc6f265cd486d900f16e84c5cb594", "type": "ec2", "id": "7ef4faa904ae7b8b4ddc7bad15b05ee359dad7d7a9b82861d4ad92fdbbb2eb4e" }, { "user_id": "aedb193e9bb8400485f8d8426f7a031f", "links": { "self": "http://example.com/identity/v3/credentials/9c1c428d8e0e8338a5e16489ecfff9962f2b00f984ce4c7e9015e4003f478df8" }, "blob": "{\"access\": \"b3a6e5f4427c47e9b202264d91a19e49\", \"secret\": \"d9eb470f503f4b46932de38db7a79402\", \"trust_id\": null}", "project_id": "a2672ecf9dd34c6980448b25a47e0947", "type": "ec2", "id": "9c1c428d8e0e8338a5e16489ecfff9962f2b00f984ce4c7e9015e4003f478df8" }, { "user_id": "c14107e65d5c4a7f8894fc4b3fc209ff", "links": { "self": "http://example.com/identity/v3/credentials/e2c35ac2becb0fca3c3c2f035692a4f46a9cbf3b6e86c8a47f5aafe837d78a05" }, "blob": "{\"access\": \"1ed843b1bd4a409f9562400085adbaa4\", \"secret\": \"236ab24db1f04ec995fcf618ed4fc0f5\", \"trust_id\": null}", "project_id": "6e01855f345f4c59812999b5e459137d", "type": "ec2", "id": "e2c35ac2becb0fca3c3c2f035692a4f46a9cbf3b6e86c8a47f5aafe837d78a05" } ], "links": { "self": "http://example.com/identity/v3/credentials", "previous": null, "next": null } } 
GET
/v3/credentials/ {credential_id}
Show credential details
 
 

Shows details for a credential.

Normal response codes: 200 Error response codes: 413,405,404,403,401,400,503

Request

Name In Type Description
credential_id path string The UUID for the credential.

Response Parameters

Name In Type Description
credential body object A credential object.
user_id path string The user ID.
links body object The links for the credential resource.
blob body string The credential itself, as a serialized blob.
project_id path string The project ID.
type body string The endpoint type.
id (Optional) body string The ID of the user. Required if you do not specify the user name.

Response Example

{
    "credential": {
        "user_id": "bb5476fd12884539b41d5a88f838d773", "links": { "self": "http://example.com/identity/v3/credentials/207e9b76935efc03804d3dd6ab52d22e9b22a0711e4ada4ff8b76165a07311d7" }, "blob": "{\"access\": \"a42a27755ce6442596b049bd7dd8a563\", \"secret\": \"71faf1d40bb24c82b479b1c6fbbd9f0c\", \"trust_id\": null}", "project_id": "6e01855f345f4c59812999b5e459137d", "type": "ec2", "id": "207e9b76935efc03804d3dd6ab52d22e9b22a0711e4ada4ff8b76165a07311d7" } } 
PATCH
/v3/credentials/ {credential_id}
Update credential
 
 

Updates a credential.

Normal response codes: 200 Error response codes: 413,415,405,404,403,401,400,503,409

Request

Name In Type Description
credential body object A credential object.
project_id path string The project ID.
type body string The endpoint type.
blob body string The credential itself, as a serialized blob.
user_id path string The user ID.
credential_id path string The UUID for the credential.

Request Example

{
    "credential": {
        "blob": "{\"access\":\"181920\",\"secrete\":\"secretKey\"}", "project_id": "731fc6f265cd486d900f16e84c5cb594", "type": "ec2", "user_id": "bb5476fd12884539b41d5a88f838d773" } } 

Response Parameters

Name In Type Description
credential body object A credential object.
user_id path string The user ID.
links body object The links for the credential resource.
blob body string The credential itself, as a serialized blob.
project_id path string The project ID.
type body string The endpoint type.
id (Optional) body string The ID of the user. Required if you do not specify the user name.

Response Example

{
    "credential": {
        "user_id": "bb5476fd12884539b41d5a88f838d773", "links": { "self": "http://example.com/identity/v3/credentials/207e9b76935efc03804d3dd6ab52d22e9b22a0711e4ada4ff8b76165a07311d7" }, "blob": "{\"access\":\"181920\",\"secrete\":\"secretKey\"}", "project_id": "731fc6f265cd486d900f16e84c5cb594", "type": "ec2", "id": "207e9b76935efc03804d3dd6ab52d22e9b22a0711e4ada4ff8b76165a07311d7" } } 
DELETE
/v3/credentials/ {credential_id}
Delete credential
 
 

Deletes a credential.

Normal response codes: 204 Error response codes: 413,415,405,404,403,401,400,503,409

Request

Name In Type Description
credential_id path string The UUID for the credential.

Domains

A domain is a collection of users, groups, and projects. Each group and project is owned by exactly one domain.

Each domain defines a namespace where certain API-visible name attributes exist, which affects whether those names must be globally unique or unique within that domain. In the Identity API, the uniqueness of these attributes is as follows:

  • Domain name. Globally unique across all domains.
  • Role name. Globally unique across all domains.
  • User name. Unique within the owning domain.
  • Project name. Unique within the owning domain.
  • Group name. Unique within the owning domain.
GET
/v3/domains
List domains
 
 

Lists all domains.

Normal response codes: 200 Error response codes: 413,405,404,403,401,400,503

Request

Name In Type Description
name (Optional) query string Filters the response by a domain name.
enabled (Optional) query string If set to true, then only domains that are enabled will be returned, if set to false only that are disabled will be returned. Any value other than 0, including no value, will be interpreted as true.

Response Parameters

Name In Type Description
domains body array A list of domain objects, each containing:
description body string The description of the domain.
enabled body string If set to true, domain is enabled. If set to false, domain is disabled.
id body string The ID of the domain.
links body object The links to the domain resource.
name body string The name of the domain.

Response Example

{
    "domains": [
        {
            "description": "Used for swift functional testing", "enabled": true, "id": "5a75994a383c449184053ff7270c4e91", "links": { "self": "http://example.com/identity/v3/domains/5a75994a383c449184053ff7270c4e91" }, "name": "swift_test" }, { "description": "Owns users and tenants (i.e. projects) available on Identity API v2.", "enabled": true, "id": "default", "links": { "self": "http://example.com/identity/v3/domains/default" }, "name": "Default" } ], "links": { "next": null, "previous": null, "self": "http://example.com/identity/v3/domains" } } 
POST
/v3/domains
Create domain
 
 

Creates a domain.

Normal response codes: 201 Error response codes: 413,415,405,404,403,401,400,503,409

Request

Name In Type Description
domain body object A domain object, containing:
enabled (Optional) body string

If set to true, domain is created enabled. If set to false, domain is created disabled. The default is true.

Users can only authorize against an enabled domain (and any of its projects). In addition, users can only authenticate if the domain that owns them is also enabled. Disabling a domain prevents both of these things.

description (Optional) body string The description of the domain.
name body string The name of the domain.

Request Example

{
    "domain": {
        "description": "Domain description", "enabled": true, "name": "myDomain" } } 

Response Parameters

Name In Type Description
domain body object A domain object, containing:
description body string The description of the domain.
enabled body string If set to true, domain is enabled. If set to false, domain is disabled.
id body string The ID of the domain.
links body object The links to the domain resource.
name body string The name of the domain.
GET
/v3/domains/ {domain_id}
Show domain details
 
 

Shows details for a domain.

Normal response codes: 200 Error response codes: 413,405,404,403,401,400,503

Request

Name In Type Description
domain_id path string The domain ID.

Response Parameters

Name In Type Description
domain body object A domain object, containing:
description body string The description of the domain.
enabled body string If set to true, domain is enabled. If set to false, domain is disabled.
id body string The ID of the domain.
links body object The links to the domain resource.
name body string The name of the domain.

Response Example

{
    "domain": {
        "description": "Owns users and tenants (i.e. projects) available on Identity API v2.", "enabled": true, "id": "default", "links": { "self": "http://example.com/identity/v3/domains/default" }, "name": "Default" } } 
PATCH
/v3/domains/ {domain_id}
Update domain
 
 

Updates a domain.

Normal response codes: 200 Error response codes: 413,415,405,404,403,401,400,503,409

Request

Name In Type Description
domain_id path string The domain ID.
domain body object A domain object, containing:
enabled (Optional) body string

If set to true, domain is enabled. If set to false, domain is disabled. The default is true.

Users can only authorize against an enabled domain (and any of its projects). In addition, users can only authenticate if the domain that owns them is also enabled. Disabling a domain prevents both of these things. When you disable a domain, all tokens that are authorized for that domain become no longer valid. If you reenable the domain, these tokens are not re-enabled.

description (Optional) body string The new description of the domain.
name (Optional) body string The new name of the domain.

Request Example

{
    "domain": {
        "description": "Owns users and projects on Identity API v2." } } 

Response Parameters

Name In Type Description
domain body object A domain object, containing:
description body string The description of the domain.
enabled body string If set to true, domain is enabled. If set to false, domain is disabled.
id body string The ID of the domain.
links body object The links to the domain resource.
name body string The name of the domain.

Response Example

{
    "domain": {
        "links": { "self": "http://example.com/identity/v3/domains/default" }, "enabled": true, "description": "Owns users and projects on Identity API v2.", "name": "Default", "id": "default" } } 
DELETE
/v3/domains/ {domain_id}
Delete domain
 
 

Deletes a domain.

To minimize the risk of accidentally deleting a domain, you must first disable the domain by using the update domain method.

When you delete a domain, this call also deletes all entities owned by it, such as users, groups, and projects, and any credentials and granted roles that relate to those entities.

If you try to delete an enabled domain, this call returns the Forbidden (403) response code.

Normal response codes: 204 Error response codes: 413,415,405,404,403,401,400,503,409

Request

Name In Type Description
domain_id path string The domain ID.

Domain configuration

You can manage domain-specific configuration options.

Domain-specific configuration options are structured within their group objects. The API supports only the identity and ldap groups. These groups override the default configuration settings for the storage of users and groups by the Identity server.

You can create, update, and delete domain-specific configuration options by using the HTTP PUT , PATCH , and DELETE methods. When updating, it is only necessary to include those options that are being updated.

To create an option, use the PUT method. The Identity API does not return options that are considered sensitive, although you can create and update these options. The only option currently considered sensitive is the password option within the ldap group.

The API enables you to include sensitive options as part of non- sensitive options. For example, you can include the password as part of the url option.

If you try to create or update configuration options for groups other than the identity or ldap groups, the Forbidden (403) response code is returned.

For information about how to integrate the Identity service with LDAP, see Integrate Identity with LDAP.

GET
/v3/domains/ {domain_id}/config/{group}/{option}
Show domain group option configuration
 
 

Shows details for a domain group option configuration.

The API supports only the identity and ldap groups. For the ldap group, a valid value is url or user_tree_dn. For the identity group, a valid value is driver.

Normal response codes: 200 Error response codes:413,405,404,403,401,400,503,

Request

Name In Type Description
domain_id path string Filters the response by a domain ID.
group body object A group object, containing:
option path string The option name. For the ldap group, a valid value is url or user_tree_dn. For the identity group, a valid value is driver.

Response Parameters

Name In Type Description
url body string The endpoint URL.
driver body string The Identity back-end driver.
ldap body object An ldap object. Required to set the LDAP group configuration options.
config body object A config object.
user_tree_dn body string The base distinguished name (DN) of LDAP, from where all users can be reached. For example, ou=Users,dc=root,dc=org.
identity body object An identity object.

Response Example

{
    "url": "http://myldap/root"
}
PATCH
/v3/domains/ {domain_id}/config/{group}/{option}
Update domain group option configuration
 
 

Updates a domain group option configuration.

The API supports only the identity and ldap groups. For the ldap group, a valid value is url or user_tree_dn. For the identity group, a valid value is driver.

Normal response codes: 200 Error response codes:413,415,405,404,403,401,400,503,409,

Request

Name In Type Description
url body string The endpoint URL.
driver body string The Identity back-end driver.
ldap body object An ldap object. Required to set the LDAP group configuration options.
config body object A config object.
user_tree_dn body string The base distinguished name (DN) of LDAP, from where all users can be reached. For example, ou=Users,dc=root,dc=org.
identity body object An identity object.
domain_id path string Filters the response by a domain ID.
group body object A group object, containing:
option path string The option name. For the ldap group, a valid value is url or user_tree_dn. For the identity group, a valid value is driver.

Request Example

{
    "url": "http://myldap/my_other_root"
}

Response Parameters

Name In Type Description
url body string The endpoint URL.
driver body string The Identity back-end driver.
ldap body object An ldap object. Required to set the LDAP group configuration options.
config body object A config object.
user_tree_dn body string The base distinguished name (DN) of LDAP, from where all users can be reached. For example, ou=Users,dc=root,dc=org.
identity body object An identity object.

Response Example

{
    "config": {
        "identity": { "driver": "keystone.identity.backends.ldap.Identity" }, "ldap": { "url": "http://myldap/my_other_root", "user_tree_dn": "ou=Users,dc=my_new_root,dc=org" } } } 
DELETE
/v3/domains/ {domain_id}/config/{group}/{option}
Delete domain group option configuration
 
 

Deletes a domain group option configuration.

The API supports only the identity and ldap groups. For the ldap group, a valid value is url or user_tree_dn. For the identity group, a valid value is driver.

Error response codes:204,413,415,405,404,403,401,400,503,409,

Request

Name In Type Description
domain_id path string Filters the response by a domain ID.
group body object A group object, containing:
option path string The option name. For the ldap group, a valid value is url or user_tree_dn. For the identity group, a valid value is driver.
GET
/v3/domains/ {domain_id}/config/{group}
Show domain group configuration
 
 

Shows details for a domain group configuration.

The API supports only the identity and ldap groups.

Normal response codes: 200 Error response codes:413,405,404,403,401,400,503,

Request

Name In Type Description
domain_id path string Filters the response by a domain ID.
group body object A group object, containing:

Response Parameters

Name In Type Description
url body string The endpoint URL.
driver body string The Identity back-end driver.
ldap body object An ldap object. Required to set the LDAP group configuration options.
config body object A config object.
user_tree_dn body string The base distinguished name (DN) of LDAP, from where all users can be reached. For example, ou=Users,dc=root,dc=org.
identity body object An identity object.

Response Example

{
    "ldap": {
        "url": "http://myldap/root", "user_tree_dn": "ou=Users,dc=root,dc=org" } } 
PATCH
/v3/domains/ {domain_id}/config/{group}
Update domain group configuration
 
 

Updates a domain group configuration.

The API supports only the identity and ldap groups. If you try to set configuration options for other groups, this call fails with the Forbidden (403) response code.

Normal response codes: 200 Error response codes:413,415,405,404,403,401,400,503,409,

Request

Name In Type Description
url body string The endpoint URL.
driver body string The Identity back-end driver.
ldap body object An ldap object. Required to set the LDAP group configuration options.
config body object A config object.
user_tree_dn body string The base distinguished name (DN) of LDAP, from where all users can be reached. For example, ou=Users,dc=root,dc=org.
identity body object An identity object.
domain_id path string Filters the response by a domain ID.
group body object A group object, containing:

Request Example

{
    "config": {
        "ldap": { "url": "http://myldap/my_new_root", "user_tree_dn": "ou=Users,dc=my_new_root,dc=org" } } } 

Response Parameters

Name In Type Description
url body string The endpoint URL.
driver body string The Identity back-end driver.
ldap body object An ldap object. Required to set the LDAP group configuration options.
config body object A config object.
user_tree_dn body string The base distinguished name (DN) of LDAP, from where all users can be reached. For example, ou=Users,dc=root,dc=org.
identity body object An identity object.

Response Example

{
    "config": {
        "identity": { "driver": "keystone.identity.backends.ldap.Identity" }, "ldap": { "url": "http://myldap/my_new_root", "user_tree_dn": "ou=Users,dc=my_new_root,dc=org" } } } 
DELETE
/v3/domains/ {domain_id}/config/{group}
Delete domain group configuration
 
 

Deletes a domain group configuration.

The API supports only the identity and ldap groups.

Error response codes:204,413,415,405,404,403,401,400,503,409,

Request

Name In Type Description
domain_id path string Filters the response by a domain ID.
group body object A group object, containing:
GET
/v3/domains/ {domain_id}/config
Show domain configuration
 
 

Shows details for a domain configuration.

Normal response codes: 200 Error response codes:413,405,404,403,401,400,503,

Request

Name In Type Description
domain_id path string Filters the response by a domain ID.

Response Parameters

Name In Type Description
url body string The endpoint URL.
driver body string The Identity back-end driver.
ldap body object An ldap object. Required to set the LDAP group configuration options.
config body object A config object.
user_tree_dn body string The base distinguished name (DN) of LDAP, from where all users can be reached. For example, ou=Users,dc=root,dc=org.
identity body object An identity object.

Response Example

{
    "config": {
        "identity": { "driver": "keystone.identity.backends.ldap.Identity" }, "ldap": { "url": "http://myldap/root", "user_tree_dn": "ou=Users,dc=root,dc=org" } } } 
PATCH
/v3/domains/ {domain_id}/config
Update domain configuration
 
 

Updates a domain configuration.

Normal response codes: 200 Error response codes:413,415,405,404,403,401,400,503,409,

Request

Name In Type Description
url body string The endpoint URL.
driver body string The Identity back-end driver.
ldap body object An ldap object. Required to set the LDAP group configuration options.
config body object A config object.
user_tree_dn body string The base distinguished name (DN) of LDAP, from where all users can be reached. For example, ou=Users,dc=root,dc=org.
identity body object An identity object.
domain_id path string Filters the response by a domain ID.

Request Example

{
    "config": {
        "ldap": { "url": "http://myldap/my_new_root", "user_tree_dn": "ou=Users,dc=my_new_root,dc=org" } } } 

Response Parameters

Name In Type Description
url body string The endpoint URL.
driver body string The Identity back-end driver.
ldap body object An ldap object. Required to set the LDAP group configuration options.
config body object A config object.
user_tree_dn body string The base distinguished name (DN) of LDAP, from where all users can be reached. For example, ou=Users,dc=root,dc=org.
identity body object An identity object.

Response Example

{
    "config": {
        "identity": { "driver": "keystone.identity.backends.ldap.Identity" }, "ldap": { "url": "http://myldap/my_new_root", "user_tree_dn": "ou=Users,dc=my_new_root,dc=org" } } } 
DELETE
/v3/domains/ {domain_id}/config
Delete domain configuration
 
 

Deletes a domain configuration.

Error response codes:204,413,415,405,404,403,401,400,503,409,

Request

Name In Type Description
domain_id path string Filters the response by a domain ID.

Groups

A group is a collection of users. Each group is owned by a domain.

You can use groups to ease the task of managing role assignments for users. Assigning a role to a group on a project or domain is equivalent to assigning the role to each group member on that project or domain.

When you unassign a role from a group, that role is automatically unassigned from any user that is a member of the group. Any tokens that authenticates those users to the relevant project or domain are revoked.

As with users, a group without any role assignments is useless from the perspective of an OpenStack service and has no access to resources. However, a group without role assignments is permitted as a way of acquiring or loading users and groups from external sources before mapping them to projects and domains.

GET
/v3/groups/ {group_id}
Show group details
 
 

Shows details for a group.

Normal response codes: 200 Error response codes:413,405,404,403,401,400,503,

Request

Name In Type Description
group_id path string The group ID.

Response Parameters

Name In Type Description
group body object A group object, containing:
description body string The description of the group.
domain_id body string The ID of the domain of the group.
id body string The ID of the group.
links body string The link to the resources in question.
name body string The name of the group.

Response Example

{
    "group": {
        "description": "Contract developers", "domain_id": "default", "id": "c0d675eac29945ad9dfd08aa1bb75751", "links": { "self": "http://example.com/identity/v3/groups/c0d675eac29945ad9dfd08aa1bb75751" }, "name": "Contract developers" } } 
PATCH
/v3/groups/ {group_id}
Update group
 
 

Updates a group.

If the back-end driver does not support this functionality, the call returns the Not Implemented (501) response code.

Normal response codes: 200 Error response codes:413,415,405,404,403,401,400,503,409,

Request

Name In Type Description
group_id path string The group ID.
group body object A group object, containing:
description (Optional) body string The new description of the group.
domain_id (Optional) body string The ID of the new domain for the group. The ability to change the domain of a group is now deprecated, and will be removed in subsequent release. It is already disabled by default in most Identity service implementations.
name (Optional) body string The new name of the group.

Request Example

{
    "group": {
        "description": "Contract developers 2016", "name": "Contract developers 2016" } } 

Response Parameters

Name In Type Description
group body object A group object, containing:
description body string The description of the group.
domain_id body string The ID of the domain of the group.
id body string The ID of the group.
links body string The link to the resources in question.
name body string The name of the group.

Response Example

{
    "group": {
        "description": "Contract developers 2016", "domain_id": "default", "id": "c0d675eac29945ad9dfd08aa1bb75751", "links": { "self": "http://example.com/identity/v3/groups/c0d675eac29945ad9dfd08aa1bb75751" }, "name": "Contract developers 2016" } } 
DELETE
/v3/groups/ {group_id}
Delete group
 
 

Deletes a group.

Error response codes:204,413,415,405,404,403,401,400,503,409,

Request

Name In Type Description
group_id path string The group ID.
PUT
/v3/groups/ {group_id}/users/{user_id}
Add user to group
 
 

Adds a user to a group.

Error response codes:204,413,415,405,404,403,401,400,503,409,

Request

Name In Type Description
user_id path string The user ID.
group_id path string The group ID.
DELETE
/v3/groups/ {group_id}/users/{user_id}
Remove user from group
 
 

Removes a user from a group.

Normal response codes: 204 Error response codes:413,415,405,404,403,401,400,503,409,

Request

Name In Type Description
user_id path string The user ID.
group_id path string The group ID.
HEAD
/v3/groups/ {group_id}/users/{user_id}
Check whether user belongs to group
 
 

Validates that a user belongs to a group.

Normal response codes: 204 Error response codes:413,405,404,403,401,400,503,

Request

Name In Type Description
user_id path string The user ID.
group_id path string The group ID.
GET
/v3/groups/ {group_id}/users
List users in group
 
 

Lists the users that belong to a group.

Normal response codes: 200 Error response codes:413,405,404,403,401,400,503,

Request

Name In Type Description
group_id path string The group ID.

Response Example

{
    "links": {
        "self": "http://example.com/identity/v3/groups/9ce0ad4e58a84d7a97b92f7955d10c92/users", "previous": null, "next": null }, "users": [ { "domain_id": "default", "description": null, "enabled": true, "id": "acd565a08293c1e48bc0dd0d72ad5d5d" "name": "Henry", "links": { "self": "http://example.com/identity/v3/users/acd565a08293c1e48bc0dd0d72ad5d5d" } }, { "domain_id": "default", "description": null, "enabled": true, "id": "fff603a0829d41e48bc0dd0d72ad61ce", "name": "Paul", "links": { "self": "http://example.com/identity/v3/users/fff603a0829d41e48bc0dd0d72ad61ce" }, "password_expires_at": "2016-11-06T15:32:17.000000" } ] } 
POST
/v3/groups
Create group
 
 

Creates a group.

Normal response codes: 201 Error response codes:413,415,405,404,403,401,400,503,409,

Request

Name In Type Description
group body object A group object, containing:
description body string The description of the group.
domain_id body string The ID of the domain of the group.
name body string The name of the group.

Request Example

{
    "group": {
        "description": "Contract developers", "domain_id": "default", "name": "Contract developers" } } 

Response Parameters

Name In Type Description
group body object A group object, containing:
description body string The description of the group.
domain_id body string The ID of the domain of the group.
id body string The ID of the group.
links body string The link to the resources in question.
name body string The name of the group.

Response Example

{
    "group": {
        "description": "Contract developers", "domain_id": "default", "id": "c0d675eac29945ad9dfd08aa1bb75751", "links": { "self": "http://example.com/identity/v3/groups/c0d675eac29945ad9dfd08aa1bb75751" }, "name": "Contract developers" } } 
GET
/v3/groups
List groups
 
 

Lists groups.

Normal response codes: 200 Error response codes:413,405,404,403,401,400,503,

Request

Name In Type Description
name (Optional) query string Filters the response by a group name.
domain_id (Optional) query string Filters the response by a domain ID.

Response Parameters

Name In Type Description
links body string The link to the collection of resources.
groups body array A list of group objects, each containing:
description body string The description of the group.
domain_id body string The ID of the domain of the group.
id body string The ID of the group.
links body string The link to the resources in question.
name body string The name of the group.

Response Example

{
    "links": {
        "self": "http://example.com/identity/v3/groups", "previous": null, "next": null }, "groups": [ { "description": "non-admin group", "domain_id": "default", "id": "96372bbb152f475aa37e9a76a25a029c", "links": { "self": "http://example.com/identity/v3/groups/96372bbb152f475aa37e9a76a25a029c" }, "name": "nonadmins" }, { "description": "openstack admin group", "domain_id": "default", "id": "9ce0ad4e58a84d7a97b92f7955d10c92", "links": { "self": "http://example.com/identity/v3/groups/9ce0ad4e58a84d7a97b92f7955d10c92" }, "name": "admins" } ] } 

OS-INHERIT API

Enables projects to inherit role assignments from either their owning domain or projects that are higher in the hierarchy.

(Since API v3.4) The OS-INHERIT extension allows inheritance from both projects and domains. To access project inheritance, the Identity service server must run at least API v3.4.

PUT
/v3/OS-INHERIT/domains/ {domain_id}/users/{user_id}/roles/{role_id}/inherited_to_projects
Assign role to user on projects owned by domain
 
 

Relationship: http://developer.openstack.org/api-ref/identity/v3/index.html#assign-role-to-user-owned-by-domain-projects

Assigns a role to a user in projects owned by a domain.

The inherited role is only applied to the owned projects (both existing and future projects), and will not appear as a role in a domain scoped token.

Normal response codes: 204

Request

Name In Type Description
domain_id path string Filters the response by a domain ID.
role_id path string The role ID.
user_id path string The user ID.
PUT
/v3/OS-INHERIT/domains/ {domain_id}/groups/{group_id}/roles/{role_id}/inherited_to_projects
Assign role to group on projects owned by a domain
 
 

Relationship: http://developer.openstack.org/api-ref/identity/v3/?expanded=#assign-role-to-group-in-domain-projects

The inherited role is only applied to the owned projects (both existing and future projects), and will not appear as a role in a domain scoped token.

Normal response codes: 204

Request

Name In Type Description
domain_id path string Filters the response by a domain ID.
group_id path string The group ID.
role_id path string The role ID.
GET
/v3/OS-INHERIT/domains/ {domain_id}/users/{user_id}/roles/inherited_to_projects
List user's inherited project roles on a domain
 
 

Relationship: http://developer.openstack.org/api-ref/identity/v3/?expanded=#list-project-roles-for-user-in-domain

The list only contains those role assignments to the domain that were specified as being inherited to projects within that domain.

Normal response codes: 200

Request

Name In Type Description
domain_id path string Filters the response by a domain ID.
user_id path string The user ID.

Response Example

{
    "roles": [
        {
            "id": "91011", "links": { "self": "http://example.com/identity/v3/roles/91011" }, "name": "admin" }, { "id": "91011", "links": { "self": "http://example.com/identity/v3/roles/91011" }, "name": "admin" } ], "links": { "self": "http://example.com/identity/v3/OS-INHERIT/domains/1234/users/5678/roles/inherited_to_projects", "previous": null, "next": null } } 
GET
/v3/OS-INHERIT/domains/ {domain_id}/groups/{group_id}/roles/inherited_to_projects
List group's inherited project roles on domain
 
 

Relationship: http://developer.openstack.org/api-ref/identity/v3/?expanded=#list-project-roles-for-group-in-domain

The list only contains those role assignments to the domain that were specified as being inherited to projects within that domain.

Normal response codes: 200

Request

Name In Type Description
domain_id path string Filters the response by a domain ID.
group_id path string The group ID.

Response Example

{
    "roles": [
        {
            "id": "91011", "links": { "self": "http://example.com/identity/v3/roles/91011" }, "name": "admin" }, { "id": "91011", "links": { "self": "http://example.com/identity/v3/roles/91011" }, "name": "admin" } ], "links": { "self": "http://example.com/identity/v3/OS-INHERIT/domains/1234/groups/5678/roles/inherited_to_projects", "previous": null, "next": null } } 
HEAD
/v3/OS-INHERIT/domains/ {domain_id}/users/{user_id}/roles/{role_id}/inherited_to_projects
Check if user has an inherited project role on domain
 
 

Relationship: http://developer.openstack.org/api-ref/identity/v3/?expanded=#check-project-role-for-user-in-domain

Checks whether a user has an inherited project role in a domain.

Normal response codes: 204

Request

Name In Type Description
domain_id path string Filters the response by a domain ID.
role_id path string The role ID.
user_id path string The user ID.
HEAD
/v3/OS-INHERIT/domains/ {domain_id}/groups/{group_id}/roles/{role_id}/inherited_to_projects
Check if group has an inherited project role on domain
 
 

Relationship: http://developer.openstack.org/api-ref/identity/v3/?expanded=#check-project-role-for-group-in-domain

Checks whether a group has an inherited project role in a domain.

Normal response codes: 204

Request

Name In Type Description
domain_id path string Filters the response by a domain ID.
group_id path string The group ID.
role_id path string The role ID.
DELETE
/v3/OS-INHERIT/domains/ {domain_id}/users/{user_id}/roles/{role_id}/inherited_to_projects
Revoke an inherited project role from user on domain
 
 

Relationship: http://developer.openstack.org/api-ref/identity/v3/?expanded=#revoke-role-from-user

Revokes an inherited project role from a user in a domain.

Normal response codes: 204

Request

Name In Type Description
domain_id path string Filters the response by a domain ID.
role_id path string The role ID.
user_id path string The user ID.
DELETE
/v3/OS-INHERIT/domains/ {domain_id}/groups/{group_id}/roles/{role_id}/inherited_to_projects
Revoke an inherited project role from group on domain
 
 

Relationship: http://developer.openstack.org/api-ref/identity/v3/?expanded=#revoke-project-role-from-group-in-domain

Revokes an inherited project role from a group in a domain.

Normal response codes: 204

Request

Name In Type Description
domain_id path string Filters the response by a domain ID.
group_id path string The group ID.
role_id path string The role ID.
PUT
/v3/OS-INHERIT/projects/ {project_id}/users/{user_id}/roles/{role_id}/inherited_to_projects
Assign role to user on projects in a subtree
 
 

Relationship: http://developer.openstack.org/api-ref/identity/v3/?expanded=#assign-role-to-user

The inherited role assignment is anchored to a project and applied to its subtree in the projects hierarchy (both existing and future projects).

  • Note: It is possible for a user to have both a regular (non-inherited) and an inherited role assignment on the same project.
  • Note: The request doesn’t require a body, which will be ignored if provided.

Normal response codes: 204

Request

Name In Type Description
project_id path string The project ID.
role_id path string The role ID.
user_id path string The user ID.
PUT
/v3/OS-INHERIT/projects/ {project_id}/groups/{group_id}/roles/{role_id}/inherited_to_projects
Assign role to group on projects in a subtree
 
 

Relationship: http://developer.openstack.org/api-ref/identity/v3/?expanded=#assign-role-to-group

The inherited role assignment is anchored to a project and applied to its subtree in the projects hierarchy (both existing and future projects).

  • Note: It is possible for a group to have both a regular (non-inherited) and an inherited role assignment on the same project.
  • Note: The request doesn’t require a body, which will be ignored if provided.

Normal response codes: 204

Request

Name In Type Description
group_id path string The group ID.
project_id path string The project ID.
role_id path string The role ID.
GET
/v3/OS-INHERIT/projects/ {project_id}/users/{user_id}/roles/inherited_to_projects
List user's inherited project roles on project
 
 

Relationship: http://developer.openstack.org/api-ref/identity/v3/?expanded=#list-inherited-roles-for-user

The list only contains those roles assigned to this project that were specified as being inherited to its subtree.

Normal response codes: 200

Request

Name In Type Description
project_id path string The project ID.
user_id path string The user ID.

Response Example

{
    "roles": [
        {
            "id": "91011", "links": { "self": "http://example.com/identity/v3/roles/91011" }, "name": "admin" }, { "id": "91011", "links": { "self": "http://example.com/identity/v3/roles/91011" }, "name": "admin" } ], "links": { "self": "http://example.com/identity/v3/OS-INHERIT/projects/1234/users/5678/roles/inherited_to_projects", "previous": null, "next": null } } 
GET
/v3/OS-INHERIT/projects/ {project_id}/groups/{group_id}/roles/inherited_to_projects
List group's inherited project roles on project
 
 

Relationship: http://developer.openstack.org/api-ref/identity/v3/?expanded=#list-roles-for-group

The list only contains those roles assigned to this project that were specified as being inherited to its subtree.

Normal response codes: 200

Request

Name In Type Description
group_id path string The group ID.
project_id path string The project ID.

Response Example

{
    "roles": [
        {
            "id": "91011", "links": { "self": "http://example.com/identity/v3/roles/91011" }, "name": "admin" }, { "id": "91011", "links": { "self": "http://example.com/identity/v3/roles/91011" }, "name": "admin" } ], "links": { "self": "http://example.com/identity/v3/OS-INHERIT/projects/1234/groups/5678/roles/inherited_to_projects", "previous": null, "next": null } } 
HEAD
/v3/OS-INHERIT/projects/ {project_id}/users/{user_id}/roles/{role_id}/inherited_to_projects
Check if user has an inherited project role on project
 
 

Relationship: http://developer.openstack.org/api-ref/identity/v3/?expanded=#check-role-for-user

Checks whether a user has a role assignment with the inherited_to_projects flag in a project.

Normal response codes: 200

Request

Name In Type Description
project_id path string The project ID.
role_id path string The role ID.
user_id path string The user ID.
HEAD
/v3/OS-INHERIT/projects/ {project_id}/groups/{group_id}/roles/{role_id}/inherited_to_projects
Check if group has an inherited project role on project
 
 

Relationship: http://developer.openstack.org/api-ref/identity/v3/?expanded=#check-role-for-group

Checks whether a group has a role assignment with the inherited_to_projects flag in a project.

Normal response codes: 200

Request

Name In Type Description
group_id path string The group ID.
project_id path string The project ID.
role_id path string The role ID.
DELETE
/v3/OS-INHERIT/projects/ {project_id}/users/{user_id}/roles/{role_id}/inherited_to_projects
Revoke an inherited project role from user on project
 
 

Relationship: http://developer.openstack.org/api-ref/identity/v3/?expanded=#revoke-role-from-user

Normal response codes: 204

Request

Name In Type Description
project_id path string The project ID.
role_id path string The role ID.
user_id path string The user ID.
DELETE
/v3/OS-INHERIT/projects/ {project_id}/groups/{group_id}/roles/{role_id}/inherited_to_projects
Revoke an inherited project role from group on project
 
 

Relationship: http://developer.openstack.org/api-ref/identity/v3/?expanded=#revoke-role-from-group

Normal response codes: 204

Request

Name In Type Description
group_id path string The group ID.
project_id path string The project ID.
role_id path string The role ID.
GET
/v3/role_assignments
List effective role assignments
 
 

Relationship: http://developer.openstack.org/api-ref/identity/v3/?expanded=#list-effective-role-assignments

Optional query parameters:

Name In Type Description
effective (Optional) query key-only (no value required) Returns the effective assignments, including any assignments gained by virtue of group membership.
include_names (Optional) query boolean

If set to true, then the names of any entities returned will be include as well as their IDs. Any value other than 0 (including no value) will be interpreted as true.

New in version 3.6

include_subtree (Optional) query boolean

If set to true, then relevant assignments in the project hierarchy below the project specified in the scope.project_id query parameter are also included in the response. Any value other than 0 (including no value) for include_subtree will be interpreted as true.

New in version 3.6

group_id (Optional) query string Filters the response by a group ID.
role_id (Optional) query string Filters the response by a role ID.
scope.domain.id (Optional) query string Filters the response by a domain ID.
scope.OS-INHERIT:inherited_to (Optional) query string Filters based on role assignments that are inherited. The only value of inherited_to that is currently supported is projects.
scope.project.id (Optional) query string Filters the response by a project ID.
user_id (Optional) query string Filters the response by a user ID.

Get a list of role assignments.

If no query parameters are specified, then this API will return a list of all role assignments.

{
    "role_assignments": [
        {
            "links": { "assignment": "http://example.com/identity/v3/domains/161718/users/313233/roles/123456" }, "role": { "id": "123456" }, "scope": { "domain": { "id": "161718" } }, "user": { "id": "313233" } }, { "group": { "id": "101112" }, "links": { "assignment": "http://example.com/identity/v3/projects/456789/groups/101112/roles/123456" }, "role": { "id": "123456" }, "scope": { "project": { "id": "456789" } } } ], "links": { "self": "http://example.com/identity/v3/role_assignments", "previous": null, "next": null } } 

Since this list is likely to be very long, this API would typically always be used with one of more of the filter queries. Some typical examples are:

GET /v3/role_assignments?user.id={user_id} would list all role assignments involving the specified user.

GET /v3/role_assignments?scope.project.id={project_id} would list all role assignments involving the specified project.

It is also possible to list all role assignments within a tree of projects: GET /v3/role_assignments?scope.project.id={project_id}?include_subtree=true would list all role assignments involving the specified project and all sub-projects. include_subtree=true can only be specified in conjunction with scope.project.id, specifiying it without this will result in an HTTP 400 Bad Request being returned.

Each role assignment entity in the collection contains a link to the assignment that gave rise to this entity.

The scope section in the list response is extended to allow the representation of role assignments that are inherited to projects.

{
        "role_assignments": [
            {
                "links": { "assignment": "http://example.com/identity/v3/OS-INHERIT/domains/161718/users/313233/roles/123456/inherited_to_projects" }, "role": { "id": "123456" }, "scope": { "domain": { "id": "161718" }, "OS-INHERIT:inherited_to": "projects" }, "user": { "id": "313233" } }, { "group": { "id": "101112-" }, "links": { "assignment": "http://example.com/identity/v3/projects/456789/groups/101112/roles/123456" }, "role": { "id": "123456" }, "scope": { "project": { "id": "456789" } } } ], "links": { "self": "http://example.com/identity/v3/role_assignments", "previous": null, "next": null } } 

The query filter scope.OS-INHERIT:inherited_to can be used to filter based on role assignments that are inherited. The only value of scope.OS-INHERIT:inherited_to that is currently supported is projects, indicating that this role is inherited to all projects of the owning domain or parent project.

If the query parameter effective is specified, rather than simply returning a list of role assignments that have been made, the API returns a list of effective assignments at the user, project and domain level, having allowed for the effects of group membership, role inference rules as well as inheritance from the parent domain or project. Since the effects of group membership have already been allowed for, the group role assignment entities themselves will not be returned in the collection. Likewise, since the effects of inheritance have already been allowed for, the role assignment entities themselves that specify the inheritance will also not be returned in the collection. This represents the effective role assignments that would be included in a scoped token. The same set of query parameters can also be used in combination with the effective parameter.

For example:

GET /v3/role_assignments?user.id={user_id}&effective would, in other words, answer the question “what can this user actually do?”.

GET /v3/role_assignments?user.id={user_id}&scope.project.id={project_id}&effective would return the equivalent set of role assignments that would be included in the token response of a project scoped token.

An example response for an API call with the query parameter effective specified is given below:

{
    "role_assignments": [
        {
            "links": { "assignment": "http://example.com/identity/v3/domains/161718/users/313233/roles/123456" }, "role": { "id": "123456" }, "scope": { "domain": { "id": "161718" } }, "user": { "id": "313233" } }, { "links": { "assignment": "http://example.com/identity/v3/projects/456789/groups/101112/roles/123456", "membership": "http://example.com/identity/v3/groups/101112/users/313233" }, "role": { "id": "123456" }, "scope": { "project": { "id": "456789" } }, "user": { "id": "313234" } } ], "links": { "self": "http://example.com/identity/v3/role_assignments?effective", "previous": null, "next": null } } 

The entity links section of a response using the effective query parameter also contains, for entities that are included by virtue of group membership, a url that can be used to access the membership of the group.

If the query parameter include_names is specified, rather than simply returning the entity IDs in the role assignments, the collection will additionally include the names of the entities. For example:

GET /v3/role_assignments?user.id={user_id}&effective&include_names=true would return:

Normal response codes: 200 Error response codes: 400, 401, 403, 404, 405, 413, 503

Policies

A policy is an arbitrarily serialized policy engine rule set to be consumed by a remote service.

You encode policy rule sets into a blob that remote services can consume. To do so, set type to application/json and specify policy rules as JSON strings in a blob. For example:

{
    "blob":{
        "foobar_user":[
            "role:compute-user" ] } } 
POST
/v3/policies
Create policy
 
 

Creates a policy.

Normal response codes: 201 Error response codes: 413,415,405,404,403,401,400,503,409

Request

Name In Type Description
policy body object A policy object.
user_id path string The user ID.
project_id path string The project ID.
type body string The endpoint type.
blob body string The credential itself, as a serialized blob.

Request Example

{
    "policy": {
        "blob": "{'foobar_user': 'role:compute-user'}", "project_id": "0426ac1e48f642ef9544c2251e07e261", "type": "application/json", "user_id": "0ffd248c55b443eaac5253b4e9cbf9b5" } } 

Response Parameters

Name In Type Description
user_id path string The user ID.
links body object The links for the credential resource.
blob body string The credential itself, as a serialized blob.
policy body object A policy object.
project_id path string The project ID.
type body string The endpoint type.
id (Optional) body string The ID of the user. Required if you do not specify the user name.
GET
/v3/policies
List policies
 
 

Lists policies.

Normal response codes: 200 Error response codes: 413,405,404,403,401,400,503

Request

Name In Type Description
type body string The endpoint type.

Response Parameters

Name In Type Description
user_id path string The user ID.
links body object The links for the credential resource.
blob body string The credential itself, as a serialized blob.
policies body array A policies object.
project_id path string The project ID.
type body string The endpoint type.
id (Optional) body string The ID of the user. Required if you do not specify the user name.

Response Example

{
    "links": {
        "next": null, "previous": null, "self": "http://example.com/identity/v3/policies" }, "policies": [ { "blob": { "foobar_user": [ "role:compute-user" ] }, "id": "717273", "links": { "self": "http://example.com/identity/v3/policies/717273" }, "project_id": "456789", "type": "application/json", "user_id": "616263" }, { "blob": { "foobar_user": [ "role:compute-user" ] }, "id": "717274", "links": { "self": "http://example.com/identity/v3/policies/717274" }, "project_id": "456789", "type": "application/json", "user_id": "616263" } ] } 
GET
/v3/policies/ {policy_id}
Show policy details
 
 

Shows details for a policy.

Normal response codes: 200 Error response codes: 413,405,404,403,401,400,503