标签：
OpenStack Identity API v3 OS-ENDPOINT-POLICY
The Identity API primarily fulfills authentication and authorization needs within OpenStack, and is intended to provide a programmatic facade in front of existing authentication and authorization system(s).
The Identity API also provides endpoint discovery through a service catalog, identity management, project management, and a centralized repository for policy engine rule sets.
These features are considered stable as of September 4th, 2014.
These features are considered stable as of January 23, 2014.
These features are considered stable as of July 18, 2013.
These features are considered stable as of February 20, 2013.
This document is always evolving as new features are added, use cases are clarified, etc. API features added since the original publication of this document are summarized above, grouped by the API version in which they were first introduced. This document is treated as the single source of truth for the entire 3.x series of the API.
A particular implementation of the API is never referenced by name. This is documentation for the HTTP API itself. Details of the code-base servicing the API, such as architecture, configuration, and deployment, are not relevant here.
The “API Conventions” section defines architectural patterns applied to the entire API until a portion of the API documents an exception to the overall conventions. Details of the conventions are not repeated throughout the document, except in examples, so the reader is expected to have understood the conventions before reading any further. The goal is to reduce the cost of documentation maintenance (DRY) and improve self-consistency across the API, which makes the API more intuitive to readers and fosters simpler implementations.
A high level overview of the resources presented by the API are documented in the “API Resources” section, including required and optional attributes, use cases and expected behaviors. Specific API calls are not enumerated, although the feature set of the related calls should be described if it deviates from the conventions used by the rest of the API (for example, a resource could be constrained as “a read-only collection”).
Finally, the specific calls supported by the API are enumerated with examples at the end of the document. The examples are intended to be “realistic” representations of actual requests and responses you could expect from an implementation of the API. Specifically, the JSON should be syntactically valid and use data that is self-consistent with related calls.
The features described by this document are intended to be applicable to all implementations of the API. If a particular implementation or deployment should not be expected to have a use case for a particular feature, that feature should be documented as an extension to this API. Extensions may suffix existing resources with their own namespace in order to add new resources, or prefix new attributes on existing resource representations. To clearly distinguish extensions from the core API (which is described by this document) and avoid namespace collisions between extensions, suffixes and prefixes are composed of an uppercased abbreviation of the organization supporting the extension (such as “OS” for OpenStack), followed by a hyphen (“-”), followed by an uppercased abbreviation of the extension name (such as “OAUTH1” for OAuth 1.0). Therefore, an extension could be identified as “OS-OAUTH1”.
This section describes architectural patterns applied throughout the Identity API, unless an exception to these conventions is specifically documented. In general, the Identity API provides an HTTP interface using JSON as the primary transport format.
Each resource contains a canonically unique identifier (ID) defined by the Identity service implementation and is provided as the id attribute; Resource ID’s are strings of non-zero length.
The resource paths of all collections are plural and are represented at the root of the API (e.g. /v3/policies).
TCP port 35357 is designated by the Internet Assigned Numbers Authority (“IANA”) for use by OpenStack Identity services. Example API requests and responses in this document therefore assume that the Identity service implementation is deployed at the root of http://identity:35357/.
X-Auth-Token
This header is used to convey the API user’s authentication token when accessing Identity APIs.
X-Subject-Token
This header is used to convey the subject of the request for token-related operations.
New in version 3.4
X-Project-Id
X-Project-Name
X-Project-Domain-Id
X-Project-Domain-Name
For tokenless authorization, these headers are used to convey the project scope information. To scope to a project, caller must provide either X-Project-Id or combination of X-Project-Name and X-Project-Domain-Id or X-Project-Domain-Name.
X-Domain-Id
X-Domain-Name
For tokenless authorization, these headers are used to convey the domain scope information. To scope to a domain, caller must provide either X-Domain-Id or X-Domain-Name.
New in version 3.7
X-OpenStack-API-Version: [SERVICE_TYPE] microversion
This header is used to convey the microversion with which the client is communicating for OpenStack APIs, specifying a microversion for given service type. Multiple service types can be specified, for example:
X-OpenStack-API-Version: identity 3.7, compute 2.12
The Identity server will ignore any components of the header other than that for the identity` service type. The server will respond as appropriate for that microversion, provided that it can support the requested version. It will include the same header in the response to indicate this. If the server does not support the requested version an HTTP 406 Not Acceptable is returned. The version specified by the client is of the form “X.Y”, where “X” is the major version supported and “Y” is the microversion within that major version. For Newton, this is “3.7”. The earliest microversion that can be requested is “3.6”. Two special values of the header are supported, namely “latest” and “X.latest”, where “X” is the major version. In both cases, the server will indicate the exact microversion being used in the header in the response.
For collections:
links (object)
Specifies a list of relational links to the collection.
self (url)
A self-relational link provided as an absolute URL. This attribute is provided by the identity service implementation.
previous (url)
A relational link to the previous page of the list, provided as an absolute URL. This attribute is provided by the identity service implementation. May be null.
next (url)
A relational to the next page of the list, provided as an absolute URL. This attribute is provided by the identity service implementation. May be null.
For members:
id (string)
Globally unique resource identifier. This attribute is provided by the identity service implementation.
links (object)
Specifies a set of relational links relative to the collection member.
self (url)
A self-relational link provided as an absolute URL. This attribute is provided by the identity service implementation.
For collections:
truncated (boolean)
In the case where a particular implementation has restricted the number of entries that can be returned in a collection and not all entries could be included, the list call will return a status code of 200 (OK), with truncated set to true. If this attribute is not present (or is set to false) then the list represents the complete collection, unless either the next or previous links are not null, in which case the list represents a page within the complete collection.
Unless otherwise documented (tokens being the notable exception), all resources provided by the Identity API support basic CRUD operations (create, read, update, delete).
The examples in this section utilize a resource collection of Entities on /v3/entities which is not actually a part of the Identity API, and is used for illustrative purposes only.
When creating an entity, you must provide all required attributes (except those provided by the Identity service implementation, such as the resource ID):
Request:
POST /entities
{
"entity": {
"name": string,
"description": string,
"enabled": boolean
}
}
The full entity is returned in a successful response (including the new resource’s ID and a self-relational link), keyed by the singular form of the resource name:
201 Created
{
"entity": {
"id": string,
"name": string,
"description": string,
"enabled": boolean,
"links": {
"self": url
}
}
}
Request the entire collection of entities:
GET /entities
A successful response includes a list of anonymous dictionaries, keyed by the plural form of the resource name (identical to that found in the resource URL):
200 OK
{
"entities": [
{
"id": string,
"name": string,
"description": string,
"enabled": boolean,
"links": {
"self": url
}
},
{
"id": string,
"name": string,
"description": string,
"enabled": boolean,
"links": {
"self": url
}
}
],
"links": {
"self": url,
"next": url,
"previous": url
}
}
Beyond each resource’s canonically unique identifier (the id attribute), not all attributes are guaranteed unique on their own. To filter a list of resources based on a specific attribute, we can perform a filtered query using one or more query parameters:
GET /entities?name={entity_name}&enabled
If multiple filters are specified in a query, then all filters must match for an entity to be included in the response. The values specified in a filter must be of the same type as the attribute, and in the case of strings are limited to the same maximum length as the attribute.
The response is a subset of the full collection:
200 OK
{
"entities": [
{
"id": string,
"name": string,
"description": string,
"enabled": boolean,
"links": {
"self": url
}
}
],
"links": {
"self": url,
"next": url,
"previous": url
}
}
New in version 3.2 String attributes may also be filtered using inexact patterns, for example:
GET /entities?name__startswith={initial_characters_of_entity_name}
The following inexact suffixes are supported:
__startswith
Matches if the attribute starts with the characters specified, with the comparison being case-sensitive.
__istartswith
Matches if the attribute starts with the characters specified, with the comparison being case-insensitive.
__endswith
Matches if the attribute ends with the characters specified, with the comparison being case-sensitive.
__iendswith
Matches if the attribute ends with the characters specified, with the comparison being case-insensitive.
__contains
Matches if the attribute contains the characters specified, with the comparison being case-sensitive.
__icontains
Matches if the attribute contains the characters specified, with the comparison being case-insensitive.
Inexact filters specified for non-string attributes will be ignored.
Request a specific entity by ID:
GET /entities/{entity_id}
The full resource is returned in response:
200 OK
{
"entity": {
"id": string,
"name": string,
"description": string,
"enabled": boolean,
"links": {
"self": url
}
}
}
An entity may contain nested collections, in which case the required attributes for collections still apply; however, to avoid conflicts with other required attributes, the required attributes of the collection are prefixed with the name of the collection. For example, if an entity contains a nested collection of objects, the links for the collection of objects is called objects_links:
{
"entity": {
"id": string,
"name": string,
"description": string,
"enabled": boolean,
"links": {
"self": url
},
"objects": [
{
"id": string,
"name": string,
"description": string,
"enabled": boolean,
"links": {
"self": url
}
}
],
"objects_links": {
"self": url,
"next": url,
"previous": url
}
}
}
Partially update an entity (unlike a standard PUT operation, only the specified attributes are replaced):
PATCH /entities/{entity_id}
{
"entity": {
"description": string
}
}
The full entity is returned in response:
200 OK
{
"entity": {
"id": string,
"name": string,
"description": string,
"enabled": boolean,
"links": {
"self": url
}
}
}
Delete a specific entity by ID:
DELETE /entities/{entity_id}
A successful response does not include a body:
204 No Content
The Identity API uses a subset of the available HTTP status codes to communicate specific success and failure conditions to the client.
This status code is returned in response to successful GET, HEAD and PATCH operations.
This status code is returned in response to successful POST operations.
This status code is returned in response to successful HEAD, PUT and DELETE operations.
This status code is returned by the root identity endpoint, with references to one or more Identity API versions (such as /v3/).
This status code is returned when the Identity service fails to parse the request as expected. This is most frequently returned when a required attribute is missing, a disallowed attribute is specified (such as an id on POST in a basic CRUD operation), or an attribute is provided of an unexpected data type.
The client is assumed to be in error.
This status code is returned when the request is successfully authenticated but not authorized to perform the requested action.
This status code is returned in response to failed GET, HEAD, POST, PUT, PATCH and DELETE operations when a referenced entity cannot be found by ID. In the case of a POST request, the referenced entity may be in the request body as opposed to the resource path.
This status code is returned in response to failed POST and PATCH operations. For example, when a client attempts to update an entity’s unique attribute which conflicts with that of another entity in the same collection.
Alternatively, a client should expect this status code when attempting to perform the same create operation twice in a row on a collection with a user-defined and unique attribute. For example, a User’s name attribute is defined to be unique and user-defined, so making the same POST /users request twice in a row will result in this status code.
The client is assumed to be in error.
This status code is returned when an unexpected error has occurred in the Identity service implementation.
This status code is returned when the Identity service implementation is unable to fulfill the request because it is incapable of implementing the entire API as specified.
For example, an Identity service may be incapable of returning an exhaustive collection of Projects with any reasonable expectation of performance, or lack the necessary permission to create or modify the collection of users (which may be managed by a remote system); the implementation may therefore choose to return this status code to communicate this condition to the client.
User entities represent individual API consumers and are owned by a specific domain.
Role grants explicitly associate users with projects or domains. Each user-project or user-domain pair can have a unique set of roles granted on them.
A user without any role grants is effectively useless from the perspective of an OpenStack service and should never have access to any resources. It is allowed, however, as a means of acquiring or loading users from external sources prior to mapping them to projects.
Additional required attributes:
name (string)
Unique user name, within the owning domain.
Optional attributes:
domain_id (string)
References the domain which owns the user; if a domain is not specified by the client, the Identity service implementation will default it to the domain to which the client’s token is scoped.
default_project_id (string)
References the user’s default project against which to authorize, if the API user does not explicitly specify one when creating a token. Setting this attribute does not grant any actual authorization on the project, and is merely provided for the user’s convenience. Therefore, the referenced project does not need to exist within the user’s domain.
New in version 3.1 If the user does not have authorization to their default project, the default project will be ignored at token creation.
description (string)
enabled (boolean)
Setting this value to false prevents the user from authenticating or receiving authorization. Additionally, all pre-existing tokens held by the user are immediately invalidated. Re-enabling a user does not re-enable pre-existing tokens.
password (string)
The default form of credential used during authentication.
Example entity:
{
"user": {
"default_project_id": "263fd9",
"domain_id": "1789d1",
"enabled": true,
"id": "0ca8f6",
"links": {
"self": "http://identity:35357/v3/users/0ca8f6"
},
"name": "Joe",
"password_expires_at": "2016-11-06T15:32:17.000000"
}
}
Note: password_expires_at is new a response only attribute; is not a valid request attribute. A null value means that the password never expires.
Group entities represent a collection of Users and are owned by a specific domain. As with individual users, role grants explicitly associate groups with projects or domains. A group role grant onto a project/domain is the equivalent of granting each individual member of the group the role on that project/domain. Once a group role grant has been made, the addition or removal of a user to such a group will result in the automatic granting/revoking of that role to the user, which will also cause any token containing that user and project/domain to be revoked.
As with users, a group entity without any role grants is effectively useless from the perspective an OpenStack service and should never have access to any resources. It is allowed, however, as a means of acquiring or loading users/groups from external sources prior to mapping them to projects/domains.
Additional required attributes:
name (string)
Unique group name, within the owning domain.
Optional attributes:
domain_id (string)
References the domain which owns the group; if a domain is not specified by the client, the Identity service implementation will default it to the domain to which the client’s token is scoped.
description (string)
Example entity:
{
"group": {
"description": "Developers cleared for work on all general projects"
"domain_id": "1789d1",
"id": "70febc",
"links": {
"self": "http://identity:35357/v3/groups/70febc"
},
"name": "Developers"
}
}
Credentials represent arbitrary authentication credentials associated with a user. A user may have zero or more credentials, each optionally scoped to a specific project.
Additional required attributes:
user_id (string)
References the user which owns the credential.
type (string)
Representing the credential type, such as ec2 or cert. A specific implementation may determine the list of supported types.
blob (blob)
Arbitrary blob of the credential data, to be parsed according to the type.
Optional attributes:
project_id (string)
References a project which limits the scope the credential applies to. This attribute is mandatory if the credential type is ec2.
Example entity:
{
"credential": {
"blob": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
"id": "80239a",
"links": {
"self": "http://identity:35357/v3/credentials/80239a"
},
"project_id": "263fd9",
"type": "ec2",
"user_id": "0ca8f6"
}
}
Projects represent the base unit of “ownership” in OpenStack, in that all resources in OpenStack should be owned by a specific project (“projects” were also formerly known as “tenants”). A project itself must be owned by a specific domain.
New in version 3.6, projects may, in addition to acting as containers for OpenStack resources, act as a domain (by setting the attribute is_domain to true), in which case it provides a namespace in which users, groups and other projects can be created. In fact, a domain created using the POST /domains API will actually be represented as a project with is_domain set to true with no parent (parent_id is null). Projects that are acting as a domain created via the POST /projects API must also be specified with no parent (i.e. if parent_id is included it must be null). Issuing a create project request for a project acting as a domain with a parent_id that is not null will cause an HTTP 400 Bad Request to be returned.
Given this, all projects are considered part of a project hierarchy. Projects created in a domain prior to version 3.6 are represented as a two-level hierarchy, with a project that has is_domain set to true as the root and all other projects referencing the root as their parent.
A project acting as a domain can potentially also act as a container for OpenStack resources, although this depends on whether the policy rule for the relevant resource creation allows this.
Required attributes:
name (string)
Unique project name, within the owning domain. A project name for a project acting as a domain must be unique across all domains.
Optional attributes:
is_domain (boolean) New in version 3.6
Represents if the project is acting as a domain. If this flag is set to true, the project also acts as a domain, providing a namespace in which users, groups and other projects can be created. If the flag is set to false, then this is a regular project, which can only contain resources. If not provided on project creation, is_domain defaults to false. This flag is immutable and can’t be updated after the project is created.
parent_id (string) New in version 3.4
References the parent project. If specified on project creation, this places the project within a hierarchy and implicitly defines the owning domain, which will be the closest ancestor in the hierarchy acting as a domain. If a parent project is not specified and is_domain is false, then the project will use its owning domain as its parent. If a parent project is not specified and is_domain is true, then the project is acting as a top level domain with no parents and parent_id will be set to null. parent_id is immutable, and can’t be updated after the project is created - hence a project cannot be moved within the hierarchy.
domain_id (string)
References the domain which owns the project. For projects not acting as a domain, this will be the closest ancestor in the hierarchy to be acting as a domain. Projects acting as a domain have no ancestors, and the domain_id will be set to null. On project creation, if neither domain_id or parent_id is specified by the client, the Identity service implementation will default to the domain to which the client’s token is scoped. If one or other of domain_id and parent_id is specified, then this will define the domain of the project. If both domain_id and parent_id are specified, and they do not indicate the same domain, an HTTP 400 Bad Request will be returned.
description (string)
enabled (boolean)
Setting this attribute to false prevents users from authorizing against this project. Additionally, all pre-existing tokens authorized for the project are immediately invalidated. Re-enabling a project does not re-enable pre-existing tokens.
Example entity of a project acting as a domain:
{
"project": {
"domain_id": null,
"enabled": true,
"id": "1789d1",
"links": {
"self": "http://identity:35357/v3/projects/1789d1"
},
"name": "development",
"parent_id": null,
"is_domain": true
}
}
A project that is not acting as a domain, but is a top level project, will have both the parent_id and domain_id referencing the project acting as a domain, for example:
{
"project": {
"domain_id": "1789d1",
"enabled": true,
"id": "263fd9",
"links": {
"self": "http://identity:35357/v3/projects/263fd9"
},
"name": "project-x",
"parent_id": "1789d1",
"is_domain": false
}
}
A project that is the child of the above project, will have the same domain_id as its parent, and a parent_id that references its parent, for example:
{
"project": {
"domain_id": "1789d1",
"enabled": true,
"id": "63abc1",
"links": {
"self": "http://identity:35357/v3/projects/63abc1"
},
"name": "project-y",
"parent_id": "263fd9",
"is_domain": false
}
}
Domains represent collections of users, groups and projects. Each is owned by exactly one domain. Users, however, can be associated with multiple projects by granting roles to the user on a project (including projects owned by other domains).
Starting with version 3.6, domains created using the POST /domains API will actually be represented as a project with is_domain set to true with no parent.
Each domain defines a namespace in which certain API-visible name attributes exist, which affects whether those names need to be globally unique or simply unique within that domain. Within the Identity API, there are five such name attributes:
Additional required attributes:
name (string)
Globally unique name.
Optional attributes:
description (string)
enabled (boolean)
Setting this attribute to false prevents users from authorizing against this domain or any projects owned by this domain, and prevents users owned by this domain from authenticating or receiving any other authorization. Additionally, all pre-existing tokens applicable to the above entities are immediately invalidated. Re-enabling a domain does not re-enable pre-existing tokens.
Example entity:
{
"domain": {
"enabled": true,
"id": "1789d1",
"links": {
"self": "http://identity:35357/v3/domains/1789d1"
},
"name": "example.com"
}
}
Roles entities are named identifiers used to map a collection of actions from a user to either a specific project or across an entire domain.
New in version 3.6 A role can be a global policy role (i.e. it will appear in a policy file in one of the services) or a domain specific role. A domain specific role can be used to build role inference rules that better model the sets of policy roles that need to be assigned for users or groups of a particular domain. Domain specific roles never actually appear in policy files, they are expanded into their implied global policy roles at token generation/validation time.
Additional required attributes:
name (string)
Globally (or domain-wide) unique name of the role.
Optional attributes:
domain_id (string) New in version 3.6
This attribute is immutable.
Example entity:
{
"role": {
"domain_id": null,
"id": "76e72a",
"links": {
"self": "http://identity:35357/v3/roles/76e72a"
},
"name": "admin"
}
}
New in version 3.2
Region entities represent a general division of an OpenStack deployment. A region may have zero or more sub-regions associated with it, making a tree-like structured hierarchy possible for the OpenStack deployment.
It is important to note that the concept of a Region has no geographical connotation to it. Deployers are free to use geographical names for their regions, for example “us-east”, but there is no requirement to do so.
Optional attributes:
description (string)
Freeform description field for the deployer to use as they choose to describe the region.
parent_region_id (string)
If the region is hierarchically a child of another region, this field shall be set to the id of the parent region.
Example entity:
{
"region": {
"description": "2nd sub-region inside the US East region.",
"id": "us-east-2",
"links": {
"self": "https://identity:35357/v3/regions/us-east-2"
},
"parent_region_id": "us-east"
}
}
Service entities represent web services in the OpenStack deployment. A service may have zero or more endpoints associated with it, although a service with zero endpoints is essentially useless in an OpenStack configuration.
Additional required attributes:
type (string)
Describes the API implemented by the service. The following values are recognized within the OpenStack ecosystem: compute, image, ec2, identity, volume, network. To support non-core and future projects, the value should not be validated against this list.
Optional attributes:
description (string)
User-facing description of the service.
enabled (boolean)
Setting this value to false prevents the service and its endpoints from appearing in the service catalog.
name (string)
User-facing name of the service.
Example entity:
{
"service": {
"enabled": true,
"id": "ee057c",
"links": {
"self": "http://identity:35357/v3/services/ee057c"
},
"name": "Keystone",
"type": "identity"
}
}
Endpoint entities represent URL endpoints for OpenStack web services.
Additional required attributes:
service_id (string)
References the service to which the endpoint belongs.
interface (string)
Describes the visibility of the endpoint according to one of the following values:
url (string)
Fully qualified URL of the service endpoint.
Optional attributes:
region (string)
Deprecated in v3.2. Use region_id
Represents the geographic location of the service endpoint, if relevant to the deployment. The value of this attribute is intended to be implementation specific in meaning.
region_id (string)
Represents the containing region of the service endpoint. New in v3.2
enabled (boolean)
Setting this value to false prevents the endpoint from appearing in the service catalog.
Example entity:
{
"endpoint": {
"enabled": true,
"id": "6fedc0",
"interface": "internal",
"links": {
"self": "http://identity:35357/v3/endpoints/6fedc0"
},
"region_id": "us-east-2",
"service_id": "ee057c",
"url": "http://identity:35357/"
}
}
Tokens represent an authenticated user’s identity and, potentially, explicit authorization on a specific project or domain.
Tokens are generated by the Identity service via authentication, and may be subsequently validated and/or revoked.
Unlike all other resources in the Identity API, token objects returned by the API do not have id attributes. While token objects do have identifiers, they are not passed in resource URL’s nor are they included in the objects themselves. Instead, they are passed in the X-Auth-Token and X-Subject-Token headers, along with a Vary: X-Auth-Token, X-Subject-Token header to inform caches of this pattern.
token objects are only created by the identity service implementation; clients are not expected to create them. Instead, clients provide the service with auth objects in exchange for token objects.
Required attributes:
expires_at (string, ISO 8601 extended format date time with microseconds)
Specifies the expiration time of the token. Once established, a token’s expiration may not be changed. A token may be revoked ahead of expiration. If the value represents a time in the past, the token is invalid.
issued_at (string, ISO 8601 extended format date time with microseconds)
Specifies the time at which the token was issued.
user (object)
References the user to which the token belongs.
Includes the full resource description of a user.
methods (list)
The methods attribute indicates the accumulated set of authentication methods used to obtain the token. For example, if the token was obtained by password authentication, it will contain password. Later, if the token is exchanged using the token authentication method one or more times, the subsequently created tokens will contain both password and token in their methods attribute.
Notice the difference between methods and multifactor authentication. The methods attribute merely indicates the methods used to authenticate the user for the given token. It is up to the client to look for specific methods to determine the total number of factors.
audit_ids (array)
The audit_ids attribute is a list that contains no more than two elements. Each id in the audit_ids attribute is a randomly (unique) generated string that can be used to track the token.
Each token will have its own unique audit identifier as the first element of the array. In the case of a token that was rescoped (exchanged for another token of the same or different scope), there will be a second audit identifier as the second element of the array. This conditional second identifier is the audit id string from the original token (i.e. the first token issued that was not a rescoped token).
These audit identifiers can be used to track a specific use of token (or chain of tokens) across multiple requests and endpoints without exposing the token id to non-privileged users (e.g. via logs).
Each audit identifier is a short urlsafe string.
Example token with audit_ids attribute (first element is the token’s audit_id, second is the audit_chain_id):
{
"token": {
"audit_ids": ["VcxU2JYqT8OzfUVvrjEITQ", "qNUTIJntTzO1-XUk5STybw"],
"expires_at": "2013-02-27T18:30:59.999999Z",
"issued_at": "2013-02-27T16:30:59.999999Z",
"methods": [
"password"
],
"user": {
"domain": {
"id": "1789d1",
"name": "example.com"
}
"id": "0ca8f6",
"name": "Joe",
"password_expires_at": "2016-11-06T15:32:17.000000"
}
}
}
Tokens issued prior to the inclusion of the audit id code will lack the audit_ids attribute. These tokens lacking audit_ids will continue to function normally until revoked or expired. All newly issue tokens will have the expected audit_ids attribute.
Optional attributes:
project (object)
Specifies the project authorization scope of the token. If this attribute is not provided, then the token is not authorized to access any project resources. The presence of this attribute conveys multi-tenancy to cloud services such that they can achieve resource isolation based on the authorized request context included in the token. This attribute must not be included if a domain attribute is included. A token with project-level authorization does not express any authorization on any domain-level resource.
Includes the full resource description of a project.
domain (object)
Specifies the domain authorization scope of the token. This is to provide authorization appropriate to domain-level APIs, for example user and group management within a domain. If this attribute is not provided, then the token is not authorized to access any domain level resources. This attribute must not be included if a project attribute is included. A token with domain-level authorization does not express any authorization on any project-level resource.
Includes the full resource description of a domain.
is_admin_project (boolean) New in version 3.6
A deployment can and should indicate that a specific project has elevated priviledges. Tokens scoped to this project, called the admin project can then be identified as being associated with this project. For deployments using this mechanism, policy rules can then check the value of this field to allow the bearer of such a token access to priviledged operations, for example those that are not project specific or are deployment-wide.
Example project scoped token with is_admin_project attribute:
{
"token": {
"audit_ids": ["VcxU2JYqT8OzfUVvrjEITQ", "qNUTIJntTzO1-XUk5STybw"],
"expires_at": "2023-02-27T18:30:59.999999Z",
"is_admin_project": true
"is_domain": false,
"issued_at": "2023-02-27T16:30:59.999999Z",
"methods": [
"password"
],
"project": {
"domain": {
"id": "b3652a",
"name": "domain_name1"
},
"id": "78eed8",
"name": "project_name1"
},
"roles": [
{
"id": "76e72a",
"name": "admin"
}
],
"user": {
"domain": {
"id": "1789d1",
"name": "example.com"
}
"id": "0ca8f6",
"name": "Joe",
"password_expires_at": "2016-11-06T15:32:17.000000"
}
}
}
catalog (list of object)
Specifies all the services available to/for the token. It is represented as a list of service dictionaries with the following format:
[
{
"id": "--service-id--",
"type": "--service-type--",
"name": "--service-name--",
"endpoints": [
{
"id": "--endpoint-id--",
"interface": "--interface-name--",
"region": "--region-name--",
"url": "--endpoint-url--"
},
...
]
},
...
]
Required attributes for the service object are:
Optional attributes for the service object are:
Required attributes for the endpoint object are:
Optional attributes for the endpoint object are:
region: The geographic location of the service endpoint.
bind (object) New in version 3.1
Token binding refers to the practice of embedding information from external authentication providers (like a company’s Kerberos server) inside the token such that a client may validate that the token is used in conjunction with that authentication mechanism. By coupling this authentication we can prevent re-use of a stolen token as an attacker would not have access to the external authentication.
Specifies one or more external authorization mechanisms that can be used in conjunction with the token for it to be validated by a bind enforcing client. For example a token may only be used over a Kerberos authenticated connection or with a specific client certificate.
Includes one or more mechanism identifiers with protocol specific data. The officially supported mechanisms are kerberos and x509 where:
The kerberos bind payload is of the form:
"kerberos": {
"principal": "USER@REALM"
}
... where the user’s Kerberos principal is “USER@REALM”.
The x509 bind payload is of the form:
"x509": {
"fingerprint": "0123456789ABCDEF",
"algorithm": "sha1"
}
The fingerprint is the hash of the client certificate to be validated in the specified algorithm. It should be the hex form without separating spaces or colons. The only supported algorithm is currently sha1.
Example entity:
{
"token": {
"audit_ids": [
"VcxU2JYqT8OzfUVvrjEITQ",
"qNUTIJntTzO1-XUk5STybw"
],
"bind": {
"kerberos": {
"principal": "USER@REALM"
}
},
"expires_at": "2013-02-27T18:30:59.999999Z",
"issued_at": "2013-02-27T16:30:59.999999Z",
"methods": [
"password"
],
"user": {
"domain": {
"id": "1789d1",
"name": "example.com"
},
"id": "0ca8f6",
"name": "Joe",
"password_expires_at": "2016-11-06T15:32:17.000000"
}
}
}
Policies represent arbitrarily serialized policy engine rule sets to be consumed by remote services.
Additional required attributes:
blob (string)
The policy rule set itself, as a serialized blob.
type (string)
The MIME Media Type of the serialized policy blob.
Example entity:
{
"policy": {
"blob": "{\"default\": false}",
"id": "c41a4c",
"links": {
"self": "http://identity:35357/v3/policies/c41a4c"
},
"type": "application/json"
}
}
New in version 3.3
The Identity API supports JSON Home for resource and extension discovery. The identity server will return a JSON Home document on a GET /v3 request where the Accept header indicates that the response should be application/json-home. The JSON Home document contains a mapping of “relationships” to the relative path or path template to the actual resource.
The JSON Home document includes not only the core APIs that are supported for that version of the identity API, but also the resources for the extensions.
Each of the resources in the Core API below specify the “relationship” for the resource. A client application can look up the resource path or path template for a resource by looking for that resource in the JSON Home document.
New in version 3.4
By default all core resources defined by the v3 API should be considered as stable and current. However, the JSON Home response document will indicate any variance to this in the status property of the hints property of a given resource.
Example resource response:
{
"resources": {
"http://docs.openstack.org/api/openstack-identity/3/rel/domain_config" : {
"href-template": "/domains/{domain_id}/config",
"href-vars": {
"domain_id": "http://docs.openstack.org/api/openstack-identity/3/param/domain_id"
},
"hints": {
"status": "experimental"
}
}
}
}
Supported values of status are deprecated, experimental and stable (which is the default). These values have the following meanings:
GET /v3/
The attributes in the version object are as follows:
Response:
Status: 200 OK
{
"version": {
"id": "v3.7",
"links": [
{
"href": "http://identity:35357/v3/",
"rel": "self"
}
],
"max_version": "3.7",
"min_version": "3.6",
"status": "stable",
"updated": "2013-03-06T00:00:00Z"
}
}
New in version 3.3: GET /v3/ will return a JSON Home response if the Accept header indicates that the client wants an application/json-home response. Note that the client must check the Content-Type in the response because older servers will return a normal JSON response rather than the JSON Home response. See the JSON Home spec for a description of the JSON Home document format.
The JSON Home document returned includes all the core components and also the resources for the enabled extensions. Resources for disabled extensions aren’t included.
Request:
GET /v3
Accept: application/json-home
Response:
{
"resources": {
"http://docs.openstack.org/api/openstack-identity/3/rel/auth_tokens": {
"href": "/auth/tokens"
}
}
}
Use cases:
POST /auth/tokens
Relationship: http://docs.openstack.org/api/openstack-identity/3/rel/auth_tokens
Each request to create a token contains an attribute with identity information and, optionally, a scope describing the authorization scope being requested. Example request structure:
{
"auth": {
"identity": { ... },
"scope": { ... }
}
}
Authentication is performed by specifying a list of authentication methods, each with a corresponding object, containing any attributes required by the authentication method. Example request structure for three arbitrary authentication methods:
{
"auth": {
"identity": {
"methods": ["x", "y", "z"],
"x": { ... },
"y": { ... },
"z": { ... }
}
}
}
To authenticate by password, the user must be uniquely identified in addition to providing a password attribute.
The user may be identified by either id or name. A user’s id is sufficient to uniquely identify the user. Example request:
{
"auth": {
"identity": {
"methods": [
"password"
],
"password": {
"user": {
"id": "0ca8f6",
"password": "secretsecret"
}
}
}
}
}
If the user is specified by name, then the domain of the user must also be specified in order to uniquely identify the user. Example request:
{
"auth": {
"identity": {
"methods": [
"password"
],
"password": {
"user": {
"domain": {
"id": "1789d1"
},
"name": "Joe",
"password": "secretsecret"
}
}
}
}
}
Alternatively, a domain name may be used to uniquely identify the user. Example request:
{
"auth": {
"identity": {
"methods": [
"password"
],
"password": {
"user": {
"domain": {
"name": "example.com"
},
"name": "Joe",
"password": "secretsecret"
}
}
}
}
}
If the authenticating user is already in possession of a valid token, then that token is sufficient to identity the user. This method is typically used in combination with request to change authorization scope.
{
"auth": {
"identity": {
"methods": [
"token"
],
"token": {
"id": "e80b74"
}
}
}
}
An authorization scope, including either a project, domain, or unscoped, can be optionally specified as part of the request. If both a domain and a project are specified, an HTTP 400 Bad Request will be returned, as a token cannot be simultaneously scoped to both a project and domain.
A project may be specified by either id or name. An id is sufficient to uniquely identify a project. The contents of the identity section are orthogonal to the scope as it contains identity attributes for authenticating the user, and nothing to do with authorization. Example request:
{
"auth": {
"identity": {
...
},
"scope": {
"project": {
"id": "263fd9"
}
}
}
}
If a project is specified by name, then the domain of the project must also be specified in order to uniquely identify the project.
Example request:
{
"auth": {
"identity": {
...
},
"scope": {
"project": {
"domain": {
"id": "1789d1"
},
"name": "project-x"
}
}
}
}
Alternatively, a domain name may be used to uniquely identify the project. Example request:
{
"auth": {
"identity": {
...
},
"scope": {
"project": {
"domain": {
"name": "example.com"
},
"name": "project-x"
}
}
}
}
A domain scope may be specified by either the domain’s id or name with equivalent results. Example request specifying a domain by id:
{
"auth": {
"identity": {
...
},
"scope": {
"domain": {
"id": "1789d1"
}
}
}
}
Example request specifying a domain by name:
{
"auth": {
"identity": {
...
},
"scope": {
"domain": {
"name": "example.com"
}
}
}
}
The catalog returned for a domain-scoped request can contain different services and endpoints from a project ID depending on the deployment.
A token request may, or may not, contain scope. If an unscoped token request contains scope and it is set to unscoped, it is considered an explicit unscoped token request. Which will return an unscoped response without any authorization.
{
"auth": {
"identity": {
...
},
"scope": "unscoped"
}
}
A request that does not explicitly set scope to unscoped may return a project-scoped token if the user making the request has a role assigned to its default project. Thus, it is recommended to set the authorization scope to unscoped if the intent is to receive an unscoped token. The following request body would return a project-scoped response, if user 0ca8f6 had a role assignment on their default project.
{
"auth": {
"identity": {
...
}
}
}
If there is no default project defined, or the user’s default project has been disabled or deleted, an unscoped token will be issued. Which is the same behavior as asking for an explicit unscoped token.
New in version 3.1 Additionally, if the user’s default project is invalid, a token will be issued without an explicit scope of authorization.
New in version 3.4 A user may explicitly request an unscoped token by setting the “scope” value of the token request to the string “unscoped.” This will behave the same as a token request with no scope, where the user has no default project defined.
POST /v3/auth/tokens?nocatalog
Relationship: http://docs.openstack.org/api/openstack-identity/3/rel/auth_tokens
New in version 3.1 If the caller specifies a nocatalog query parameter in the authentication request, then the authentication response will not contain the service catalog. The service catalog will otherwise be included in the response by default.
A response without an explicit authorization scope does not contain a catalog, project, domain or roles but can be used to uniquely identify the user. Example response:
Headers:
X-Subject-Token: e80b74
{
"token": {
"audit_ids": ["VcxU2JYqT8OzfUVvrjEITQ", "qNUTIJntTzO1-XUk5STybw"],
"expires_at": "2013-02-27T18:30:59.999999Z",
"issued_at": "2013-02-27T16:30:59.999999Z",
"methods": [
"password"
],
"user": {
"domain": {
"id": "1789d1",
"name": "example.com"
},
"id": "0ca8f6",
"name": "Joe",
"password_expires_at": "2016-11-06T15:32:17.000000"
}
}
}
Notice that token ID is not part of the token data. Rather, it is conveyed in the X-Subject-Token header.
A token scoped to a project will also have a service catalog, along with the user’s roles applicable to the project.
Provided there are enabled service providers, a token will be populated with a list of such service providers, accessible in the token dictionary with the key service_providers. Additional information about service providers can be found here
New in version 3.6 Project scoped tokens return an additional boolean field called is_domain that represents whether a project acts as a domain.
Example response:
Headers: X-Subject-Token
X-Subject-Token: e80b74
{
"token": {
"audit_ids": ["VcxU2JYqT8OzfUVvrjEITQ", "qNUTIJntTzO1-XUk5STybw"],
"catalog": [
{
"endpoints": [
{
"id": "39dc322ce86c4111b4f06c2eeae0841b",
"interface": "public",
"region": "RegionOne",
"url": "http://localhost:5000"
},
{
"id": "ec642f27474842e78bf059f6c48f4e99",
"interface": "internal",
"region": "RegionOne",
"url": "http://localhost:5000"
},
{
"id": "c609fc430175452290b62a4242e8a7e8",
"interface": "admin",
"region": "RegionOne",
"url": "http://localhost:35357"
}
],
"id": "4363ae44bdf34a3981fde3b823cb9aa2",
"type": "identity",
"name": "keystone"
}
],
"expires_at": "2013-02-27T18:30:59.999999Z",
"is_domain": false,
"issued_at": "2013-02-27T16:30:59.999999Z",
"methods": [
"password"
],
"project": {
"domain": {
"id": "1789d1",
"name": "example.com"
},
"id": "263fd9",
"name": "project-x"
},
"roles": [
{
"id": "76e72a",
"name": "admin"
},
{
"id": "f4f392",
"name": "member"
}
],
"service_providers": [
{
"auth_url":"https://example.com:5000/v3/OS-FEDERATION/identity_providers/acme/protocols/saml2/auth",
"id": "sp1",
"sp_url": "https://example.com:5000/Shibboleth.sso/SAML2/ECP"
},
{
"auth_url":"https://other.example.com:5000/v3/OS-FEDERATION/identity_providers/acme/protocols/saml2/auth",
"id": "sp2",
"sp_url": "https://other.example.com:5000/Shibboleth.sso/SAML2/ECP"
}
],
"user": {
"domain": {
"id": "1789d1",
"name": "example.com"
},
"id": "0ca8f6",
"name": "Joe",
"password_expires_at": "2016-11-06T15:32:17.000000"
}
}
}
A token scoped to a domain will also have a service catalog along with the user’s roles applicable to the domain. Example response:
Headers: X-Subject-Token
X-Subject-Token: e80b74
{
"token": {
"audit_ids": ["VcxU2JYqT8OzfUVvrjEITQ", "qNUTIJntTzO1-XUk5STybw"],
"catalog": [
{
"endpoints": [
{
"id": "39dc322ce86c4111b4f06c2eeae0841b",
"interface": "public",
"region": "RegionOne",
"url": "http://localhost:5000"
},
{
"id": "ec642f27474842e78bf059f6c48f4e99",
"interface": "internal",
"region": "RegionOne",
"url": "http://localhost:5000"
},
{
"id": "c609fc430175452290b62a4242e8a7e8",
"interface": "admin",
"region": "RegionOne",
"url": "http://localhost:35357"
}
],
"id": "4363ae44bdf34a3981fde3b823cb9aa2",
"type": "identity",
"name": "keystone"
}
],
"domain": {
"id": "1789d1",
"name": "example.com"
},
"expires_at": "2013-02-27T18:30:59.999999Z",
"issued_at": "2013-02-27T16:30:59.999999Z",
"methods": [
"password"
],
"roles": [
{
"id": "76e72a",
"name": "admin"
},
{
"id": "f4f392",
"name": "member"
}
],
"user": {
"domain": {
"id": "1789d1",
"name": "example.com"
},
"id": "0ca8f6",
"name": "Joe",
"password_expires_at": "2016-11-06T15:32:17.000000"
}
}
}
Several authentication errors are possible, including HTTP 403 Forbidden and HTTP 409 Conflict, but here’s an example of an HTTP 401 Unauthorized response:
Status: 401 Not Authorized
{
"error": {
"code": 401,
"message": "The request you have made requires authentication",
"title": "Not Authorized"
}
}
Optionally, the Identity service implementation may return an authentication attribute to indicate the supported authentication methods.
Status: 401 Not Authorized
{
"error": {
"code": 401,
"identity": {
"methods": [
"password",
"token",
"challenge-response"
]
},
"message": "Need to authenticate with one or more supported methods",
"title": "Not Authorized"
}
}
For authentication processes which require multiple round trips, the Identity service implementation may return an HTTP 401 Not Authorized with additional information for the next authentication step.
For example:
Status: 401 Not Authorized
{
"error": {
"code": 401,
"identity": {
"challenge-response": {
"challenge": "What was the zip code of your birthplace?",
"session_id": "123456"
},
"methods": [
"challenge-response"
]
},
"message": "Additional authentications steps required.",
"title": "Not Authorized"
}
}
GET /auth/tokens
Relationship: http://docs.openstack.org/api/openstack-identity/3/rel/auth_tokens
To validate a token using the Identity API, pass your own token in the X-Auth-Token header, and the token to be validated in the X-Subject-Token header. The Identity service returns a service catalog in the response. Example request:
Headers:
X-Auth-Token: 1dd7e3
X-Subject-Token: c67580
No request body is required.
The Identity service will return the exact same response as when the subject token was issued by POST /auth/tokens.
GET /auth/tokens?nocatalog
Relationship: http://docs.openstack.org/api/openstack-identity/3/rel/auth_tokens
New in version 3.2
To validate a token using the Identity API without returning a service catalog in the response. The request has the same format as GET /auth/tokens.
The Identity service will return the exact same response as when the subject token was issued by POST /auth/tokens?nocatalog.
HEAD /auth/tokens
Relationship: http://docs.openstack.org/api/openstack-identity/3/rel/auth_tokens
This call is identical to GET /auth/tokens, but no response body is provided, even if an error occurs or the token is invalid.
Response:
Status: 200 OK
DELETE /auth/tokens
Relationship: http://docs.openstack.org/api/openstack-identity/3/rel/auth_tokens
This call is identical to HEAD /auth/tokens except that the X-Subject-Token token is immediately invalidated, regardless of its expires_at attribute. An additional X-Auth-Token is not required. The successful response status also differs from HEAD /auth/tokens.
Response:
Status: 204 No Content
The key use cases we need to cover:
GET /auth/catalog
Relationship: http://docs.openstack.org/api/openstack-identity/3/rel/auth_catalog
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.
Response:
Status: 200 OK
{
"catalog": [
{
"endpoints": [
{
"id": "39dc322ce86c4111b4f06c2eeae0841b",
"interface": "public",
"region": "RegionOne",
"url": "http://localhost:5000"
},
{
"id": "ec642f27474842e78bf059f6c48f4e99",
"interface": "internal",
"region": "RegionOne",
"url": "http://localhost:5000"
},
{
"id": "c609fc430175452290b62a4242e8a7e8",
"interface": "admin",
"region": "RegionOne",
"url": "http://localhost:35357"
}
],
"id": "4363ae44bdf34a3981fde3b823cb9aa2",
"type": "identity",
"name": "keystone"
}
],
"links": {
"self": "https://identity:35357/v3/catalog",
"previous": null,
"next": null
}
}
GET /auth/projects
Relationship: http://docs.openstack.org/api/openstack-identity/3/rel/auth_projects
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.
Response:
Status: 200 OK
{
"projects": [
{
"domain_id": "1789d1",
"enabled": true,
"id": "263fd9",
"links": {
"self": "https://identity:35357/v3/projects/263fd9"
},
"name": "Test Group"
},
{
"domain_id": "1789d1",
"enabled": true,
"id": "50ef01",
"links": {
"self": "https://identity:35357/v3/projects/50ef01"
},
"name": "Build Group"
}
],
"links": {
"self": "https://identity:35357/v3/auth/projects",
"previous": null,
"next": null
}
}
GET /auth/domains
Relationship: http://docs.openstack.org/api/openstack-identity/3/rel/auth_domains
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.
Response:
Status: 200 OK
{
"domains": [
{
"description": "my domain description",
"enabled": true,
"id": "1789d1",
"links": {
"self": "https://identity:35357/v3/domains/1789d1"
},
"name": "my domain"
},
{
"description": "description of my other domain",
"enabled": true,
"id": "43e8da",
"links": {
"self": "https://identity:35357/v3/domains/43e8da"
},
"name": "another domain"
}
],
"links": {
"self": "https://identity:35357/v3/auth/domains",
"previous": null,
"next": null
}
}
The key use cases we need to cover:
GET /regions
Relationship: http://docs.openstack.org/api/openstack-identity/3/rel/regions
Optional query parameters:
Response:
Status: 200 OK
{
"regions": [
{
"description": "US East Region",
"id": "us-east",
"links": {
"self": "https://identity:35357/v3/regions/us-east",
"child_regions": "https://identity:35357/v3/regions?parent_region_id=us-east"
},
"parent_region_id": "us-east-coast"
},
...
],
"links": {
"self": "https://identity:35357/v3/regions",
"previous": null,
"next": null
}
}
GET /regions/{region_id}
Relationship: http://docs.openstack.org/api/openstack-identity/3/rel/region
Response:
Status: 200 OK
{
"region": {
"description": "US Southwest Region",
"id": "us-southwest",
"links": {
"self": "https://identity:35357/v3/regions/us-southwest",
"child_regions": "http://identity:35357/v3/regions?parent_region_id=us-southwest"
},
"parent_region_id": "us-west-coast"
}
}
POST /regions
Relationship: http://docs.openstack.org/api/openstack-identity/3/rel/regions
Request:
{
"region": {
"description": "US West Subregion 1",
"parent_region_id": "829551"
}
}
Response:
Status: 201 Created
{
"region": {
"description": "US West Subregion 1",
"id": "8ebd7f",
"links": {
"self": "https://identity:35357/v3/regions/8ebd7f",
"child_regions": "https://identity:35357/v3/regions?parent_region_id=8ebd7f"
},
"parent_region_id": "829551"
}
}
PUT /regions/{user_defined_region_id}
Relationship: http://docs.openstack.org/api/openstack-identity/3/rel/region
Request:
{
"region": {
"description": "US Southwest Subregion 1",
"parent_region_id": "us-south"
}
}
Response:
Status: 201 Created
{
"region": {
"description": "US Southwest Subregion 1",
"id": "us-southwest-1",
"links": {
"self": "https://identity:35357/v3/regions/us-southwest-1",
"child_regions": "https://identity:35357/v3/regions?parent_region_id=us-southwest-1"
},
"parent_region_id": "us-south"
}
}
PATCH /regions/{region_id}
Relationship: http://docs.openstack.org/api/openstack-identity/3/rel/region
Request:
{
"region": {
"description": "US Southwest Subregion",
"parent_region_id": "us-southwest"
}
}
Response:
Status: 200 OK
{
"region": {
"description": "US Southwest Subregion",
"id": "us-southwest-1",
"links": {
"self": "https://identity:35357/v3/regions/us-southwest-1",
"child_regions": "https://identity:35357/v3/regions?parent_region_id=us-southwest-1"
},
"parent_region_id": "us-southwest"
}
}
DELETE /regions/{region_id}
Relationship: http://docs.openstack.org/api/openstack-identity/3/rel/region
Response:
Status: 204 No Content
GET /services
Relationship: http://docs.openstack.org/api/openstack-identity/3/rel/services
Optional query parameters:
name (string)
New in version 3.3
type (string)
Response:
Status: 200 OK
{
"services": [
{
"description": "OpenStack Volume Service",
"id": "ee057c",
"links": {
"self": "https://identity:35357/v3/services/ee057c"
},
"name": "Cinder",
"type": "volume"
},
{
"description": "OpenStack Identity Service",
"id": "5e70df",
"links": {
"self": "https://identity:35357/v3/services/5e70df"
},
"name": "Keystone",
"type": "identity"
}
],
"links": {
"self": "https://identity:35357/v3/services",
"previous": null,
"next": null
}
}
GET /services/{service_id}
Relationship: http://docs.openstack.org/api/openstack-identity/3/rel/service
Response:
Status: 200 OK
{
"service": {
"description": "OpenStack Volume Service",
"id": "ee057c",
"links": {
"self": "https://identity:35357/v3/services/ee057c"
},
"name": "Cinder",
"type": "volume"
}
}
POST /services
Relationship: http://docs.openstack.org/api/openstack-identity/3/rel/services
Request:
{
"service": {
"description": "OpenStack Compute Service",
"name": "Nova",
"type": "compute"
}
}
Response:
Status: 201 Created
{
"service": {
"description": "OpenStack Compute Service",
"id": "520ec2",
"links": {
"self": "https://identity:35357/v3/services/520ec2"
},
"name": "Nova",
"type": "compute"
}
}
PATCH /services/{service_id}
Relationship: http://docs.openstack.org/api/openstack-identity/3/rel/service
The request block is the same as the one for create service, except that only the attributes that are being updated need to be included.
Response:
Status: 200 OK
{
"service": {
"description": "OpenStack Image Service",
"id": "520ec2",
"links": {
"self": "https://identity:35357/v3/services/520ec2"
},
"name": "Glance",
"type": "image"
}
}
DELETE /services/{service_id}
Relationship: http://docs.openstack.org/api/openstack-identity/3/rel/service
Response:
Status: 204 No Content
GET /endpoints
Relationship: http://docs.openstack.org/api/openstack-identity/3/rel/endpoints
Optional query parameters:
Response:
Status: 200 OK
{
"endpoints": [
{
"enabled": true,
"id": "6fedc0",
"interface": "public",
"links": {
"self": "https://identity:35357/v3/endpoints/6fedc0"
},
"region_id": "us-east-1",
"service_id": "ee057c",
"url": "https://service.example.com:5000/"
},
{
"enabled": true,
"id": "d12b15",
"interface": "admin",
"links": {
"self": "https://identity:35357/v3/endpoints/d12b15"
},
"region_id": "us-east-2",
"service_id": "8ef7de",
"url": "https://service.example.com:35357/"
}
],
"links": {
"self": "https://identity:35357/v3/endpoints",
"previous": null,
"next": null
}
}
GET /endpoints/{endpoint_id}
Relationship: http://docs.openstack.org/api/openstack-identity/3/rel/endpoint
Response:
Status: 200 OK
{
"endpoint": {
"enabled": true,
"id": "6fedc0",
"interface": "public",
"links": {
"self": "https://identity:35357/v3/endpoints/6fedc0"
},
"region_id": "us-east-2",
"service_id": "ee057c",
"url": "https://service.example.com:5000/"
}
}
POST /endpoints
Relationship: http://docs.openstack.org/api/openstack-identity/3/rel/endpoints
Request:
{
"endpoint": {
"interface": "admin",
"region_id": "us-east-2",
"url": "https://service.example.com/",
"service_id": "ee057c"
}
}
Response:
Status: 200 OK
{
"endpoint": {
"enabled": true,
"id": "6fedc0",
"interface": "admin",
"links": {
"self": "https://identity:35357/v3/endpoints/6fedc0"
},
"region_id": "us-east-2",
"service_id": "ee057c",
"url": "https://service.example.com:35357/"
}
}
PATCH /endpoints/{endpoint_id}
Relationship: http://docs.openstack.org/api/openstack-identity/3/rel/endpoint
The request block is the same as the one for create endpoint, except that only the attributes that are being updated need to be included.
Response:
Status: 200 OK
{
"endpoint": {
"enabled": true,
"id": "6fedc0",
"interface": "public",
"links": {
"self": "https://identity:35357/v3/endpoints/6fedc0"
},
"region_id": "us-east-1",
"service_id": "ee057c",
"url": "https://service.example.com:5000/"
}
}
DELETE /endpoints/{endpoint_id}
Relationship: http://docs.openstack.org/api/openstack-identity/3/rel/endpoint
Response:
Status: 204 No Content
GET /domains
Relationship: http://docs.openstack.org/api/openstack-identity/3/rel/domains
Optional query parameters:
Response:
Status: 200 OK
{
"domains": [
{
"description": "my domain description",
"enabled": true,
"id": "1789d1",
"links": {
"self": "https://identity:35357/v3/domains/1789d1"
},
"name": "my domain"
},
{
"description": "description of my other domain",
"enabled": true,
"id": "43e8da",
"links": {
"self": "https://identity:35357/v3/domains/43e8da"
},
"name": "another domain"
}
],
"links": {
"self": "https://identity:35357/v3/domains",
"previous": null,
"next": null
}
}
GET /domains/{domain_id}
Relationship: http://docs.openstack.org/api/openstack-identity/3/rel/domain
Response:
Status: 200 OK
{
"domain": {
"description": "my domain description",
"enabled": true,
"id": "1789d1",
"links": {
"self": "https://identity:35357/v3/domains/1789d1"
},
"name": "my domain"
}
}
POST /domains
Relationship: http://docs.openstack.org/api/openstack-identity/3/rel/domains
Request:
{
"domain": {
"description": "my new domain for users",
"enabled": true,
"name": "my new domain"
}
}
Response:
Status: 201 Created
{
"domain": {
"description": "my new domain for users",
"enabled": true,
"id": "89b3e2",
"links": {
"self": "https://identity:35357/v3/domains/89b3e2"
},
"name": "my new domain"
}
}
PATCH /domains/{domain_id}
Relationship: http://docs.openstack.org/api/openstack-identity/3/rel/domain
The request block is the same as the one for create domain, except that only the attributes that are being updated need to be included.
Request:
{
"domain": {
"description": "my new domain for users and tenants"
}
}
Response:
Status: 200 OK
{
"domain": {
"description": "my new domain for users and tenants",
"enabled": true,
"id": "89b3e2",
"links": {
"self": "https://identity:35357/v3/domains/89b3e2"
},
"name": "my new domain"
}
}
DELETE /domains/{domain_id}
Relationship: http://docs.openstack.org/api/openstack-identity/3/rel/domain
Deleting a domain will delete all the entities owned by it (Users, Groups, and Projects), as well as any credentials and role grants that relate to these entities.
In order to minimize the risk of an inadvertent deletion of a domain and its entities, a domain must first be disabled (using the update domain API) before a successful delete domain API call can be made. Attempting to delete an enabled domain will result in an HTTP 403 Forbidden response.
Response:
Status: 204 No Content
New in version 3.6
New in version 3.4 (experimental)
Keystone optionally supports the ability to manage domain specific configuration options via the API, allowing configuration options to be overriden for a given domain. In addition, New in version 3.6 (experimental), the default configuration options can also be retrieved.
Domain specific configuration options are structured within their group objects. Currently only the identity and ldap groups are supported, and these can be used to override the default configuration settings for the storage of users and groups by the identity server. Attempting to read or override configuration options for groups other than identity and ldap will result in an HTTP 403 Forbidden.
The default configuration settings for the options that can be overridden can be retrieved.
GET /domains/config/default
Relationship:: http://docs.openstack.org/api/openstack-identity/3/rel/domain_config_default
Response:
Status: 200 OK
{
"config": {
"identity": {
"driver": "ldap"
},
"ldap": {
"url": "ldap://localhost",
"user": "",
"suffix": "cn=example,cn=com".
....
}
}
}
It is possible to read the default configuration settings for a specific group or option.
GET /domains/config/ldap/default
Relationship:: http://docs.openstack.org/api/openstack-identity/3/rel/domain_config_default
Response:
Status: 200 OK
{
"ldap": {
"url": "ldap://localhost",
"user": "",
"suffix": "cn=example,cn=com".
....
}
}
GET /domains/config/identity/driver/default
Relationship:: http://docs.openstack.org/api/openstack-identity/3/rel/domain_config_default
Response:
Status: 200 OK
{
"driver": "ldap"
}
A similar form of URL can be used to retrieve the values of those options that have been overriden for a domain by the API.
GET /domains/{domain_id}/config
Relationship: http://docs.openstack.org/api/openstack-identity/3/rel/domain_config
Response:
Status: 200 OK
{
"config": {
"identity": {
"driver": "keystone.identity.backends.ldap.Identity"
},
"ldap": {
"url": "http://myldap/root",
"user_tree_dn": "ou=Users,dc=root,dc=org"
}
}
}
The values of a specific group that has been overridden can also be read.
GET /domains/{domain_id}/config/ldap
Relationship: http://docs.openstack.org/api/openstack-identity/3/rel/domain_config_group
Response:
Status: 200 OK
{
"ldap": {
"url": "http://myldap/root",
"user_tree_dn": "ou=Users,dc=root,dc=org"
}
}
An individual option may also be requested.
GET /domains/{domain_id}/config/ldap/url
Relationship: http://docs.openstack.org/api/openstack-identity/3/rel/domain_config_option
Response:
Status: 200 OK
{
"url": "http://myldap/root",
}
Domain specific configuration options can also be created, updated and deleted using the PUT, PATCH and DELETE HTTP commands. When updating, it is only necessary to include those options that are being updated.
PATCH /domains/{domain_id}/config
Relationship: http://docs.openstack.org/api/openstack-identity/3/rel/domain_config
Request:
{
"config": {
"ldap": {
"url": "http://myldap/my_new_root",
"user_tree_dn": "ou=Users,dc=my_new_root,dc=org"
}
}
}
Response:
Status: 200 OK
{
"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"
}
}
}
In a similar case to GET, an indiviudal option can be updated.
PATCH /domains/{domain_id}/config/ldap/url
Request:
{
"url": "http://myldap/my_other_root",
}
Response:
Status: 200 OK
{
"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"
}
}
}
In the above example, if the url option did not yet exist then an HTTP PUT command would be required.
The Keystone API will not return options that are considered sensitive, although these can be written/updated. The only option currently considered sensitive is the password option within the ldap group. To aid those situations where sensitive options are required to be included in other options that otherwise would not considered sensitive, the API supports a substitution ability for any sensitive options. For example, the password can be included as part of the url option.
PATCH /domains/{domain_id}/config/ldap/url
Request:
{
"url": "http://myldap/my_other_root/my_user/%(password)s",
}
Response:
Status: 200 OK
{
"config": {
"identity": {
"driver": "keystone.identity.backends.ldap.Identity"
},
"ldap": {
"url": "http://myldap/my_other_root/my_user/$(password)s",
"user_tree_dn": "ou=Users,dc=my_new_root,dc=org"
}
}
}
In this example, Keystone will substitute the referenced password option with its actual value when using the url to talk to the LDAP server. A sensitive option that is referenced in this way must be in the same option group as the referring option.
GET /projects
Relationship: http://docs.openstack.org/api/openstack-identity/3/rel/projects
Optional query parameters:
domain_id (string)
enabled (key-only, no value expected)
is_domain (boolean, defaults to false) New in version 3.6
If this is not specified, then only projects that are not acting as a domain will be included in the collection. If it is specified as true, then only projects acting as a domain are included.
name (string)
parent_id (string) New in version 3.4
Response:
Status: 200 OK
{
"projects": [
{
"domain_id": "1789d1",
"enabled": true,
"id": "263fd9",
"links": {
"self": "https://identity:35357/v3/projects/263fd9"
},
"name": "Dev Group A",
"parent_id": null
},
{
"domain_id": "1789d1",
"enabled": true,
"id": "e56ad3",
"links": {
"self": "https://identity:35357/v3/projects/e56ad3"
},
"name": "Dev Group B",
"parent_id": null
}
],
"links": {
"self": "https://identity:35357/v3/projects",
"previous": null,
"next": null
}
}
GET /projects/{project_id}
Relationship: http://docs.openstack.org/api/openstack-identity/3/rel/project
New in version 3.4
Response:
Status: 200 OK
{
"project": {
"domain_id": "1789d1",
"enabled": true,
"id": "263fd9",
"links": {
"self": "https://identity:35357/v3/projects/263fd9"
},
"name": "Dev Group A",
"parent_id": "183ab2"
}
}
If additional information about the project’s hierarchy is required, this API has two query parameters.
GET /projects/{project_id}?parents_as_list
The parent hierarchy will be included as a list in the response. This list will contain the projects found by traversing up the hierarchy to the top-level project.
Note
Server responses may vary depending on the level of authorization the user has against the projects in the hierarchy. The server may return an empty list if the user does not have any role assignments on the projects in the hierarchy, or only return projects that the user has role assignments on.
Response:
{
"project": {
"domain_id": "1789d1",
"enabled": true,
"id": "263fd9",
"links": {
"self": "http://identity:35357/v3/projects/263fd9"
},
"name": "Dev Group A",
"parent_id": "183ab2",
"parents": [
{
"project": {
"domain_id": "1789d1",
"enabled": true,
"id": "183ab2",
"links": {
"self": "identity:35357/v3/projects/183ab2"
},
"name": "Dev Group A Parent",
"parent_id": null
}
}
]
}
}
GET /projects/{project_id}?subtree_as_list
The child hierarchy will be included as a list in the response. This list will contain the projects found by traversing down the hierarchy.
Note
Server responses may vary depending on the level of authorization the user has against the projects in the hierarchy. The server may return an empty list if the user does not have any role assignments on the projects in the hierarchy, or only return projects that the user has role assignments on.
Response:
{
"project": {
"domain_id": "1789d1",
"enabled": true,
"id": "263fd9",
"links": {
"self": "http://identity:35357/v3/projects/263fd9"
},
"name": "Dev Group A",
"parent_id": "183ab2",
"subtree": [
{
"project": {
"domain_id": "1789d1",
"enabled": true,
"id": "9n1jhb",
"links": {
"self": "identity:35357/v3/projects/9n1jhb"
},
"name": "Dev Group A Child 1",
"parent_id": "263fd9"
}
},
{
"project": {
"domain_id": "1789d1",
"enabled": true,
"id": "4b6aa1",
"links": {
"self": "identity:35357/v3/projects/4b6aa1"
},
"name": "Dev Group A Child 2",
"parent_id": "263fd9"
}
},
{
"project": {
"domain_id": "1789d1",
"enabled": true,
"id": "b76eq8",
"links": {
"self": "identity:35357/v3/projects/b76xq8"
},
"name": "Dev Group A Grandchild",
"parent_id": "4b6aa1"
}
}
]
}
}
GET /projects/{project_id}?parents_as_ids
The entire parent hierarchy will be included as nested dictionaries in the response. It will contain all projects ids found by traversing up the hierarchy to the top-level project.
Note
The server may return ids of all projects in the hierarchy without requiring the user to have role assignments on any projects in the hierarchy.
Response:
{
"project": {
"domain_id": "1789d1",
"enabled": true,
"id": "263fd9",
"links": {
"self": "http://identity:35357/v3/projects/263fd9"
},
"name": "Dev Group A",
"parent_id": "183ab2",
"parents": {
"183ab2": {
"f53a4e": null
}
}
}
}
GET /projects/{project_id}?subtree_as_ids
The entire child hierarchy will be included as nested dictionaries in the response. It will contain all the projects ids found by traversing down the hierarchy.
Note
The server may return ids of all projects in the hierarchy without requiring the user to have role assignments on any projects in the hierarchy.
Response:
{
"project": {
"domain_id": "1789d1",
"enabled": true,
"id": "263fd9",
"links": {
"self": "http://identity:35357/v3/projects/263fd9"
},
"name": "Dev Group A",
"parent_id": "183ab2",
"subtree": {
"9n1jhb": null,
"4b6aa1": {
"b76eq8": null
}
}
}
}
Note that the subtree and parents query parameters are not mutually exclusive. The same is not true for similar query params such as parents_as_list and parents_as_ids, which can’t be included at the same time. If included, the server will fail with an HTTP 400 Bad Request error.
GET /projects/{project_id}?parents_as_list&subtree_as_list
Both the parents and subtree lists will be included in the response.
Response:
{
"project": {
"domain_id": "1789d1",
"enabled": true,
"id": "263fd9",
"links": {
"self": "http://identity:35357/v3/projects/263fd9"
},
"name": "Dev Group A",
"parent_id": "183ab2",
"parents": [
{
"project": {
"domain_id": "1789d1",
"enabled": true,
"id": "183ab2",
"links": {
"self": "identity:35357/v3/projects/183ab2"
},
"name": "Dev Group A Parent",
"parent_id": null
}
}
],
"subtree": [
{
"project": {
"domain_id": "1789d1",
"enabled": true,
"id": "9n1jhb",
"links": {
"self": "identity:35357/v3/projects/9n1jhb"
},
"name": "Dev Group A Child 1",
"parent_id": "263fd9"
}
},
{
"project": {
"domain_id": "1789d1",
"enabled": true,
"id": "4b6aa1",
"links": {
"self": "identity:35357/v3/projects/4b6aa1"
},
"name": "Dev Group A Child 2",
"parent_id": "263fd9"
}
},
{
"project": {
"domain_id": "1789d1",
"enabled": true,
"id": "b76xq8",
"links": {
"self": "identity:35357/v3/projects/b76xq8"
},
"name": "Dev Group A Grandchild",
"parent_id": "4b6aa1"
}
}
]
}
}
GET /projects/{project_id}?parents_as_ids&subtree_as_ids
Both the parents and subtree hierarchies will be included in the response.
Response:
{
"project": {
"domain_id": "1789d1",
"enabled": true,
"id": "263fd9",
"links": {
"self": "http://identity:35357/v3/projects/263fd9"
},
"name": "Dev Group A",
"parent_id": "183ab2",
"parents": {
"183ab2": {
"f53a4e": null
}
},
"subtree": {
"9n1jhb": null,
"4b6aa1": {
"b76eq8": null
}
}
}
}
POST /projects
Relationship: http://docs.openstack.org/api/openstack-identity/3/rel/projects
Request:
{
"project": {
"description": "Project space for Test Group",
"domain_id": "1789d1",
"enabled": true,
"name": "Test Group",
"parent_id": "7fa612"
}
}
Response:
Status: 201 Created
{
"project": {
"description": "Project space for Test Group",
"domain_id": "1789d1",
"enabled": true,
"id": "d52e32",
"links": {
"self": "https://identity:35357/v3/projects/d52e32"
},
"name": "Test Group",
"parent_id": "7fa612"
}
}
New in version 3.4
PATCH /projects/{project_id}
Relationship: http://docs.openstack.org/api/openstack-identity/3/rel/project
The request block is the same as the one for create project, except that only the attributes that are being updated need to be included.
Request:
{
"project": {
"description": "Project space for Build Group",
"name": "Build Group"
}
}
Response:
Status: 200 OK
{
"project": {
"description": "Project space for Build Group",
"domain_id": "1789d1",
"enabled": true,
"id": "d52e32",
"links": {
"self": "https://identity:35357/v3/projects/d52e32"
},
"name": "Build Group",
"parent_id": "7fa612"
}
}
New in version 3.4
DELETE /projects/{project_id}
Relationship: http://docs.openstack.org/api/openstack-identity/3/rel/project
Status: 204 No Content
New in version 3.4
GET /users
Relationship: http://docs.openstack.org/api/openstack-identity/3/rel/users
Optional query parameters:
Response:
Status: 200 OK
{
"users": [
{
"default_project_id": "263fd9",
"description": "Admin user",
"domain_id": "1789d1",
"enabled": true,
"id": "0ca8f6",
"links": {
"self": "https://identity:35357/v3/users/0ca8f6"
},
"name": "admin",
"password_expires_at": "2016-11-06T15:32:17.000000"
},
{
"default_project_id": "263fd9",
"description": "John Smith‘s user",
"domain_id": "1789d1",
"enabled": true,
"id": "9fe1d3",
"links": {
"self": "https://identity:35357/v3/users/9fe1d3"
},
"name": "jsmith",
"password_expires_at": null
}
],
"links": {
"self": "http://identity:35357/v3/users",
"previous": null,
"next": null
}
}
GET /users/{user_id}
Relationship: http://docs.openstack.org/api/openstack-identity/3/rel/user
Response:
Status: 200 OK
{
"user": {
"default_project_id": "263fd9",
"description": "John Smith‘s user",
"domain_id": "1789d1",
"enabled": true,
"id": "9fe1d3",
"links": {
"self": "https://identity:35357/v3/users/9fe1d3"
},
"name": "jsmith",
"password_expires_at": null
}
}
GET /users/{user_id}/projects
Relationship: http://docs.openstack.org/api/openstack-identity/3/rel/user_projects
Optional query parameters:
Response:
Status: 200 OK
{
"projects": [
{
"domain_id": "1789d1",
"enabled": true,
"id": "263fd9",
"links": {
"self": "https://identity:35357/v3/projects/263fd9"
},
"name": "Test Group"
},
{
"domain_id": "1789d1",
"enabled": true,
"id": "50ef01",
"links": {
"self": "https://identity:35357/v3/projects/50ef01"
},
"name": "Build Group"
}
],
"links": {
"self": "https://identity:35357/v3/users/9fe1d3/projects",
"previous": null,
"next": null
}
}
GET /users/{user_id}/groups
Relationship: http://docs.openstack.org/api/openstack-identity/3/rel/user_groups
Optional query parameters:
Response:
Status: 200 OK
{
"groups": [
{
"description": "Developers cleared for work on all general projects"
"domain_id": "1789d1",
"id": "ea167b",
"links": {
"self": "https://identity:35357/v3/groups/ea167b"
},
"name": "Developers"
},
{
"description": "Developers cleared for work on secret projects"
"domain_id": "1789d1",
"id": "a62db1",
"links": {
"self": "https://identity:35357/v3/groups/a62db1"
},
"name": "Secure Developers"
}
],
"links": {
"self": "http://identity:35357/v3/users/9fe1d3/groups",
"previous": null,
"next": null
}
}
POST /users
Relationship: http://docs.openstack.org/api/openstack-identity/3/rel/users
Request:
{
"user": {
"default_project_id": "263fd9",
"description": "Jim Doe‘s user",
"domain_id": "1789d1",
"enabled": true,
"name": "James Doe",
"password": "secretsecret"
}
}
Response:
Status: 201 Created
{
"user": {
"default_project_id": "263fd9",
"description": "Jim Doe‘s user",
"domain_id": "1789d1",
"enabled": true,
"id": "ff4e51",
"links": {
"self": "https://identity:35357/v3/users/ff4e51"
},
"name": "jdoe",
"password_expires_at": "2016-11-06T15:32:17.000000"
}
}
PATCH /users/{user_id}
Relationship: http://docs.openstack.org/api/openstack-identity/3/rel/user
The request block is the same as the one for create user, except that only the attributes that are being updated need to be included. Use this method attempt to update user password or enable/disable the user. This may return a HTTP 501 Not Implemented if the back-end driver does not allow for the functionality.
Response:
Status: 200 OK
{
"user": {
"default_project_id": "263fd9",
"description": "James Doe‘s user",
"domain_id": "1789d1",
"enabled": true,
"id": "ff4e51",
"links": {
"self": "https://identity:35357/v3/users/ff4e51"
},
"name": "jamesdoe",
"password_expires_at": "2016-11-06T15:32:17.000000"
}
}
DELETE /users/{user_id}
Relationship: http://docs.openstack.org/api/openstack-identity/3/rel/user
Response:
Status: 204 No Content
POST /users/{user_id}/password
Relationship: http://docs.openstack.org/api/openstack-identity/3/rel/user_change_password
Request:
{
"user": {
"password": "old_secretsecret",
"original_password": "secretsecret"
}
}
Response:
Status: 204 No Content
POST /groups
Relationship: http://docs.openstack.org/api/openstack-identity/3/rel/groups
Request:
{
"group": {
"description": "--optional--",
"domain_id": "--optional--",
"name": "..."
}
}
Response:
Status: 201 Created
{
"group": {
"description": "Developers cleared for work on secret projects",
"id": "--group-id--",
"links": {
"self": "http://identity:35357/v3/groups/--group-id--"
},
"name": "Secure Developers"
}
}
GET /groups
Relationship: http://docs.openstack.org/api/openstack-identity/3/rel/groups
Optional query parameters:
Response:
Status: 200 OK
{
"groups": [
{
"description": "Developers cleared for work on all general projects"
"domain_id": "--domain-id--",
"id": "--group-id--",
"links": {
"self": "http://identity:35357/v3/groups/--group-id--"
},
"name": "Developers"
},
{
"description": "Developers cleared for work on secret projects"
"domain_id": "--domain-id--",
"id": "--group-id--",
"links": {
"self": "http://identity:35357/v3/groups/--group-id--"
},
"name": "Secure Developers"
},
{
"description": "Testers cleared for work on all general projects"
"domain_id": "--domain-id--",
"id": "--group-id--",
"links": {
"self": "http://identity:35357/v3/groups/--group-id--"
},
"name": "Testers"
}
],
"links": {
"self": "http://identity:35357/v3/groups",
"previous": null,
"next": null
}
}
GET /groups/{group_id}
Relationship: http://docs.openstack.org/api/openstack-identity/3/rel/group
Response:
Status: 200 OK
{
"group": {
"description": "Developers cleared for work on secret projects",
"id": "--group-id--",
"links": {
"self": "http://identity:35357/v3/groups/--group-id--"
},
"name": "Secure Developers"
}
}
GET /groups/{group_id}/users
Relationship: http://docs.openstack.org/api/openstack-identity/3/rel/group_users
Optional query parameters:
Response:
Status: 200 OK
{
"users": [
{
"default_project_id": "--default-project-id--",
"description": "a user",
"domain_id": "--domain-id--",
"enabled": true,
"id": "--user-id--",
"links": {
"self": "http://identity:35357/v3/users/--user-id--"
},
"name": "admin",
"password_expires_at": "2016-11-06T15:32:17.000000"
},
{
"default_project_id": "--default-project-id--",
"description": "another user",
"domain_id": "--domain-id--",
"enabled": true,
"id": "--user-id--",
"links": {
"self": "http://identity:35357/v3/users/--user-id--"
},
"name": "someone",
"password_expires_at": "2016-11-06T15:32:17.000000"
}
],
"links": {
"self": "http://identity:35357/v3/groups/--group-id--/users",
"previous": null,
"next": null
}
}
PATCH /groups/{group_id}
Relationship: http://docs.openstack.org/api/openstack-identity/3/rel/group
The request block is the same as the one for create group, except that only the attributes that are being updated need to be included. This may return an HTTP 501 Not Implemented if the back-end driver doesn’t allow for the functionality.
Response:
Status: 200 OK
{
"group": {
"description": "Developers cleared for work on secret projects",
"id": "--group-id--",
"links": {
"self": "http://identity:35357/v3/groups/--group-id--"
},
"name": "Secure Developers"
}
}
DELETE /groups/{group_id}
Relationship: http://docs.openstack.org/api/openstack-identity/3/rel/group
Response:
Status: 204 No Content
PUT /groups/{group_id}/users/{user_id}
Relationship: http://docs.openstack.org/api/openstack-identity/3/rel/group_user
Response:
Status: 204 No Content
DELETE /groups/{group_id}/users/{user_id}
Relationship: http://docs.openstack.org/api/openstack-identity/3/rel/group_user
Response:
Status: 204 No Content
HEAD /groups/{group_id}/users/{user_id}
Relationship: http://docs.openstack.org/api/openstack-identity/3/rel/group_user
Response:
Status: 204 No Content
The key use cases we need to cover:
POST /credentials
Relationship: http://docs.openstack.org/api/openstack-identity/3/rel/credentials
This example shows creating an EC2 style credential where the credentials are a combination of access_key and secret. Other credentials (such as access_key) may be supported by simply changing the content of the key data.
Request:
{
"credential": {
"blob": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
"project_id": "0211d7",
"type": "ec2",
"user_id": "f293ba"
}
}
Response:
Status: 201 Created
{
"credential": {
"blob": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
"id": "46322a",
"links": {
"self": "https://identity:35357/v3/credentials/46322a"
},
"project_id": "0211d7",
"type": "ec2",
"user_id": "f293ba"
}
}
GET /credentials
Relationship: http://docs.openstack.org/api/openstack-identity/3/rel/credentials
Optional query parameters:
Response:
Status: 200 OK
{
"credentials": [
{
"blob": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
"id": "10b182",
"links": {
"self": "https://identity:35357/v3/credentials/10b182"
},
"project_id": "82cc2f",
"type": "ec2",
"user_id": "27a19b"
},
{
"blob": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
"id": "85d995",
"links": {
"self": "https://identity:35357/v3/credentials/85d995"
},
"project_id": "82cc2f",
"type": "ec2",
"user_id": "88770a"
}
],
"links": {
"self": "http://identity:35357/v3/credentials",
"previous": null,
"next": null
}
}
GET /credentials/{credential_id}
Relationship: http://docs.openstack.org/api/openstack-identity/3/rel/credential
Response:
Status: 200 OK
{
"credential": {
"blob": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
"id": "85d995",
"links": {
"self": "https://identity:35357/v3/credentials/85d995"
},
"project_id": "82cc2f",
"type": "ec2",
"user_id": "88770a"
}
}
PATCH /credentials/{credential_id}
Relationship: http://docs.openstack.org/api/openstack-identity/3/rel/credential
The request block is the same as the one for create credential, except that only the attributes that are being updated need to be included.
Response:
Status: 200 OK
{
"credential": {
"blob": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
"id": "85d995",
"links": {
"self": "https://identity:35357/v3/credentials/85d995"
},
"project_id": "6f20ed",
"type": "ec2",
"user_id": "2a64f5"
}
}
DELETE /credentials/{credential_id}
Relationship: http://docs.openstack.org/api/openstack-identity/3/rel/credential
Response:
Status: 204 No Content
The key use cases we need to cover:
POST /roles
Relationship: http://docs.openstack.org/api/openstack-identity/3/rel/roles
Request:
{
"role": {
"name": "..."
}
}
Response:
Status: 201 Created
{
"role": {
"domain_id": null,
"id": "--role-id--",
"links": {
"self": "http://identity:35357/v3/roles/--role-id--"
},
"name": "a role name"
}
}
To create a domain specific role, the request block and response would look like:
{
"role": {
"domain_id": "--domain-id--",
"name": "my specific domain role"
}
}
Response:
Status: 201 Created
{
"role": {
"domain_id": "--domain-id--",
"id": "--role-id--",
"links": {
"self": "http://identity:35357/v3/roles/--role-id--"
},
"name": "my specific domain role"
}
}
GET /roles
Relationship: http://docs.openstack.org/api/openstack-identity/3/rel/roles
Optional query parameters:
name (string)
domain_id (string, defaults to null) New in version 3.6
Since this defaults to null, listing roles without specifying domain_id in the query string will result in a collection containing only global roles.
Response:
Status: 200 OK
{
"roles": [
{
"domain_id": null,
"id": "--role-id--",
"links": {
"self": "http://identity:35357/v3/roles/--role-id--"
},
"name": "a role name"
},
{
"domain_id": null,
"id": "--role-id--",
"links": {
"self": "http://identity:35357/v3/roles/--role-id--"
},
"name": "a role name"
}
],
"links": {
"self": "http://identity:35357/v3/roles",
"previous": null,
"next": null
}
}
GET /roles/{role_id}
Relationship: http://docs.openstack.org/api/openstack-identity/3/rel/role
Response:
Status: 200 OK
{
"role": {
"domain_id": "--domain-id--",
"id": "--role-id--",
"links": {
"self": "http://identity:35357/v3/roles/--role-id--"
},
"name": "a domain specific role"
}
}
PATCH /roles/{role_id}
Relationship: http://docs.openstack.org/api/openstack-identity/3/rel/role
The request block is the same as the one for create role, except that only the attributes that are being updated need to be included.
Response:
Status: 200 OK
{
"role": {
"domain_id": null,
"id": "--role-id--",
"links": {
"self": "http://identity:35357/v3/roles/--role-id--"
},
"name": "a global policy role name"
}
}
Deleting a role also deletes all role inference rules where that role is either the prior or implied role.
DELETE /roles/{role_id}
Relationship: http://docs.openstack.org/api/openstack-identity/3/rel/role
Response:
Status: 204 No Content
PUT /roles/{prior_role_id}/implies/{implied_role_id}
Relationship: http://developer.openstack.org/api-ref-identity-v3.html#createRoleInference
Response:
Status: 201 Created
{
"role_inference": {
"prior_role": {
"id": "--prior-role-id--",
"links": {
"self": "http://identity:35357/v3/roles/--prior-role-id--"
},
"name": "prior role name"
},
"implies": {
"id": "--implied-role1-id--",
"links": {
"self": "http://identity:35357/v3/roles/--implied-role1-id--"
},
"name": "implied role1 name"
}
},
"links": {
"self": "http://identity:35357/v3/roles/--prior-role-id--/implies/--implied-role-id--"
}
}
GET /roles/{prior_role_id}/implies/{implied_role_id}
Relationship: http://developer.openstack.org/api-ref-identity-v3.html#getRoleInference
Response:
Status: 200 OK
{
"role_inference": {
"prior_role": {
"id": "--prior-role-id--",
"links": {
"self": "http://identity:35357/v3/roles/--prior-role-id--"
},
"name": "prior role name"
},
"implies": {
"id": "--implied-role-id--",
"links": {
"self": "http://identity:35357/v3/roles/--implied-role-id--"
},
"name": "implied role name"
}
},
"links": {
"self": "http://identity:35357/v3/roles/--prior-role-id--/implies/--implied-role-id--"
}
}
HEAD /roles/{prior_role_id}/implies/{implied_role_id}
Relationship: http://developer.openstack.org/api-ref-identity-v3.html#getRoleInference
Response:
Status: 204 No Content
DELETE /roles/{prior_role_id}/implies/{implied_role_id}
Relationship: http://developer.openstack.org/api-ref-identity-v3.html#deleteRoleInference
Response:
Status: 204 No Content
GET /roles/{prior_role_id}/implies
Relationship: http://developer.openstack.org/api-ref-identity-v3.html#getRoleInference
Response:
Status: 200 OK
{
"role_inference": {
"prior_role": {
"id": "--prior-role-id--",
"links": {
"self": "http://identity:35357/v3/roles/--prior-role-id--"
},
"name": "prior role name"
},
"implies": [
{
"id": "--implied-role1-id--",
"links": {
"self": "http://identity:35357/v3/roles/--implied-role1-id--"
},
"name": "implied role1 name"
},
{
"id": "--implied-role2-id--",
"links": {
"self": "http://identity:35357/v3/roles/--implied-role2-id--"
},
"name": "implied role2 name"
}
]
},
"links" : {
"self": "http://identity:35357/v3/roles/--prior-role-id--/implies"
}
}
GET /role_inferences/
Relationship: http://developer.openstack.org/api-ref-identity-v3.html#getRoleInference
Response:
Status: 200 OK
{
"role_inferences": [
{
"prior_role": {
"id": "--prior-role-id1--",
"links": {
"self": "http://identity:35357/v3/roles/--prior-role-id--"
}
"name": "prior role name"
},
"implies": [
{
"id": "--implied-role1-id--",
"links": {
"self": "http://identity:35357/v3/roles/--implied-role1-id--"
},
"name": "implied role1 name"
},
{
"id": "--implied-role2-id--",
"links": {
"self": "http://identity:35357/v3/roles/--implied-role2-id--"
},
"name": "implied role2 name"
}
]
},
{
"prior_role": {
"id": "--prior-role-id2--",
"links": {
"self" : "http://identity:35357/v3/roles/--prior-role-id--"
}
"name": "prior role name"
},
"implies": [
{
"id": "--implied-role3-id--",
"links": {
"self": "http://identity:35357/v3/roles/--implied-role1-id--"
},
"name": "implied role1 name"
},
{
"id": "--implied-role4-id--",
"links": {
"self": "http://identity:35357/v3/roles/--implied-role2-id--"
},
"name": "implied role2 name"
}
]
}
],
"links": {
"self": "http://identity:35357/v3/role_inferences"
}
}
PUT /domains/{domain_id}/users/{user_id}/roles/{role_id}
Relationship: http://docs.openstack.org/api/openstack-identity/3/rel/domain_user_role
Response:
Status: 204 No Content
PUT /domains/{domain_id}/groups/{group_id}/roles/{role_id}
Relationship: http://docs.openstack.org/api/openstack-identity/3/rel/domain_group_role
Response:
Status: 204 No Content
PUT /OS-INHERIT/domains/{domain_id}/users/{user_id}/roles/{role_id}/inherited_to_projects
Relationship: http://developer.openstack.org/api-ref-identity-v3.html#assignRoleToUser-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.
Response:
Status: 204 No Content
PUT /OS-INHERIT/domains/{domain_id}/groups/{group_id}/roles/{role_id}/inherited_to_projects
Relationship: http://developer.openstack.org/api-ref-identity-v3.html#assignRoleToGroup-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.
Response:
Status: 204 No Content
GET /domains/{domain_id}/users/{user_id}/roles
Relationship: http://docs.openstack.org/api/openstack-identity/3/rel/domain_user_roles
Response:
Status: 200 OK
{
"roles": [
{
"id": "--role-id--",
"links": {
"self": "http://identity:35357/v3/roles/--role-id--"
},
"name": "--role-name--",
},
{
"id": "--role-id--",
"links": {
"self": "http://identity:35357/v3/roles/--role-id--"
},
"name": "--role-name--"
}
],
"links": {
"self": "http://identity:35357/v3/domains/--domain_id--/users/--user_id--/roles",
"previous": null,
"next": null
}
}
GET /domains/{domain_id}/groups/{group_id}/roles
Relationship: http://docs.openstack.org/api/openstack-identity/3/rel/domain_group_roles
Response:
Status: 200 OK
{
"roles": [
{
"id": "--role-id--",
"links": {
"self": "http://identity:35357/v3/roles/--role-id--"
},
"name": "--role-name--",
},
{
"id": "--role-id--",
"links": {
"self": "http://identity:35357/v3/roles/--role-id--"
},
"name": "--role-name--"
}
],
"links": {
"self": "http://identity:35357/v3/domains/--domain_id--/groups/--group_id--/roles",
"previous": null,
"next": null
}
}
GET /OS-INHERIT/domains/{domain_id}/users/{user_id}/roles/inherited_to_projects
Relationship: http://developer.openstack.org/api-ref-identity-v3.html#listRolesForUser-domain
The list only contains those role assignments to the domain that were specified as being inherited to projects within that domain.
Response:
Status: 200 OK
{
"roles": [
{
"id": "--role-id--",
"links": {
"self": "http://identity:35357/v3/roles/--role-id--"
},
"name": "--role-name--",
},
{
"id": "--role-id--",
"links": {
"self": "http://identity:35357/v3/roles/--role-id--"
},
"name": "--role-name--"
}
],
"links": {
"self": "http://identity:35357/v3/OS-INHERIT/domains/--domain_id--/
users/--user_id--/roles/inherited_to_projects",
"previous": null,
"next": null
}
}
GET /OS-INHERIT/domains/{domain_id}/groups/{group_id}/roles/inherited_to_projects
Relationship: http://developer.openstack.org/api-ref-identity-v3.html#listRolesForGroup-domain
The list only contains those role assignments to the domain that were specified as being inherited to projects within that domain.
Response:
Status: 200 OK
{
"roles": [
{
"id": "--role-id--",
"links": {
"self": "http://identity:35357/v3/roles/--role-id--"
},
"name": "--role-name--",
},
{
"id": "--role-id--",
"links": {
"self": "http://identity:35357/v3/roles/--role-id--"
},
"name": "--role-name--"
}
],
"links": {
"self": "http://identity:35357/v3/OS-INHERIT/domains/--domain_id--/
groups/--group_id--/roles/inherited_to_projects",
"previous": null,
"next": null
}
}
HEAD /domains/{domain_id}/users/{user_id}/roles/{role_id}
Relationship: http://docs.openstack.org/api/openstack-identity/3/rel/domain_user_role
Response:
Status: 204 No Content
HEAD /domains/{domain_id}/groups/{group_id}/roles/{role_id}
Relationship: http://docs.openstack.org/api/openstack-identity/3/rel/domain_group_role
Response:
Status: 204 No Content
HEAD /OS-INHERIT/domains/{domain_id}/users/{user_id}/roles/{role_id}/inherited_to_projects
Relationship: http://developer.openstack.org/api-ref-identity-v3.html#checkRoleForGroup-domain
Response:
Status: 204 No Content
HEAD /OS-INHERIT/domains/{domain_id}/groups/{group_id}/roles/{role_id}/inherited_to_projects
Relationship: http://developer.openstack.org/api-ref-identity-v3.html#checkRoleForGroup-domain
Response:
Status: 204 No Content
DELETE /domains/{domain_id}/users/{user_id}/roles/{role_id}
Relationship: http://docs.openstack.org/api/openstack-identity/3/rel/domain_user_role
Response:
Status: 204 No Content
DELETE /domains/{domain_id}/groups/{group_id}/roles/{role_id}
Relationship: http://docs.openstack.org/api/openstack-identity/3/rel/domain_group_role
Response:
Status: 204 No Content
DELETE /OS-INHERIT/domains/{domain_id}/users/{user_id}/roles/{role_id}/inherited_to_projects
Relationship: http://developer.openstack.org/api-ref-identity-v3.html#revokeRoleFromUser-domain
Response:
Status: 204 No Content
DELETE /OS-INHERIT/domains/{domain_id}/groups/{group_id}/roles/{role_id}/inherited_to_projects
Relationship: http://developer.openstack.org/api-ref-identity-v3.html#revokeRoleFromGroup-domain
Response:
Status: 204 No Content
PUT /projects/{project_id}/users/{user_id}/roles/{role_id}
Relationship: http://docs.openstack.org/api/openstack-identity/3/rel/project_user_role
Response:
Status: 204 No Content
PUT /projects/{project_id}/groups/{group_id}/roles/{role_id}
Relationship: http://docs.openstack.org/api/openstack-identity/3/rel/project_group_role
Response:
Status: 204 No Content
PUT /OS-INHERIT/projects/{project_id}/users/{user_id}/roles/{role_id}/inherited_to_projects
Relationship: http://developer.openstack.org/api-ref-identity-v3.html#assignRoleToUser
The inherited role assignment is anchored to a project and applied to its subtree in the projects hierarchy (both existing and future projects).
Response:
Status: 204 No Content
PUT /OS-INHERIT/projects/{project_id}/groups/{group_id}/roles/{role_id}/inherited_to_projects
Relationship: http://developer.openstack.org/api-ref-identity-v3.html#assignRoleToGroup
The inherited role assignment is anchored to a project and applied to its subtree in the projects hierarchy (both existing and future projects).
Response:
Status: 204 No Content
GET /projects/{project_id}/users/{user_id}/roles
Relationship: http://docs.openstack.org/api/openstack-identity/3/rel/project_user_roles
Response:
Status: 200 OK
{
"roles": [
{
"id": "--role-id--",
"links": {
"self": "http://identity:35357/v3/roles/--role-id--"
},
"name": "--role-name--",
},
{
"id": "--role-id--",
"links": {
"self": "http://identity:35357/v3/roles/--role-id--"
},
"name": "--role-name--"
}
],
"links": {
"self": "http://identity:35357/v3/projects/--project_id--/users/--user_id--/roles",
"previous": null,
"next": null
}
}
GET /projects/{project_id}/groups/{group_id}/roles
Relationship: http://docs.openstack.org/api/openstack-identity/3/rel/project_group_roles
Response:
Status: 200 OK
{
"roles": [
{
"id": "--role-id--",
"links": {
"self": "http://identity:35357/v3/roles/--role-id--"
},
"name": "--role-name--",
},
{
"id": "--role-id--",
"links": {
"self": "http://identity:35357/v3/roles/--role-id--"
},
"name": "--role-name--"
}
],
"links": {
"self": "http://identity:35357/v3/projects/--project_id--/groups/--group_id--/roles",
"previous": null,
"next": null
}
}
GET /OS-INHERIT/projects/{project_id}/users/{user_id}/roles/inherited_to_projects
Relationship: http://developer.openstack.org/api-ref-identity-v3.html#listRolesForUser
The list only contains those roles assigned to this project that were specified as being inherited to its subtree.
Response:
Status: 200 OK
{
"roles": [
{
"id": "--role-id--",
"links": {
"self": "http://identity:35357/v3/roles/--role-id--"
},
"name": "--role-name--",
},
{
"id": "--role-id--",
"links": {
"self": "http://identity:35357/v3/roles/--role-id--"
},
"name": "--role-name--"
}
],
"links": {
"self": "http://identity:35357/v3/OS-INHERIT/projects/--project_id--/
users/--user_id--/roles/inherited_to_projects",
"previous": null,
"next": null
}
}
GET /OS-INHERIT/projects/{project_id)/groups/{group_id}/roles/inherited_to_projects
Relationship: http://developer.openstack.org/api-ref-identity-v3.html#listRolesForGroup
The list only contains those roles assigned to this project that were specified as being inherited to its subtree.
Response:
Status: 200 OK
{
"roles": [
{
"id": "--role-id--",
"links": {
"self": "http://identity:35357/v3/roles/--role-id--"
},
"name": "--role-name--",
},
{
"id": "--role-id--",
"links": {
"self": "http://identity:35357/v3/roles/--role-id--"
},
"name": "--role-name--"
}
],
"links": {
"self": "http://identity:35357/v3/OS-INHERIT/projects/--project_id--/
groups/--group_id--/roles/inherited_to_projects",
"previous": null,
"next": null
}
}
HEAD /projects/{project_id}/users/{user_id}/roles/{role_id}
Relationship: http://docs.openstack.org/api/openstack-identity/3/rel/project_user_role
Response:
Status: 204 No Content
HEAD /projects/{project_id}/groups/{group_id}/roles/{role_id}
Relationship: http://docs.openstack.org/api/openstack-identity/3/rel/project_group_role
Response:
Status: 204 No Content
Checks if a user has a role assignment with the inherited_to_projects flag on a project.
HEAD /OS-INHERIT/projects/{project_id)/users/{user_id}/roles/{role_id}/inherited_to_projects
Relationship: http://developer.openstack.org/api-ref-identity-v3.html#checkRoleForUser
Response:
Status: 200 OK
Checks if a group has a role assignment with the inherited_to_projects flag on a project.
HEAD /OS-INHERIT/projects/{project_id)/groups/{group_id}/roles/{role_id}/inherited_to_projects
Relationship: http://developer.openstack.org/api-ref-identity-v3.html#checkRoleForGroup
Response:
Status: 200 OK
DELETE /projects/{project_id}/users/{user_id}/roles/{role_id}
Relationship: http://docs.openstack.org/api/openstack-identity/3/rel/project_user_role
Response:
Status: 204 No Content
DELETE /projects/{project_id}/groups/{group_id}/roles/{role_id}
Relationship: http://docs.openstack.org/api/openstack-identity/3/rel/project_group_role
Response:
Status: 204 No Content
DELETE /OS-INHERIT/projects/{project_id)/users/{user_id}/roles/{role_id}/inherited_to_projects
Relationship: http://developer.openstack.org/api-ref-identity-v3.html#revokeRoleFromUser
Response:
Status: 204 No Content
DELETE /OS-INHERIT/projects/{project_id)/groups/{group_id}/roles/{role_id}/inherited_to_projects
Relationship: http://developer.openstack.org/api-ref-identity-v3.html#revokeRoleFromGroup
Response:
Status: 204 No Content
GET /role_assignments
Relationship: http://docs.openstack.org/api/openstack-identity/3/rel/role_assignments
New in version 3.1
Optional query parameters:
Get a list of role assignments.
If no query parameters are specified, then this API will return a list of all role assignments.
Response:
Status: 200 OK
{
"role_assignments": [
{
"links": {
"assignment": "http://identity:35357/v3/domains/--domain-id--/users/--user-id--/roles/--role-id--"
},
"role": {
"id": "--role-id--"
},
"scope": {
"domain": {
"id": "--domain-id--"
}
},
"user": {
"id": "--user-id--"
}
},
{
"group": {
"id": "--group-id--"
},
"links": {
"assignment": "http://identity:35357/v3/projects/--project-id--/groups/--group-id--/roles/--role-id--"
},
"role": {
"id": "--role-id--"
},
"scope": {
"project": {
"id": "--project-id--"
}
}
}
],
"links": {
"self": "http://identity:35357/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 /role_assignments?user.id={user_id} would list all role assignments involving the specified user.
GET /role_assignments?scope.project.id={project_id} would list all role assignments involving the specified project.
New in version 3.6 It is also possible to list all role assignments within a tree of projects: GET /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.
Response:
Status: 200 OK
{
"role_assignments": [
{
"links": {
"assignment": "http://identity:35357/v3/OS-INHERIT/
domains/--domain-id--/users/--user-id--/
roles/--role-id--/inherited_to_projects"
},
"role": {
"id": "--role-id--"
},
"scope": {
"domain": {
"id": "--domain-id--"
},
"OS-INHERIT:inherited_to": "projects"
},
"user": {
"id": "--user-id--"
}
},
{
"group": {
"id": "--group-id--"
},
"links": {
"assignment": "http://identity:35357/v3/projects/--project-id--/
groups/--group-id--/roles/--role-id--"
},
"role": {
"id": "--role-id--"
},
"scope": {
"project": {
"id": "--project-id--"
}
}
}
],
"links": {
"self": "http://identity:35357/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 /role_assignments?user.id={user_id}&effective would, in other words, answer the question “what can this user actually do?”.
GET /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:
Response:
Status: 200 OK
{
"role_assignments": [
{
"links": {
"assignment": "http://identity:35357/v3/domains/--domain-id--/users/--user-id--/roles/--role-id--"
},
"role": {
"id": "--role-id--"
},
"scope": {
"domain": {
"id": "--domain-id--"
}
},
"user": {
"id": "--user-id--"
}
},
{
"links": {
"assignment": "http://identity:35357/v3/projects/--project-id--/groups/--group-id--/roles/--role-id--",
"membership": "http://identity:35357/v3/groups/--group-id--/users/--user-id--"
},
"role": {
"id": "--role-id--"
},
"scope": {
"project": {
"id": "--project-id--"
}
},
"user": {
"id": "--user-id--"
}
},
{
"links": {
"assignment": "http://identity:35357/v3/OS-INHERIT/
domains/--domain-id--/users/--user-id--/
roles/--role-id--/inherited_to_projects"
},
"role": {
"id": "--role-id--"
},
"scope": {
"project": {
"id": "--project-id--"
}
},
"user": {
"id": "--user-id--"
}
}
],
"links": {
"self": "http://identity:35357/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 /role_assignments?user.id={user_id}&effective&include_names=true would return:
Response:
Status: 200 OK
{
"role_assignments": [
{
"links": {
"assignment": "http://identity:35357/v3/domains/--domain-id--/users/--user-id--/roles/--role-id--"
},
"role": {
"id": "--role-id--",
"name": "--role-name--"
},
"scope": {
"domain": {
"id": "--domain-id--",
"name": "--domain-name--"
}
},
"user": {
"domain": {
"id": "--domain-id--",
"name": "--domain-name--"
},
"id": "--user-id--",
"name": "--user-name--",
"password_expires_at": "--password-expires-at--"
}
},
{
"links": {
"assignment": "http://identity:35357/v3/projects/--project-id--/groups/--group-id--/roles/--role-id--",
"membership": "http://identity:35357/v3/groups/--group-id--/users/--user-id--"
},
"role": {
"id": "--role-id--",
"name": "--role-name--"
},
"scope": {
"project": {
"domain": {
"id": "--domain-id--",
"name": "--domain-name--"
}
"id": "--project-id--",
"name": "--project-name--"
}
},
"user": {
"domain": {
"id": "--domain-id--",
"name": "--domain-name--"
},
"id": "--user-id--",
"name": "--user-name--",
"password_expires_at": "--password-expires-at--"
}
}
],
"links": {
"self": "http://identity:35357/v3/role_assignments?effective&include_names=true",
"previous": null,
"next": null
}
}
The key use cases we need to cover:
POST /policies
Relationship: http://docs.openstack.org/api/openstack-identity/3/rel/policies
Request:
{
"blob": "--serialized-blob--",
"type": "--serialization-mime-type--"
}
Response:
Status: 201 Created
{
"policy": {
"blob": "--serialized-blob--",
"id": "--policy-id--",
"links": {
"self": "http://identity:35357/v3/policies/--policy-id--"
},
"type": "--serialization-mime-type--"
}
}
GET /policies
Relationship: http://docs.openstack.org/api/openstack-identity/3/rel/policies
Optional query parameters:
Response:
Status: 200 OK
{
"policies": [
{
"blob": "--serialized-blob--",
"id": "--policy-id--",
"links": {
"self": "http://identity:35357/v3/policies/--policy-id--"
},
"type": "--serialization-mime-type--"
},
{
"blob": "--serialized-blob--",
"id": "--policy-id--",
"links": {
"self": "http://identity:35357/v3/policies/--policy-id--"
},
"type": "--serialization-mime-type--"
}
],
"links": {
"self": "http://identity:35357/v3/policies",
"previous": null,
"next": null
}
}
GET /policies/{policy_id}
Relationship: http://docs.openstack.org/api/openstack-identity/3/rel/policy
Response:
Status: 200 OK
{
"policy": {
"blob": "--serialized-blob--",
"id": "--policy-id--",
"links": {
"self": "http://identity:35357/v3/policies/--policy-id--"
},
"type": "--serialization-mime-type--"
}
}
PATCH /policies/{policy_id}
Relationship: http://docs.openstack.org/api/openstack-identity/3/rel/policy
The request block is the same as the one for create policy, except that only the attributes that are being updated need to be included.
Response:
Status: 200 OK
{
"policy": {
"blob": "--serialized-blob--",
"id": "--policy-id--",
"links": {
"self": "http://identity:35357/v3/policies/--policy-id--"
},
"type": "--serialization-mime-type--"
}
}
DELETE /policies/{policy_id}
Relationship: http://docs.openstack.org/api/openstack-identity/3/rel/policy
Response:
Status: 204 No Content
From：OpenStack Identity API v3
标签：
原文地址：http://www.cnblogs.com/dwf07223/p/5720015.html
