Identity API v3 extensions (CURRENT)

Relationships

The entries within the operations below contain a relationship link, which appears as a valid URI, however these are actually URN (Uniform Resource Name), which are similar to GUID except it uses a URI syntax so that it is easier to be read. These links do not resolve to anything valid, but exist to show a relationship.

Identity API Extensions

This page describes these Identity API v3 extensions:

OS-ENDPOINT-POLICY API

Creates, verifies, and deletes associations between service endpoints and policies. Such associations enable an endpoint to request its policy.

To create, check, or delete an association, you reference a policy by its ID in the Identity server.

The extension supports these associations:

  • A policy and endpoint association.

  • A policy and service-type endpoint in a region association.

  • A policy and service-type endpoint association.

This order reflects policies in their most to least-specific order.

When an endpoint requests the appropriate policy for itself, the extension finds the policy by traversing the ordered sequence of methods of association. The extension shows the policy for the first association that it finds.

If the region of the endpoint has a parent, the extension examines the region associations up the region tree in ascending order. For region associations, the extension examines any parent regions in ascending order. The extension does not combine polices.

PUT
/v3/policies/{policy_id}/OS-ENDPOINT-POLICY/endpoints/{endpoint_id}

Associate policy and endpoint

Associates a policy and an endpoint.

If an association already exists between the endpoint and another policy, this call replaces that association.

Request

Parameters

Name

In

Type

Description

policy_id

path

string

The policy ID.

endpoint_id

path

string

The endpoint ID.

Response

Status Codes
Success

Code

Reason
204 - No Content

The server has fulfilled the request.
GET
/v3/policies/{policy_id}/OS-ENDPOINT-POLICY/endpoints/{endpoint_id}

Verify a policy and endpoint association

Verifies an association between a policy and an endpoint.

A HEAD version of this API is also supported.

Request

Parameters

Name

In

Type

Description

policy_id

path

string

The policy ID.

endpoint_id

path

string

The endpoint ID.

Response

Status Codes
Success

Code

Reason
204 - No Content

The server has fulfilled the request.
DELETE
/v3/policies/{policy_id}/OS-ENDPOINT-POLICY/endpoints/{endpoint_id}

Delete a policy and endpoint association

Deletes an association between a policy and an endpoint.

Request

Parameters

Name

In

Type

Description

policy_id

path

string

The policy ID.

endpoint_id

path

string

The endpoint ID.

Response

Status Codes
Success

Code

Reason
204 - No Content

The server has fulfilled the request.
PUT
/v3/policies/{policy_id}/OS-ENDPOINT-POLICY/services/{service_id}

Associate policy and service-type endpoint

Associates a policy and any endpoint of a service type.

If an association already exists between the endpoint of a service type and another policy, this call replaces that association.

Request

Parameters

Name

In

Type

Description

policy_id

path

string

The policy ID.

service_id

path

string

The service ID.

Response

Status Codes
Success

Code

Reason
204 - No Content

The server has fulfilled the request.
GET
/v3/policies/{policy_id}/OS-ENDPOINT-POLICY/services/{service_id}

Verify a policy and service-type endpoint association

Verifies an association between a policy and an endpoint of a service type.

A HEAD version of this API is also supported.

Request

Parameters

Name

In

Type

Description

policy_id

path

string

The policy ID.

service_id

path

string

The service ID.

Response

Status Codes
Success

Code

Reason
204 - No Content

The server has fulfilled the request.
DELETE
/v3/policies/{policy_id}/OS-ENDPOINT-POLICY/services/{service_id}

Delete a policy and service-type endpoint association

Deletes an association between a policy and an endpoint of a service type.

Request

Parameters

Name

In

Type

Description

policy_id

path

string

The policy ID.

service_id

path

string

The service ID.

Response

Status Codes
Success

Code

Reason
204 - No Content

The server has fulfilled the request.
GET
/v3/policies/{policy_id}/OS-ENDPOINT-POLICY/policy

Show policy for endpoint

Shows a policy for an endpoint.

The extension finds the policy by traversing the ordered sequence of methods of association. The extension shows the policy for the first association that it finds. If the region of the endpoint has a parent, the extension examines the region associations up the region tree in ascending order.

Request

Parameters

Name

In

Type

Description

policy_id

path

string

The policy ID.

Response

Parameters

Name

In

Type

Description

policy

body

object

A policy object.

type

body

string

The MIME media type of the serialized policy blob. From the perspective of the Identity API, a policy blob can be based on any technology. In OpenStack, the policy.json blob (type="application/json") is the conventional solution. However, you might want to use an alternative policy engine that uses a different policy language type. For example, type="application/xacml+xml".

blob

body

object

The policy rule itself, as a serialized blob.

links

body

object

The links for the policy resource.

id

body

string

The ID of the policy.
Status Codes
Success

Code

Reason
200 - OK

Request was successful.
Example
{
    "policy": {
        "blob": {
            "foobar_user": [
                "role:compute-user"
            ]
        },
        "id": "13c92821e4c4476a878d3aae7444f52f",
        "links": {
            "self": "http://example.com/identity/v3/policies/13c92821e4c4476a878d3aae7444f52f"
        },
        "type": "application/json"
    }
}
HEAD
/v3/policies/{policy_id}/OS-ENDPOINT-POLICY/policy

Check policy and service endpoint association

Checks whether a policy is associated with an endpoint.

Request

Parameters

Name

In

Type

Description

policy_id

path

string

The policy ID.

Response

Status Codes
Success

Code

Reason
200 - OK

Request was successful.
PUT
/v3/policies/{policy_id}/OS-ENDPOINT-POLICY/services/{service_id}/regions/{region_id}

Associate policy and service-type endpoint in a region

Associates a policy and an endpoint of a service type in a region.

If an association already exists between the service in a region and another policy, this call replaces that association.

Request

Parameters

Name

In

Type

Description

policy_id

path

string

The policy ID.

service_id

path

string

The service ID.

region_id

path

string

The region ID.

Response

Status Codes
Success

Code

Reason
204 - No Content

The server has fulfilled the request.
GET
/v3/policies/{policy_id}/OS-ENDPOINT-POLICY/services/{service_id}/regions/{region_id}

Verify a policy and service-type endpoint in a region association

Verifies an association between a policy and service-type endpoint in a region.

A HEAD version of this API is also supported.

Request

Parameters

Name

In

Type

Description

policy_id

path

string

The policy ID.

service_id

path

string

The service ID.

region_id

path

string

The region ID.

Response

Status Codes
Success

Code

Reason
204 - No Content

The server has fulfilled the request.
DELETE
/v3/policies/{policy_id}/OS-ENDPOINT-POLICY/services/{service_id}/regions/{region_id}

Delete a policy and service-type endpoint in a region association

Deletes an association between a policy and service-type endpoint in a region.

Request

Parameters

Name

In

Type

Description

policy_id

path

string

The policy ID.

service_id

path

string

The service ID.

region_id

path

string

The region ID.

Response

Status Codes
Success

Code

Reason
204 - No Content

The server has fulfilled the request.
GET
/v3/policies/{policy_id}/OS-ENDPOINT-POLICY/endpoints

List policy and service endpoint associations

Lists all the endpoints that are currently associated with a policy through any of the association methods.

Request

Parameters

Name

In

Type

Description

policy_id

path

string

The policy ID.

Response

Parameters

Name

In

Type

Description

links

body

object

The links for the policy resource.

url

body

string

The endpoint URL.

region

body

string

(Deprecated in v3.2) The geographic location of the service endpoint.

next

body

string

The next relative link for the endpoints resource.

self

body

string

The self relative link for the endpoints resource.

interface

body

string

The interface type, which describes the visibility of the endpoint. Value is: - public. Visible by end users on a publicly available network interface. - internal. Visible by end users on an unmetered internal network interface. - admin. Visible by administrative users on a secure network interface.

service_id

body

string

The UUID of the service to which the endpoint belongs.

endpoints

body

array

An endpoints object.

id

body

string

The endpoint UUID.

previous

body

string

The previous relative link for the endpoints resource.
Status Codes
Success

Code

Reason
200 - OK

Request was successful.
Example
{
    "endpoints": [
        {
            "id": "1",
            "interface": "public",
            "links": {
                "self": "http://example.com/identity/v3/endpoints/1"
            },
            "region": "north",
            "service_id": "9242e05f0c23467bbd1cf1f7a6e5e596",
            "url": "http://example.com/identity/"
        },
        {
            "id": "1",
            "interface": "internal",
            "links": {
                "self": "http://example.com/identity/v3/endpoints/1"
            },
            "region": "south",
            "service_id": "9242e05f0c23467bbd1cf1f7a6e5e596",
            "url": "http://example.com/identity/"
        }
    ],
    "links": {
        "next": null,
        "previous": null,
        "self": "http://example.com/identity/v3/OS-ENDPOINT-POLICY/policies/13c92821e4c4476a878d3aae7444f52f/endpoints"
    }
}
GET
/v3/endpoints/{endpoint_id}/OS-ENDPOINT-POLICY/policy

Show the effective policy associated with an endpoint

Returns the policy that is currently associated with the given endpoint, by working through the ordered sequence of methods of association. The first association that is found will be returned. If the region of the endpoint has a parent, then region associations will be examined up the region tree in ascending order.

A HEAD version of this API is also supported.

Request

Parameters

Name

In

Type

Description

endpoint_id

path

string

The endpoint ID.

Response

Parameters

Name

In

Type

Description

policy

body

object

A policy object.

type

body

string

The MIME media type of the serialized policy blob. From the perspective of the Identity API, a policy blob can be based on any technology. In OpenStack, the policy.json blob (type="application/json") is the conventional solution. However, you might want to use an alternative policy engine that uses a different policy language type. For example, type="application/xacml+xml".

blob

body

object

The policy rule itself, as a serialized blob.

links

body

object

The links for the policy resource.

id

body

string

The ID of the policy.
Status Codes
Success

Code

Reason
200 - OK

Request was successful.
Example
{
    "policy": {
        "blob": {
            "foobar_user": [
                "role:compute-user"
            ]
        },
        "id": "13c92821e4c4476a878d3aae7444f52f",
        "links": {
            "self": "http://example.com/identity/v3/policies/13c92821e4c4476a878d3aae7444f52f"
        },
        "type": "application/json"
    }
}

OS-OAUTH1 API

Provide the ability for identity users to delegate roles to third party consumers via the OAuth 1.0a specification. Requires v3.0+ of the Identity API. An OAuth-derived token will provide a means of acting on behalf of the authorizing user.

Overview

Definitions

  • User: An Identity API service user, the entity whose role(s) will be delegated, and the entity that authorizes Request Tokens.

  • Request Token: A token used by the Consumer to obtain authorization from the User, and exchanged with an OAuth Verifier for an Access Token.

  • Access Token: A token used by the Consumer to request new Identity API tokens on behalf of the authorizing User, instead of using the User’s credentials.

  • Token Key: A key used by the token to identify itself. Both Request Tokens and Access Tokens have Token Keys. For OpenStack purposes, the Token Key is the Token ID.

  • Token Secret: A secret used by the Consumer to establish ownership of a given Token. Both Request Tokens and Access Tokens have Token Secrets.

  • OAuth Verifier: A string that must be provided with the corresponding Request Token in exchange for an Access Token.

Delegated Authentication Flow

Delegated Authentication via OAuth is done in five steps:

  1. An Identity API service User creates a Consumer.

  2. The Consumer obtains an unauthorized Request Token.

  3. The User authorizes the Request Token.

  4. The Consumer exchanges the Request Token for an Access Token.

  5. The Consumer uses the Access Token to request an Identity API service Token.

POST
/v3/OS-OAUTH1/consumers

Create consumer

Enables a user to create a consumer.

Relationship: https://docs.openstack.org/api/openstack-identity/3/ext/OS-OAUTH1/1.0/rel/consumers

Request

Parameters

Name

In

Type

Description

description (Optional)

body

string

The consumer description.
Example
{
    "consumer": {
        "description": "My consumer"
    }
}

Response

Status Codes
Success

Code

Reason
201 - Created

Resource was created and is ready to use.
Error

Code

Reason
413 - Request Entity Too Large

The request is larger than the server is willing or able to process.
415 - Unsupported Media Type

The request entity has a media type which the server or resource does not support.
405 - Method Not Allowed

Method is not valid for this endpoint.
404 - Not Found

The requested resource could not be found.
403 - Forbidden

Policy does not allow current user to do this operation.
401 - Unauthorized

User must authenticate before making a request.
400 - Bad Request

Some content in the request was invalid.
503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.
409 - Conflict

This operation conflicted with another operation on this resource.

Status: 201 Created

The secret is only returned once, during consumer creation.

Example
{
    "consumer": {
        "secret": "secretsecret",
        "description": "My consumer",
        "id": "7fea2d",
        "links": {
            "self": "http://example.com/identity/v3/OS-OAUTH1/consumers/7fea2d"
        }
    }
}
DELETE
/v3/OS-OAUTH1/consumers/{consumer_id}

Delete consumer

Deletes a consumer.

When you delete a consumer, any associated request tokens, access tokens, and Identity API tokens are also revoked.

Relationship: https://docs.openstack.org/api/openstack-identity/3/ext/OS-OAUTH1/1.0/rel/consumer

Request

Parameters

Name

In

Type

Description

consumer_id

path

string

The UUID of the consumer.

Response

Status Codes
Success

Code

Reason
204 - No Content

The server has fulfilled the request.
Error

Code

Reason
413 - Request Entity Too Large

The request is larger than the server is willing or able to process.
415 - Unsupported Media Type

The request entity has a media type which the server or resource does not support.
405 - Method Not Allowed

Method is not valid for this endpoint.
404 - Not Found

The requested resource could not be found.
403 - Forbidden

Policy does not allow current user to do this operation.
401 - Unauthorized

User must authenticate before making a request.
400 - Bad Request

Some content in the request was invalid.
503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.
409 - Conflict

This operation conflicted with another operation on this resource.
GET
/v3/OS-OAUTH1/consumers

List consumers

Lists consumers.

Relationship: https://docs.openstack.org/api/openstack-identity/3/ext/OS-OAUTH1/1.0/rel/consumers

Response

Status Codes
Success

Code

Reason
200 - OK

Request was successful.
Error

Code

Reason
413 - Request Entity Too Large

The request is larger than the server is willing or able to process.
405 - Method Not Allowed

Method is not valid for this endpoint.
404 - Not Found

The requested resource could not be found.
403 - Forbidden

Policy does not allow current user to do this operation.
401 - Unauthorized

User must authenticate before making a request.
400 - Bad Request

Some content in the request was invalid.
503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.
Example
{
    "consumers": [
        {
            "id": "0c2a74",
            "links": {
                "self": "http://example.com/identity/v3/OS-OAUTH1/consumers/0c2a74"
            }
        },
        {
            "description": "My consumer",
            "id": "7fea2d",
            "links": {
                "self": "http://example.com/identity/v3/OS-OAUTH1/consumers/7fea2d"
            }
        }
    ],
    "links": {
        "next": null,
        "previous": null,
        "self": "http://example.com/identity/v3/OS-OAUTH1/consumers"
    }
}
GET
/v3/OS-OAUTH1/consumers/{consumer_id}

Show consumer details

Shows details for a consumer.

Relationship: https://docs.openstack.org/api/openstack-identity/3/ext/OS-OAUTH1/1.0/rel/consumer

Request

Parameters

Name

In

Type

Description

consumer_id

path

string

The UUID of the consumer.

Response

Status Codes
Success

Code

Reason
200 - OK

Request was successful.
Error

Code

Reason
413 - Request Entity Too Large

The request is larger than the server is willing or able to process.
405 - Method Not Allowed

Method is not valid for this endpoint.
404 - Not Found

The requested resource could not be found.
403 - Forbidden

Policy does not allow current user to do this operation.
401 - Unauthorized

User must authenticate before making a request.
400 - Bad Request

Some content in the request was invalid.
503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.
Example
{
    "consumer": {
        "id": "7fea2d",
        "description": "My consumer",
        "links": {
            "self": "http://example.com/identity/v3/OS-OAUTH1/consumers/7fea2d"
        }
    }
}
PATCH
/v3/OS-OAUTH1/consumers/{consumer_id}

Update consumer

Updates the description for a consumer.

If you try to update any attribute other than description, an HTTP 400 Bad Request error is returned.

Relationship: https://docs.openstack.org/api/openstack-identity/3/ext/OS-OAUTH1/1.0/rel/consumer

Request

Parameters

Name

In

Type

Description

consumer_id

path

string

The UUID of the consumer.
Example
{
    "consumer": {
        "description": "My new consumer"
    }
}

Response

Status Codes
Success

Code

Reason
200 - OK

Request was successful.
Error

Code

Reason
413 - Request Entity Too Large

The request is larger than the server is willing or able to process.
415 - Unsupported Media Type

The request entity has a media type which the server or resource does not support.
405 - Method Not Allowed

Method is not valid for this endpoint.
404 - Not Found

The requested resource could not be found.
403 - Forbidden

Policy does not allow current user to do this operation.
401 - Unauthorized

User must authenticate before making a request.
400 - Bad Request

Some content in the request was invalid.
503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.
409 - Conflict

This operation conflicted with another operation on this resource.
Example
{
    "consumer": {
        "description": "My new consumer",
        "id": "7fea2d",
        "links": {
            "self": "http://example.com/identity/v3/OS-OAUTH1/consumers/7fea2d"
        }
    }
}
POST
/v3/OS-OAUTH1/request_token

Create request token

Enables a consumer to get an unauthorized request token.

Supported signature methods: HMAC-SHA1

The consumer must provide all required OAuth parameters in the request. See Consumer Obtains a Request Token.

Relationship: https://docs.openstack.org/api/openstack-identity/3/ext/OS-OAUTH1/1.0/rel/request_tokens

Request

Parameters

Name

In

Type

Description

Requested-Project-Id

header

string

The ID of the requested project.

Response

Parameters

Name

In

Type

Description

oauth_token

body

string

The key value for the oauth token that the Identity API returns.

oauth_token_secret

body

string

The secret value associated with the oauth Token.

oauth_expires_at (Optional)

body

string

The date and time when an oauth token expires.

The date and time stamp format is ISO 8601:

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

The ±hh:mm value, if included, is the time zone as an offset from UTC.

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

If the Identity API does not include this attribute or its value is null, the token never expires.
Status Codes
Success

Code

Reason
201 - Created

Resource was created and is ready to use.
Error

Code

Reason
413 - Request Entity Too Large

The request is larger than the server is willing or able to process.
415 - Unsupported Media Type

The request entity has a media type which the server or resource does not support.
405 - Method Not Allowed

Method is not valid for this endpoint.
404 - Not Found

The requested resource could not be found.
403 - Forbidden

Policy does not allow current user to do this operation.
401 - Unauthorized

User must authenticate before making a request.
400 - Bad Request

Some content in the request was invalid.
503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.
409 - Conflict

This operation conflicted with another operation on this resource.
Example
oauth_token=29971f&oauth_token_secret=238eb8&oauth_expires_at=2013-09-11T06:07:51.501805Z
PUT
/v3/OS-OAUTH1/authorize/{request_token_id}

Authorize request token

To authorize the Request Token, the authorizing user must have access to the requested project. Upon successful authorization, an OAuth Verifier code is returned. The Consumer receives the OAuth Verifier from the User out-of-band.

Relationship: https://docs.openstack.org/api/openstack-identity/3/ext/OS-OAUTH1/1.0/rel/authorize_request_token

Request

Example
{
    "roles": [
        {
            "id": "a3b29b"
        },
        {
            "id": "49993e"
        }
    ]
}

Response

Status Codes
Success

Code

Reason
200 - OK

Request was successful.
Error

Code

Reason
413 - Request Entity Too Large

The request is larger than the server is willing or able to process.
415 - Unsupported Media Type

The request entity has a media type which the server or resource does not support.
405 - Method Not Allowed

Method is not valid for this endpoint.
404 - Not Found

The requested resource could not be found.
403 - Forbidden

Policy does not allow current user to do this operation.
401 - Unauthorized

User must authenticate before making a request.
400 - Bad Request

Some content in the request was invalid.
503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.
409 - Conflict

This operation conflicted with another operation on this resource.
Example
{
    "token": {
        "oauth_verifier": "8171"
    }
}
POST
/v3/OS-OAUTH1/access_token

Create access token

Enables a consumer to obtain an access token by exchanging a request token.

After a user authorizes the request token, the consumer exchanges the authorized request token and OAuth verifier for an access token.

Supported signature methods: HMAC-SHA1

The consumer must provide all required OAuth parameters in the request. See Consumer Requests an Access Token.

Relationship: https://docs.openstack.org/api/openstack-identity/3/ext/OS-OAUTH1/1.0/rel/access_tokens

Response

Parameters

Name

In

Type

Description

oauth_token

body

string

The key value for the oauth token that the Identity API returns.

oauth_token_secret

body

string

The secret value associated with the oauth Token.

oauth_expires_at (Optional)

body

string

The date and time when an oauth token expires.

The date and time stamp format is ISO 8601:

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

The ±hh:mm value, if included, is the time zone as an offset from UTC.

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

If the Identity API does not include this attribute or its value is null, the token never expires.
Status Codes
Success

Code

Reason
201 - Created

Resource was created and is ready to use.
Error

Code

Reason
413 - Request Entity Too Large

The request is larger than the server is willing or able to process.
415 - Unsupported Media Type

The request entity has a media type which the server or resource does not support.
405 - Method Not Allowed

Method is not valid for this endpoint.
404 - Not Found

The requested resource could not be found.
403 - Forbidden

Policy does not allow current user to do this operation.
401 - Unauthorized

User must authenticate before making a request.
400 - Bad Request

Some content in the request was invalid.
503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.
409 - Conflict

This operation conflicted with another operation on this resource.
Example
oauth_token=accd36&oauth_token_secret=aa47da&oauth_expires_at=2013-09-11T06:07:51.501805Z
GET
/v3/users/{user_id}/OS-OAUTH1/access_tokens/{access_token_id}

Get access token

Gets an access token.

Relationship: https://docs.openstack.org/api/openstack-identity/3/ext/OS-OAUTH1/1.0/rel/user_access_token

Request

Parameters

Name

In

Type

Description

user_id

path

string

The UUID of the user.

access_token_id

path

string

The UUID of the access token.

Response

Status Codes
Success

Code

Reason
200 - OK

Request was successful.
Error

Code

Reason
413 - Request Entity Too Large

The request is larger than the server is willing or able to process.
405 - Method Not Allowed

Method is not valid for this endpoint.
404 - Not Found

The requested resource could not be found.
403 - Forbidden

Policy does not allow current user to do this operation.
401 - Unauthorized

User must authenticate before making a request.
400 - Bad Request

Some content in the request was invalid.
503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.
Example
{
    "access_token": {
        "consumer_id": "7fea2d",
        "id": "6be26a",
        "expires_at": "2013-09-11T06:07:51.501805Z",
        "links": {
            "roles": "http://example.com/identity/v3/users/ce9e07/OS-OAUTH1/access_tokens/6be26a/roles",
            "self": "http://example.com/identity/v3/users/ce9e07/OS-OAUTH1/access_tokens/6be26a"
        },
        "project_id": "b9fca3",
        "authorizing_user_id": "ce9e07"
    }
}
DELETE
/v3/users/{user_id}/OS-OAUTH1/access_tokens/{access_token_id}

Revoke access token

Enables a user to revoke an access token, which prevents the consumer from requesting new Identity Service API tokens. Also, revokes any Identity Service API tokens that were issued to the consumer through that access token.

Relationship: https://docs.openstack.org/api/openstack-identity/3/ext/OS-OAUTH1/1.0/rel/user_access_token

Request

Parameters

Name

In

Type

Description

user_id

path

string

The UUID of the user.

access_token_id

path

string

The UUID of the access token.

Response

Status Codes
Success

Code

Reason
204 - No Content

The server has fulfilled the request.
Error

Code

Reason
413 - Request Entity Too Large

The request is larger than the server is willing or able to process.
415 - Unsupported Media Type

The request entity has a media type which the server or resource does not support.
405 - Method Not Allowed

Method is not valid for this endpoint.
404 - Not Found

The requested resource could not be found.
403 - Forbidden

Policy does not allow current user to do this operation.
401 - Unauthorized

User must authenticate before making a request.
400 - Bad Request

Some content in the request was invalid.
503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.
409 - Conflict

This operation conflicted with another operation on this resource.
GET
/v3/users/{user_id}/OS-OAUTH1/access_tokens

List access tokens

Lists authorized access tokens.

Relationship: https://docs.openstack.org/api/openstack-identity/3/ext/OS-OAUTH1/1.0/rel/user_access_tokens

Request

Parameters

Name

In

Type

Description

user_id

path

string

The UUID of the user.

Response

Status Codes
Success

Code

Reason
200 - OK

Request was successful.
Error

Code

Reason
413 - Request Entity Too Large

The request is larger than the server is willing or able to process.
405 - Method Not Allowed

Method is not valid for this endpoint.
404 - Not Found

The requested resource could not be found.
403 - Forbidden

Policy does not allow current user to do this operation.
401 - Unauthorized

User must authenticate before making a request.
400 - Bad Request

Some content in the request was invalid.
503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.
Example
{
    "access_tokens": [
        {
            "consumer_id": "7fea2d",
            "id": "6be26a",
            "expires_at": "2013-09-11T06:07:51.501805Z",
            "links": {
                "roles": "http://example.com/identity/v3/users/ce9e07/OS-OAUTH1/access_tokens/6be26a/roles",
                "self": "http://example.com/identity/v3/users/ce9e07/OS-OAUTH1/access_tokens/6be26a"
            },
            "project_id": "b9fca3",
            "authorizing_user_id": "ce9e07"
        }
    ],
    "links": {
        "next": null,
        "previous": null,
        "self": "http://example.com/identity/v3/users/ce9e07/OS-OAUTH1/access_tokens"
    }
}
GET
/v3/users/{user_id}/OS-OAUTH1/access_tokens/{access_token_id}/roles

List roles for an access token

Lists associated roles for an access token.

Relationship: https://docs.openstack.org/api/openstack-identity/3/ext/OS-OAUTH1/1.0/rel/user_access_token_roles

Request

Parameters

Name

In

Type

Description

user_id

path

string

The UUID of the user.

access_token_id

path

string

The UUID of the access token.

Response

Status Codes
Success

Code

Reason
200 - OK

Request was successful.
Error

Code

Reason
413 - Request Entity Too Large

The request is larger than the server is willing or able to process.
415 - Unsupported Media Type

The request entity has a media type which the server or resource does not support.
405 - Method Not Allowed

Method is not valid for this endpoint.
404 - Not Found

The requested resource could not be found.
403 - Forbidden

Policy does not allow current user to do this operation.
401 - Unauthorized

User must authenticate before making a request.
400 - Bad Request

Some content in the request was invalid.
503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.
409 - Conflict

This operation conflicted with another operation on this resource.
Example
{
    "roles": [
        {
            "id": "5ad150",
            "domain_id": "7cf37b",
            "links": {
                "self": "http://example.com/identity/v3/roles/5ad150"
            },
            "name": "admin"
        },
        {
            "id": "a62eb6",
            "domain_id": "7cf37b",
            "links": {
                "self": "http://example.com/identity/v3/roles/a62eb6"
            },
            "name": "Member"
        }
    ],
    "links": {
        "next": null,
        "previous": null,
        "self": "http://example.com/identity/v3/users/ce9e07/OS-OAUTH1/access_tokens/6be26a/roles"
    }
}
GET
/v3/users/{user_id}/OS-OAUTH1/access_tokens/{access_token_id}/roles/{role_id}

Show role details for an access token

Shows details for a role for an access token.

Relationship: https://docs.openstack.org/api/openstack-identity/3/ext/OS-OAUTH1/1.0/rel/user_access_token_role

Request

Parameters

Name

In

Type

Description

user_id

path

string

The UUID of the user.

role_id

path

string

The UUID of the role.

access_token_id

path

string

The UUID of the access token.

Response

Status Codes
Success

Code

Reason
200 - OK

Request was successful.
Error

Code

Reason
413 - Request Entity Too Large

The request is larger than the server is willing or able to process.
405 - Method Not Allowed

Method is not valid for this endpoint.
404 - Not Found

The requested resource could not be found.
403 - Forbidden

Policy does not allow current user to do this operation.
401 - Unauthorized

User must authenticate before making a request.
400 - Bad Request

Some content in the request was invalid.
503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.
Example
{
    "role": {
        "id": "5ad150",
        "domain_id": "7cf37b",
        "links": {
            "self": "http://example.com/identity/v3/roles/5ad150"
        },
        "name": "admin"
    }
}
POST
/v3/auth/tokens

Authenticate with Identity API

Enables a consumer to get an Identity Service authentication token.

The token represents the delegated authorization and identity (impersonation) of the authorizing user. The roles and scope of the generated token match those that the consumer initially requested.

Supported signature methods: HMAC-SHA1

The consumer must provide required OAuth parameters in the request. See Accessing Protected Resources.

The returned token is scoped to the requested project and with the requested roles. In addition to the standard token response, the token has an OAuth-specific object.

Example OAuth-specific object in a token:

"OS-OAUTH1": {
    "access_token_id": "cce0b8be7"
}

Relationship: https://docs.openstack.org/identity/rel/v3/auth_tokens

Response

Status Codes
Success

Code

Reason
200 - OK

Request was successful.
Error

Code

Reason
413 - Request Entity Too Large

The request is larger than the server is willing or able to process.
405 - Method Not Allowed

Method is not valid for this endpoint.
404 - Not Found

The requested resource could not be found.
403 - Forbidden

Policy does not allow current user to do this operation.
401 - Unauthorized

User must authenticate before making a request.
400 - Bad Request

Some content in the request was invalid.
503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.

OS-OAUTH2 API

Provide the ability for identity users to delegate roles to third party consumers via the OAuth 2.0 Client Credentials grant specification. Requires v3.0+ of the Identity API. An OAuth2-derived access token will provide a means of acting on behalf of the authorizing user.

Overview

Definitions

  • User: The end-users who use Identity API service, the entity whose role(s) will be delegated, and the entity that registers Clients.

  • Client: An application making protected resource requests on behalf of the User. The credentials of the client are created though the Application Credentials API.

  • Access Token: A token used by the Client to make protected resource requests with the delegated roles.

Delegated Authentication Flow

Delegated Authentication via OAuth 2.0 is done in four steps:

  1. An Identity API service User creates an application credential.

  2. The Client authenticates with the authorization server on the Keystone and requests a new Access Token.

  3. The Client uses the Access Token to make requests for OpenStack Service APIs.

  4. Keystone Middleware validates the Access Token in an API request to obtain its metadata and validity, and forwards the request to the OpenStack service if the token is active.

POST
/identity/v3/OS-OAUTH2/token

Create Access Token

Enables a user to create an access token. The user makes a request to the token endpoint by adding the following parameters using the “application/x-www-form-urlencoded” format with a character encoding of UTF-8 in the HTTP request entity-body. And the request should use the basic authentication header which contains the application credentials information to authenticate a user through the authorization server.

Relationship: https://docs.openstack.org/api/openstack-identity/3/ext/OS-OAUTH2/1.0/rel/token

Request

Parameters

Name

In

Type

Description

grant_type

body

string

Value MUST be set to “client_credentials”.
Example
grant_type=client_credentials

Response

Parameters

Name

In

Type

Description

access_token

body

string

The authentication token issued by the authorization server.

token_type

body

string

The type of the token issued by the authorization server. Currently only the “Bearer” token type is supported.

expires_in

body

integer

The lifetime in seconds of the access token. For example, the value “3600” denotes that the access token will expire in one hour from the time the response was generated.
Status Codes
Success

Code

Reason
200 - OK

Request was successful.
Error

Code

Reason
400 - Bad Request

Some content in the request was invalid.
401 - Unauthorized

User must authenticate before making a request.
404 - Not Found

The requested resource could not be found.
500 - Internal Server Error

Something went wrong inside the service. This should not happen usually. If it does happen, it means the server has experienced some serious problems.

Status: 200 OK

Example
{
    "access_token": "gAAAAABhi1cMynG89h8t6TJrxNiZuNzjcIUIxNctoVfuqTw7BpUedLKxjPymClVEnj9GhIT5u2mpjaJATlEAtaa3D6_t8jk_fV-mqo2IUlsmTPTnMwkcjh5FSHQVRdqvDxgY3nSqLA_Hfv-zPmjS5KWX3hmyDE5YWO1ztX6QNVQb4wTPyNL1-7I",
    "token_type": "Bearer",
    "expires_in": 3600
}

OS-TRUST API

Trusts provide project-specific role delegation between users, with optional impersonation.

API Resources

Trusts

A trust represents a user’s (the trustor) authorization to delegate roles to another user (the trustee), and optionally allow the trustee to impersonate the trustor. After the trustor has created a trust, the trustee can specify the trust’s id attribute as part of an authentication request to then create a token representing the delegated authority of the trustor.

The trust contains constraints on the delegated attributes. A token created based on a trust will convey a subset of the trustor’s roles on the specified project. Optionally, the trust may only be valid for a specified time period, as defined by expires_at. If no expires_at is specified, then the trust is valid until it is explicitly revoked.

The impersonation flag allows the trustor to optionally delegate impersonation abilities to the trustee. To services validating the token, the trustee will appear as the trustor, although the token will also contain the impersonation flag to indicate that this behavior is in effect.

A project_id may not be specified without at least one role, and vice versa. In other words, there is no way of implicitly delegating all roles to a trustee, in order to prevent users accidentally creating trust that are much more broad in scope than intended. A trust without a project_id or any delegated roles is unscoped, and therefore does not represent authorization on a specific resource.

Trusts are immutable. If the trustee or trustor wishes to modify the attributes of the trust, they should create a new trust and delete the old trust. If a trust is deleted, any tokens generated based on the trust are immediately revoked.

If the trustor loses access to any delegated attributes, the trust becomes immediately invalid and any tokens generated based on the trust are immediately revoked.

Trusts can also be chained, meaning, a trust can be created by using a trust scoped token.

For more information, see Use trusts.

POST
/v3/auth/tokens

Consuming a trust

Consuming a trust effectively assumes the scope as delegated in the trust. No other scope attributes may be specified.

The user specified by authentication must match the trust’s trustee_user_id attribute.

If the trust has the impersonation attribute set to true, then the resulting token’s user attribute will also represent the trustor, rather than the authenticating user (the trustee).

Request

Example
{
    "auth": {
        "identity": {
            "methods": [
                "token"
            ],
            "token": {
                "id": "e80b74"
            }
        },
        "scope": {
            "OS-TRUST:trust": {
                "id": "de0945a"
            }
        }
    }
}

A token created from a trust will have an OS-TRUST:trust section containing the id of the trust, the impersonation flag, the trustee_user_id and the trustor_user_id.

Response

Example
{
    "token": {
        "expires_at": "2013-02-27T18:30:59.999999Z",
        "issued_at": "2013-02-27T16:30:59.999999Z",
        "methods": [
            "password"
        ],
        "OS-TRUST:trust": {
            "id": "fe0aef",
            "impersonation": false,
            "links": {
                "self": "http://example.com/identity/v3/trusts/fe0aef"
            },
            "trustee_user": {
                "id": "0ca8f6",
                "links": {
                    "self": "http://example.com/identity/v3/users/0ca8f6"
                }
            },
            "trustor_user": {
                "id": "bd263c",
                "links": {
                    "self": "http://example.com/identity/v3/users/bd263c"
                }
            }
        },
        "user": {
            "domain": {
                "id": "1789d1",
                "links": {
                    "self": "http://example.com/identity/v3/domains/1789d1"
                },
                "name": "example.com"
            },
            "email": "joe@example.com",
            "id": "0ca8f6",
            "links": {
                "self": "http://example.com/identity/v3/users/0ca8f6"
            },
            "name": "Joe"
        }
    }
}

A token created from a redelegated trust will have an OS-TRUST:trust section containing the same fields as a regular trust token, only redelegated_trust_id and redelegation_count are added.

{
    "token": {
        "expires_at": "2013-02-27T18:30:59.999999Z",
        "issued_at": "2013-02-27T16:30:59.999999Z",
        "methods": [
            "password"
        ],
        "OS-TRUST:trust": {
            "id": "fe0aef",
            "impersonation": false,
            "redelegated_trust_id": "3ba234",
            "redelegation_count": 2,
            "links": {
                "self": "http://example.com/identity/v3/trusts/fe0aef"
            },
            "trustee_user": {
                "id": "0ca8f6",
                "links": {
                    "self": "http://example.com/identity/v3/users/0ca8f6"
                }
            },
            "trustor_user": {
                "id": "bd263c",
                "links": {
                    "self": "http://example.com/identity/v3/users/bd263c"
                }
            }
        },
        "user": {
            "domain": {
                "id": "1789d1",
                "links": {
                    "self": "http://example.com/identity/v3/domains/1789d1"
                },
                "name": "example.com"
            },
            "email": "joe@example.com",
            "id": "0ca8f6",
            "links": {
                "self": "http://example.com/identity/v3/users/0ca8f6"
            },
            "name": "Joe"
        }
    }
}
POST
/v3/OS-TRUST/trusts

Create trust

Creates a trust.

Relationship: https://docs.openstack.org/api/openstack-identity/3/ext/OS-TRUST/1.0/rel/trusts

Request

Parameters

Name

In

Type

Description

trust

body

object

A trust object.

impersonation

body

boolean

If set to true, then the user attribute of tokens generated based on the trust will represent that of the trustor rather than the trustee, thus allowing the trustee to impersonate the trustor. If impersonation is set to false, then the token’s user attribute will represent that of the trustee.

trustee_user_id

body

string

Represents the user who is capable of consuming the trust.

trustor_user_id

body

string

Represents the user who created the trust, and who’s authorization is being delegated.

allow_redelegation (Optional)

body

boolean

If set to true then a trust between a trustor and any third-party user may be issued by the trustee just like a regular trust. If set to false, stops further redelegation. false by default.

expires_at (Optional)

body

string

Specifies the expiration time of the trust. A trust may be revoked ahead of expiration. If the value represents a time in the past, the trust is deactivated. In the redelegation case it must not exceed the value of the corresponding expires_at field of the redelegated trust or it may be omitted, then the expires_at value is copied from the redelegated trust.

project_id (Optional)

body

string

Identifies the project upon which the trustor is delegating authorization.

redelegation_count (Optional)

body

integer

Specifies the maximum remaining depth of the redelegated trust chain. Each subsequent trust has this field decremented by 1 automatically. The initial trustor issuing new trust that can be redelegated, must set allow_redelegation to true and may set redelegation_count to an integer value less than or equal to max_redelegation_count configuration parameter in order to limit the possible length of derivated trust chains. The trust issued by the trustor using a project-scoped token (not redelegating), in which allow_redelegation is set to true (the new trust is redelegatable), will be populated with the value specified in the max_redelegation_count configuration parameter if redelegation_count is not set or set to null. If allow_redelegation is set to false then redelegation_count will be set to 0 in the trust.

If the trust is being issued by the trustee of a redelegatable trust-scoped token (redelegation case) then redelegation_count should not be set, as it will automatically be set to the value in the redelegatable trust-scoped token decremented by 1. Note, if the resulting value is 0, this means that the new trust will not be redelegatable, regardless of the value of allow_redelegation.

remaining_uses (Optional)

body

boolean

Specifies how many times the trust can be used to obtain a token. This value is decreased each time a token is issued through the trust. Once it reaches 0, no further tokens will be issued through the trust. The default value is null, meaning there is no limit on the number of tokens issued through the trust. If redelegation is enabled it must not be set.

roles (Optional)

body

array

Specifies the subset of the trustor’s roles on the project_id to be granted to the trustee when the token is consumed. The trustor must already be granted these roles in the project referenced by the project_id attribute. If redelegation is used (when trust-scoped token is used and consumed trust has allow_redelegation set to true) this parameter should contain redelegated trust’s roles only.

Roles are only provided when the trust is created, and are subsequently available as a separate read-only collection. Each role can be specified by either id or name.
Example

Status: 201 Created

{
    "trust": {
        "expires_at": "2013-02-27T18:30:59.999999Z",
        "impersonation": true,
        "allow_redelegation": true,
        "project_id": "ddef321",
        "roles": [
            {
                "name": "member"
            }
        ],
        "trustee_user_id": "86c0d5",
        "trustor_user_id": "a0fdfd"
    }
}

Response

Parameters

Name

In

Type

Description

trust

body

object

A trust object.

id

body

string

The ID of the trust.

impersonation

body

boolean

If set to true, then the user attribute of tokens generated based on the trust will represent that of the trustor rather than the trustee, thus allowing the trustee to impersonate the trustor. If impersonation is set to false, then the token’s user attribute will represent that of the trustee.

trustee_user_id

body

string

Represents the user who is capable of consuming the trust.

trustor_user_id

body

string

Represents the user who created the trust, and who’s authorization is being delegated.

allow_redelegation (Optional)

body

boolean

If set to true then a trust between a trustor and any third-party user may be issued by the trustee just like a regular trust. If set to false, stops further redelegation. false by default.

expires_at (Optional)

body

string

Specifies the expiration time of the trust. A trust may be revoked ahead of expiration. If the value represents a time in the past, the trust is deactivated. In the redelegation case it must not exceed the value of the corresponding expires_at field of the redelegated trust or it may be omitted, then the expires_at value is copied from the redelegated trust.

project_id (Optional)

body

string

Identifies the project upon which the trustor is delegating authorization.

redelegated_trust_id (Optional)

body

string

Returned with redelegated trust provides information about the predecessor in the trust chain.

redelegation_count (Optional)

body

integer

Specifies the maximum remaining depth of the redelegated trust chain. Each subsequent trust has this field decremented by 1 automatically. The initial trustor issuing new trust that can be redelegated, must set allow_redelegation to true and may set redelegation_count to an integer value less than or equal to max_redelegation_count configuration parameter in order to limit the possible length of derivated trust chains. The trust issued by the trustor using a project-scoped token (not redelegating), in which allow_redelegation is set to true (the new trust is redelegatable), will be populated with the value specified in the max_redelegation_count configuration parameter if redelegation_count is not set or set to null. If allow_redelegation is set to false then redelegation_count will be set to 0 in the trust.

If the trust is being issued by the trustee of a redelegatable trust-scoped token (redelegation case) then redelegation_count should not be set, as it will automatically be set to the value in the redelegatable trust-scoped token decremented by 1. Note, if the resulting value is 0, this means that the new trust will not be redelegatable, regardless of the value of allow_redelegation.

remaining_uses (Optional)

body

boolean

Specifies how many times the trust can be used to obtain a token. This value is decreased each time a token is issued through the trust. Once it reaches 0, no further tokens will be issued through the trust. The default value is null, meaning there is no limit on the number of tokens issued through the trust. If redelegation is enabled it must not be set.

roles (Optional)

body

array

Specifies the subset of the trustor’s roles on the project_id to be granted to the trustee when the token is consumed. The trustor must already be granted these roles in the project referenced by the project_id attribute. If redelegation is used (when trust-scoped token is used and consumed trust has allow_redelegation set to true) this parameter should contain redelegated trust’s roles only.

Roles are only provided when the trust is created, and are subsequently available as a separate read-only collection. Each role can be specified by either id or name.

roles_links

body

object

A roles links object. Includes next, previous, and self links for roles.

links

body

object

A trust links object. Includes next, previous, and self links for trusts.
Status Codes
Success

Code

Reason
201 - Created

Resource was created and is ready to use.
Error

Code

Reason
400 - Bad Request

Some content in the request was invalid.
401 - Unauthorized

User must authenticate before making a request.
403 - Forbidden

Policy does not allow current user to do this operation.
404 - Not Found

The requested resource could not be found.
405 - Method Not Allowed

Method is not valid for this endpoint.
409 - Conflict

This operation conflicted with another operation on this resource.
413 - Request Entity Too Large

The request is larger than the server is willing or able to process.
415 - Unsupported Media Type

The request entity has a media type which the server or resource does not support.
503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.
Example

Status: 201 Created

{
    "trust": {
        "expires_at": "2013-02-27T18:30:59.999999Z",
        "id": "1ff900",
        "impersonation": true,
        "redelegation_count": 10,
        "links": {
            "self": "http://example.com/identity/v3/OS-TRUST/trusts/1ff900"
        },
        "project_id": "ddef321",
        "remaining_uses": null,
        "roles": [
            {
                "id": "ed7b78",
                "links": {
                    "self": "http://example.com/identity/v3/roles/ed7b78"
                },
                "name": "member"
            }
        ],
        "roles_links": {
            "next": null,
            "previous": null,
            "self": "http://example.com/identity/v3/OS-TRUST/trusts/1ff900/roles"
        },
        "trustee_user_id": "86c0d5",
        "trustor_user_id": "a0fdfd"
    }
}
GET
/v3/OS-TRUST/trusts

List trusts

Lists all trusts.

Relationship: https://docs.openstack.org/api/openstack-identity/3/ext/OS-TRUST/1.0/rel/trusts

Request

Parameters

Name

In

Type

Description

trustor_user_id (Optional)

query

string

Filters the response by a trustor user ID. In order to list trusts for a given trustor, filter the collection using a query string (e.g., ?trustor_user_id={user_id}).

trustee_user_id (Optional)

query

string

Filters the response by a trustee user ID. In order to list trusts for a given trustee, filter the collection using a query string (e.g., ?trustee_user_id={user_id}).

Response

Parameters

Name

In

Type

Description

trust

body

object

A trust object.

id

body

string

The ID of the trust.

impersonation

body

boolean

If set to true, then the user attribute of tokens generated based on the trust will represent that of the trustor rather than the trustee, thus allowing the trustee to impersonate the trustor. If impersonation is set to false, then the token’s user attribute will represent that of the trustee.

trustee_user_id

body

string

Represents the user who is capable of consuming the trust.

trustor_user_id

body

string

Represents the user who created the trust, and who’s authorization is being delegated.

allow_redelegation (Optional)

body

boolean

If set to true then a trust between a trustor and any third-party user may be issued by the trustee just like a regular trust. If set to false, stops further redelegation. false by default.

expires_at (Optional)

body

string

Specifies the expiration time of the trust. A trust may be revoked ahead of expiration. If the value represents a time in the past, the trust is deactivated. In the redelegation case it must not exceed the value of the corresponding expires_at field of the redelegated trust or it may be omitted, then the expires_at value is copied from the redelegated trust.

project_id (Optional)

body

string

Identifies the project upon which the trustor is delegating authorization.

redelegated_trust_id (Optional)

body

string

Returned with redelegated trust provides information about the predecessor in the trust chain.

redelegation_count (Optional)

body

integer

Specifies the maximum remaining depth of the redelegated trust chain. Each subsequent trust has this field decremented by 1 automatically. The initial trustor issuing new trust that can be redelegated, must set allow_redelegation to true and may set redelegation_count to an integer value less than or equal to max_redelegation_count configuration parameter in order to limit the possible length of derivated trust chains. The trust issued by the trustor using a project-scoped token (not redelegating), in which allow_redelegation is set to true (the new trust is redelegatable), will be populated with the value specified in the max_redelegation_count configuration parameter if redelegation_count is not set or set to null. If allow_redelegation is set to false then redelegation_count will be set to 0 in the trust.

If the trust is being issued by the trustee of a redelegatable trust-scoped token (redelegation case) then redelegation_count should not be set, as it will automatically be set to the value in the redelegatable trust-scoped token decremented by 1. Note, if the resulting value is 0, this means that the new trust will not be redelegatable, regardless of the value of allow_redelegation.

remaining_uses (Optional)

body

boolean

Specifies how many times the trust can be used to obtain a token. This value is decreased each time a token is issued through the trust. Once it reaches 0, no further tokens will be issued through the trust. The default value is null, meaning there is no limit on the number of tokens issued through the trust. If redelegation is enabled it must not be set.

roles (Optional)

body

array

Specifies the subset of the trustor’s roles on the project_id to be granted to the trustee when the token is consumed. The trustor must already be granted these roles in the project referenced by the project_id attribute. If redelegation is used (when trust-scoped token is used and consumed trust has allow_redelegation set to true) this parameter should contain redelegated trust’s roles only.

Roles are only provided when the trust is created, and are subsequently available as a separate read-only collection. Each role can be specified by either id or name.

roles_links

body

object

A roles links object. Includes next, previous, and self links for roles.

links

body

object

A trust links object. Includes next, previous, and self links for trusts.
Status Codes
Success

Code

Reason
200 - OK

Request was successful.
Error

Code

Reason
400 - Bad Request

Some content in the request was invalid.
401 - Unauthorized

User must authenticate before making a request.
403 - Forbidden

Policy does not allow current user to do this operation.
404 - Not Found

The requested resource could not be found.
405 - Method Not Allowed

Method is not valid for this endpoint.
413 - Request Entity Too Large

The request is larger than the server is willing or able to process.
503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.
Example

Status: 200 OK

{
    "trusts": [
        {
            "id": "1ff900",
            "expires_at": "2013-02-27T18:30:59.999999Z",
            "impersonation": true,
            "links": {
                "self": "http://example.com/identity/v3/OS-TRUST/trusts/1ff900"
            },
            "project_id": "0f1233",
            "trustee_user_id": "86c0d5",
            "trustor_user_id": "a0fdfd"
        },
        {
            "id": "f4513a",
            "impersonation": false,
            "links": {
                "self": "http://example.com/identity/v3/OS-TRUST/trusts/f45513a"
            },
            "project_id": "0f1233",
            "trustee_user_id": "86c0d5",
            "trustor_user_id": "3cd2ce"
        }
    ]
}
GET
/v3/OS-TRUST/trusts/{trust_id}

Get trust

Gets the trust information for {trust_id}.

Relationship: https://docs.openstack.org/api/openstack-identity/3/ext/OS-TRUST/1.0/rel/trust

Request

Parameters

Name

In

Type

Description

trust_id

path

string

The trust ID.

Response

Parameters

Name

In

Type

Description

trust

body

object

A trust object.

id

body

string

The ID of the trust.

impersonation

body

boolean

If set to true, then the user attribute of tokens generated based on the trust will represent that of the trustor rather than the trustee, thus allowing the trustee to impersonate the trustor. If impersonation is set to false, then the token’s user attribute will represent that of the trustee.

trustee_user_id

body

string

Represents the user who is capable of consuming the trust.

trustor_user_id

body

string

Represents the user who created the trust, and who’s authorization is being delegated.

allow_redelegation (Optional)

body

boolean

If set to true then a trust between a trustor and any third-party user may be issued by the trustee just like a regular trust. If set to false, stops further redelegation. false by default.

expires_at (Optional)

body

string

Specifies the expiration time of the trust. A trust may be revoked ahead of expiration. If the value represents a time in the past, the trust is deactivated. In the redelegation case it must not exceed the value of the corresponding expires_at field of the redelegated trust or it may be omitted, then the expires_at value is copied from the redelegated trust.

project_id (Optional)

body

string

Identifies the project upon which the trustor is delegating authorization.

redelegated_trust_id (Optional)

body

string

Returned with redelegated trust provides information about the predecessor in the trust chain.

redelegation_count (Optional)

body

integer

Specifies the maximum remaining depth of the redelegated trust chain. Each subsequent trust has this field decremented by 1 automatically. The initial trustor issuing new trust that can be redelegated, must set allow_redelegation to true and may set redelegation_count to an integer value less than or equal to max_redelegation_count configuration parameter in order to limit the possible length of derivated trust chains. The trust issued by the trustor using a project-scoped token (not redelegating), in which allow_redelegation is set to true (the new trust is redelegatable), will be populated with the value specified in the max_redelegation_count configuration parameter if redelegation_count is not set or set to null. If allow_redelegation is set to false then redelegation_count will be set to 0 in the trust.

If the trust is being issued by the trustee of a redelegatable trust-scoped token (redelegation case) then redelegation_count should not be set, as it will automatically be set to the value in the redelegatable trust-scoped token decremented by 1. Note, if the resulting value is 0, this means that the new trust will not be redelegatable, regardless of the value of allow_redelegation.

remaining_uses (Optional)

body

boolean

Specifies how many times the trust can be used to obtain a token. This value is decreased each time a token is issued through the trust. Once it reaches 0, no further tokens will be issued through the trust. The default value is null, meaning there is no limit on the number of tokens issued through the trust. If redelegation is enabled it must not be set.

roles (Optional)

body

array

Specifies the subset of the trustor’s roles on the project_id to be granted to the trustee when the token is consumed. The trustor must already be granted these roles in the project referenced by the project_id attribute. If redelegation is used (when trust-scoped token is used and consumed trust has allow_redelegation set to true) this parameter should contain redelegated trust’s roles only.

Roles are only provided when the trust is created, and are subsequently available as a separate read-only collection. Each role can be specified by either id or name.

roles_links

body

object

A roles links object. Includes next, previous, and self links for roles.

links

body

object

A trust links object. Includes next, previous, and self links for trusts.
Status Codes
Success

Code

Reason
200 - OK

Request was successful.
Error

Code

Reason
400 - Bad Request

Some content in the request was invalid.
401 - Unauthorized

User must authenticate before making a request.
403 - Forbidden

Policy does not allow current user to do this operation.
404 - Not Found

The requested resource could not be found.
405 - Method Not Allowed

Method is not valid for this endpoint.
413 - Request Entity Too Large

The request is larger than the server is willing or able to process.
503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.
Example

Status: 200 OK

{
    "trust": {
        "id": "987fe8",
        "expires_at": "2013-02-27T18:30:59.999999Z",
        "impersonation": true,
        "links": {
            "self": "http://example.com/identity/v3/OS-TRUST/trusts/987fe8"
        },
        "roles": [
            {
                "id": "ed7b78",
                "links": {
                    "self": "http://example.com/identity/v3/roles/ed7b78"
                },
                "name": "member"
            }
        ],
        "roles_links": {
            "next": null,
            "previous": null,
            "self": "http://example.com/identity/v3/OS-TRUST/trusts/1ff900/roles"
        },
        "project_id": "0f1233",
        "trustee_user_id": "be34d1",
        "trustor_user_id": "56ae32"
    }
}
DELETE
/v3/OS-TRUST/trusts/{trust_id}

Delete trust

Deletes a trust with {trust_id}.

Relationship: https://docs.openstack.org/api/openstack-identity/3/ext/OS-TRUST/1.0/rel/trust

Request

Parameters

Name

In

Type

Description

trust_id

path

string

The trust ID.

Response

Example

Status: 204 No Content

GET
/v3/OS-TRUST/trusts/{trust_id}/roles

List roles delegated by a trust

Lists roles delegated by a trust with {trust_id}.

Relationship: https://docs.openstack.org/api/openstack-identity/3/ext/OS-TRUST/1.0/rel/trust_roles

Request

Parameters

Name

In

Type

Description

trust_id

path

string

The trust ID.

Response

Status Codes
Success

Code

Reason
200 - OK

Request was successful.
Error

Code

Reason
400 - Bad Request

Some content in the request was invalid.
401 - Unauthorized

User must authenticate before making a request.
403 - Forbidden

Policy does not allow current user to do this operation.
404 - Not Found

The requested resource could not be found.
405 - Method Not Allowed

Method is not valid for this endpoint.
413 - Request Entity Too Large

The request is larger than the server is willing or able to process.
503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.
Example

Status: 200 OK

{
    "roles": [
        {
            "id": "c1648e",
            "links": {
                "self": "http://example.com/identity/v3/roles/c1648e"
            },
            "name": "manager"
        },
        {
            "id": "ed7b78",
            "links": {
                "self": "http://example.com/identity/v3/roles/ed7b78"
            },
            "name": "member"
        }
    ]
}
HEAD
/v3/OS-TRUST/trusts/{trust_id}/roles/{role_id}

Check if a role is delegated by a trust

Checks if a role is delegated by a trust.

Relationship: https://docs.openstack.org/api/openstack-identity/3/ext/OS-TRUST/1.0/rel/trust_role

Request

Parameters

Name

In

Type

Description

trust_id

path

string

The trust ID.

role_id

path

string

The UUID of the role.

Response

Status Codes
Success

Code

Reason
200 - OK

Request was successful.
Error

Code

Reason
400 - Bad Request

Some content in the request was invalid.
401 - Unauthorized

User must authenticate before making a request.
403 - Forbidden

Policy does not allow current user to do this operation.
404 - Not Found

The requested resource could not be found.
405 - Method Not Allowed

Method is not valid for this endpoint.
413 - Request Entity Too Large

The request is larger than the server is willing or able to process.
503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.
Example

Status: 200 OK

GET
/v3/OS-TRUST/trusts/{trust_id}/roles/{role_id}

Get role delegated by a trust

Gets a role with delegated by a trust.

Relationship: https://docs.openstack.org/api/openstack-identity/3/ext/OS-TRUST/1.0/rel/trust_role

Request

Parameters

Name

In

Type

Description

trust_id

path

string

The trust ID.

role_id

path

string

The UUID of the role.

Response

Status Codes
Success

Code

Reason
200 - OK

Request was successful.
Error

Code

Reason
400 - Bad Request

Some content in the request was invalid.
401 - Unauthorized

User must authenticate before making a request.
403 - Forbidden

Policy does not allow current user to do this operation.
404 - Not Found

The requested resource could not be found.
405 - Method Not Allowed

Method is not valid for this endpoint.
413 - Request Entity Too Large

The request is larger than the server is willing or able to process.
503 - Service Unavailable

Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.
Example

Status: 200 OK

{
    "role": {
        "id": "c1648e",
        "links": {
            "self": "http://example.com/identity/v3/roles/c1648e"
        },
        "name": "manager"
    }
}

OS-REVOKE API

This API provides a list of token revocations. Each event expresses a set of criteria which describes a set of tokens that are no longer valid. Requires v3.2+ of the Identity API.

What’s New in v1.1

  • Use of expires_at has been deprecated in favor of using audit_id and audit_chain_id.

  • Revocation events can use audit_id to revoke an individual token.

  • Revocation events can use audit_chain_id to revoke all related tokens. A related token is defined by the first (non-rescoped) token. All tokens in the chain will have the same audit_chain_id.

API Resources

Revocation Events

Revocation events are objects that contain criteria used to evaluate token validity. Tokens that match all the criteria of a revocation event are considered revoked, and should not be accepted as proof of authorization for the user.

Revocation events do not have a unique identifier (id).

GET
/v3/OS-REVOKE/events

List revocation events

Relationship: https://docs.openstack.org/api/openstack-identity/3/ext/OS-REVOKE/1.0/rel/events

List revocation events.

The HTTP Date header returned in the response reflects the timestamp of the most recently issued revocation event. Clients can then use this value in the since query parameter to limit the list of events in subsequent requests.

Request

Parameters

Name

In

Type

Description

since (Optional)

query

string

A timestamp used to limit the list of results to events that occurred on or after the specified time. (RFC 1123 format date time)

Response

Parameters

Name

In

Type

Description

events

body

string

List of recovation events.

issued_before

body

string

(string, ISO 8601 extended format date time with microseconds).

Tokens issued before this time are considered revoked.

This attribute can be used to determine how long the expiration event is valid. It can also be used in queries to filter events, so that only a subset that have occurred since the last request are returned.

user_id

body

string

Revoke tokens expressing the identity of a particular user.

audit_id

body

string

Specifies the unique identifier (UUID) assigned to the token itself.

This will revoke a single token only. This attribute mirrors the use of the Token Revocation List (the mechanism used prior to revocation events) but does not utilize data that could convey authorization (the token id).

If an event is issued for audit_id then the event cannot contain an audit_chain_id.

audit_chain_id

body

string

Specifies a group of tokens based upon the audit_id of the first token in the chain.

If a revocation event specifies the audit_chain_id any token that is part of the token chain (based upon the original token at the start of the chain) will be revoked, including the original token at the start of the chain.

If an event is issued for audit_chain_id then the event cannot contain an audit_id.

domain_id

body

string

Revoke tokens scoped to a particular domain.

project_id

body

string

Revoke tokens scoped to a particular project.

role_id

body

string

Revoke tokens issued with a specific role.

OS-TRUST:trust_id

body

string

Revoke tokens issued as the result of a particular trust, as part of the OS-TRUST API extension.

OS-OAUTH1:consumer_id

body

string

Revoke tokens issued to a specific OAuth consumer, as part of the OS-OAUTH1 API extension.

expires_at

body

string

Specifies the exact expiration time of one or more tokens to be revoked.

This attribute is useful for revoking chains of tokens, such as those produced when re-scoping an existing token. When a token is issued based on initial authentication, it is given an expires_at value. When a token is used to get another token, the new token will have the same expires_at value as the original.
Status Codes
Success

Code

Reason
200 - OK

Request was successful.
Example
{
    "events": [
        {
            "issued_before": "2014-02-27T18:30:59.999999Z",
            "user_id": "f287de"
        },
        {
            "audit_id": "VcxU2JYqT8OzfUVvrjEITQ",
            "issued_before": "2014-02-27T18:30:59.999999Z"
        },
        {
            "audit_chain_id": "VcxU2JYqT8OzfUVvrjEITQ",
            "issued_before": "2014-02-27T18:30:59.999999Z",
            "project_id": "976bf9"
        },
        {
            "domain_id": "be2c70",
            "issued_before": "2014-02-2805:15:59.999999Z",
            "user_id": "f287de"
        }
    ]
}

OS-EP-FILTER API

This API enables the creation of custom catalogs using project scope. The result is the ability to advertise specific endpoints based on the project in use. The association can be done two different ways. The first is by building a direct association between the project and the endpoint, which implies that all tokens scoped to that particular project will receive a specific endpoint, or set of endpoints, in the service catalog. The second is by creating an endpoint group. An endpoint group is a filter that consists of at least one endpoint attribute. By associating a project to an endpoint group, all service catalogs scoped to that project will contain endpoints that match the attributes defined in the endpoint group. Using endpoint groups is a way to dynamically associate an endpoint, or a group of endpoints, to a specific project.

API Resources

Endpoint Group

An endpoint group represents a dynamic collection of service endpoints having the same characteristics, such as service_id, interface, or region_id. Any endpoint attribute could be used as part of a filter.

An example use case would be to give a particular project access to specific service endpoints. When users authenticate for scoped tokens to that project, they are presented with endpoints for the service because the association matched attributes of the endpoints based on the filters. Continuing with this example, let’s assume we want a specific set of endpoints to be advertised in the service catalog for a particular project. We can create an endpoint group to explicitly filter endpoints based on their interface type and service ID.

{
    "endpoint_group": {
        "description": "endpoint group description",
        "filters": {
            "interface": "admin",
            "service_id": "1b501a"
        },
        "name": "endpoint group name"
    }
}

This implies an Endpoint Group that will only return endpoints that have an interface type of admin and correspond to a service with an ID of 1b501a.

POST
/v3/OS-EP-FILTER/endpoint_groups

Create Endpoint Group

Create a new endpoint group filter that represents a dynamic collection of service endpoints having the same characteristics

Relationship: https://docs.openstack.org/api/openstack-identity/3/ext/OS-EP-FILTER/1.0/rel/endpoint_groups

Request

Parameters

Name

In

Type

Description

name

body

string

The name of the endpoint group.

filters

body

object

Describes the filtering performed by the endpoint group. The filter used must be an endpoint property, such as interface, service_id, region_id and enabled. Note that if using interface as a filter, the only available values are public, internal and admin.

description (Optional)

body

string

The endpoint group description.
Example
{
    "endpoint_group": {
        "description": "endpoint group description",
        "filters": {
            "interface": "admin",
            "service_id": "1b501a"
        },
        "name": "endpoint group name"
    }
}

Response

Status Codes
Success

Code

Reason
201 - Created

Resource was created and is ready to use.
Error

Code

Reason
401 - Unauthorized

User must authenticate before making a request.
Example

Status: 201 Created

{
    "endpoint_group": {
        "description": "endpoint group description",
        "filters": {
            "interface": "admin",
            "service_id": "1b501a"
        },
        "id": "ac4861",
        "links": {
            "self": "http://example.com/identity/v3/OS-EP-FILTER/endpoint_groups/ac4861"
        },
        "name": "endpoint group name"
    }
}
GET
/v3/OS-EP-FILTER/endpoint_groups/{endpoint_group_id}

Get Endpoint Group

Show details of an endpoint group.

Relationship: https://docs.openstack.org/api/openstack-identity/3/ext/OS-EP-FILTER/1.0/rel/endpoint_group

Request

Parameters

Name

In

Type

Description

endpoint_group_id

path

string

The UUID of the endpoint group.

Response

Status Codes
Success

Code

Reason
200 - OK

Request was successful.
Error

Code

Reason
401 - Unauthorized

User must authenticate before making a request.
Example

Status: 200 OK

{
    "endpoint_group": {
        "description": "endpoint group description",
        "filters": {
            "interface": "admin",
            "service_id": "1b501a"
        },
        "id": "ac4861",
        "links": {
            "self": "http://example.com/identity/v3/OS-EP-FILTER/endpoint_groups/ac4861"
        },
        "name": "endpoint group name"
    }
}
HEAD
/v3/OS-EP-FILTER/endpoint_groups/{endpoint_group_id}

Check Endpoint Group

Determine if an endpoint group exists.

Relationship: https://docs.openstack.org/api/openstack-identity/3/ext/OS-EP-FILTER/1.0/rel/endpoint_group

Request

Parameters

Name

In

Type

Description

endpoint_group_id

path

string

The UUID of the endpoint group.

Response

Status Codes
Success

Code

Reason
200 - OK

Request was successful.
Error

Code

Reason
401 - Unauthorized

User must authenticate before making a request.
Example

Status: 200 OK

PATCH
/v3/OS-EP-FILTER/endpoint_groups/{endpoint_group_id}

Update Endpoint Group

Modify attributes of an endpoint group.

Relationship: https://docs.openstack.org/api/openstack-identity/3/ext/OS-EP-FILTER/1.0/rel/endpoint_group

Request

Parameters

Name

In

Type

Description

endpoint_group_id

path

string

The UUID of the endpoint group.

name

body

string

The name of the endpoint group.

filters

body

object

Describes the filtering performed by the endpoint group. The filter used must be an endpoint property, such as interface, service_id, region_id and enabled. Note that if using interface as a filter, the only available values are public, internal and admin.

description (Optional)

body

string

The endpoint group description.
Example
{
    "endpoint_group": {
        "filters": {
            "interface": "public"
        }
    }
}

Response

Status Codes
Success

Code

Reason
200 - OK

Request was successful.
Error

Code

Reason
401 - Unauthorized

User must authenticate before making a request.
Example

Status: 200 OK

{
    "endpoint_group": {
        "description": "endpoint group description",
        "filters": {
            "interface": "public",
            "service_id": "1b501a"
        },
        "id": "ac4861",
        "links": {
            "self": "http://example.com/identity/v3/OS-EP-FILTER/endpoint_groups/ac4861"
        },
        "name": "endpoint group name"
    }
}
DELETE
/v3/OS-EP-FILTER/endpoint_groups/{endpoint_group_id}

Delete Endpoint Group

Delete an endpoint group.

Relationship: https://docs.openstack.org/api/openstack-identity/3/ext/OS-EP-FILTER/1.0/rel/endpoint_group

Request

Parameters

Name

In

Type

Description

endpoint_group_id

path

string

The UUID of the endpoint group.

Response

Status Codes
Success

Code

Reason
204 - No Content

The server has fulfilled the request.
Error

Code

Reason
401 - Unauthorized

User must authenticate before making a request.

Status: 204 No Content

GET
/v3/OS-EP-FILTER/endpoint_groups

List Endpoint Groups

List all available endpoint groups.

Relationship: https://docs.openstack.org/api/openstack-identity/3/ext/OS-EP-FILTER/1.0/rel/endpoint_groups

Request

Parameters

Name

In

Type

Description

name (Optional)

query

string

Filters the response by an endpoint group name.

Response

Status Codes
Success

Code

Reason
200 - OK

Request was successful.
Error

Code

Reason
401 - Unauthorized

User must authenticate before making a request.
Example

Status: 200 OK

{
    "endpoint_groups": [
        {
            "endpoint_group": {
                "description": "endpoint group description #1",
                "filters": {
                    "interface": "admin",
                    "service_id": "1b501a"
                },
                "id": "ac4861",
                "links": {
                    "self": "http://example.com/identity/v3/OS-EP-FILTER/endpoint_groups/ac4861"
                },
                "name": "endpoint group name #1"
            }
        },
        {
            "endpoint_group": {
                "description": "endpoint group description #2",
                "filters": {
                    "interface": "admin"
                },
                "id": "3de68c",
                "links": {
                    "self": "http://example.com/identity/v3/OS-EP-FILTER/endpoint_groups/3de68c"
                },
                "name": "endpoint group name #2"
            }
        }
        ],
    "links": {
        "self": "https://example.com/identity/v3/OS-EP-FILTER/endpoint_groups",
        "previous": null,
        "next": null
    }
}

Project and Endpoint Associations

As previously noted, projects can be associated with endpoints either directly or by using endpoint groups. The following API calls describe how to associate a project to a single endpoint and an endpoint group.

PUT
/v3/OS-EP-FILTER/projects/{project_id}/endpoints/{endpoint_id}

Create Association

Creates a direct association between project_id and endpoint_id.

Relationship: https://docs.openstack.org/api/openstack-identity/3/ext/OS-EP-FILTER/1.0/rel/project_endpoint

Request

Parameters

Name

In

Type

Description

project_id

path

string

The UUID of the project.

endpoint_id

path

string

The endpoint ID.

Response

Status Codes
Success

Code

Reason
204 - No Content

The server has fulfilled the request.
Error

Code

Reason
401 - Unauthorized

User must authenticate before making a request.
Example

Status: 204 No Content

HEAD
/v3/OS-EP-FILTER/projects/{project_id}/endpoints/{endpoint_id}

Check Association

Verifies the existence of an association between project_id and endpoint_id.

Relationship: https://docs.openstack.org/api/openstack-identity/3/ext/OS-EP-FILTER/1.0/rel/project_endpoint

Request

Parameters

Name

In

Type

Description

project_id

path

string

The UUID of the project.

endpoint_id

path

string

The endpoint ID.

Response

Status Codes
Success

Code

Reason
204 - No Content

The server has fulfilled the request.
Error

Code

Reason
401 - Unauthorized

User must authenticate before making a request.
Example

Status: 204 No Content

DELETE
/v3/OS-EP-FILTER/projects/{project_id}/endpoints/{endpoint_id}

Delete Association

Removes a direct association between project_id and endpoint_id.

Relationship: https://docs.openstack.org/api/openstack-identity/3/ext/OS-EP-FILTER/1.0/rel/project_endpoint

Request

Parameters

Name

In

Type

Description

project_id

path

string

The UUID of the project.

endpoint_id

path

string

The endpoint ID.

Response

Status Codes
Success

Code

Reason
204 - No Content

The server has fulfilled the request.
Error

Code

Reason
401 - Unauthorized

User must authenticate before making a request.
Example

Status: 204 No Content

GET
/v3/OS-EP-FILTER/projects/{project_id}/endpoints

List Associations by Project

Returns all endpoints that are currently associated with project_id.

Relationship: https://docs.openstack.org/api/openstack-identity/3/ext/OS-EP-FILTER/1.0/rel/project_endpoints

Request

Parameters

Name

In

Type

Description

project_id

path

string

The UUID of the project.

Response

Status Codes
Success

Code

Reason
200 - OK

Request was successful.
Error

Code

Reason
401 - Unauthorized

User must authenticate before making a request.
Example

Status: 200 OK

{
    "endpoints": [
        {
            "id": "6fedc0",
            "interface": "public",
            "url": "http://example.com/identity/",
            "region": "north",
            "links": {
                "self": "http://example.com/identity/v3/endpoints/6fedc0"
            },
            "service_id": "1b501a"
        },
        {
            "id": "6fedc0",
            "interface": "internal",
            "region": "south",
            "url": "http://example.com/identity/",
            "links": {
                "self": "http://example.com/identity/v3/endpoints/6fedc0"
            },
            "service_id": "1b501a"
        }
    ],
    "links": {
        "self": "http://example.com/identity/v3/OS-EP-FILTER/projects/263fd9/endpoints",
        "previous": null,
        "next": null
    }
}
GET
/v3/OS-EP-FILTER/endpoints/{endpoint_id}/projects

List Associations by Endpoint

Returns all projects that are currently associated with endpoint_id.

Relationship: https://docs.openstack.org/api/openstack-identity/3/ext/OS-EP-FILTER/1.0/rel/endpoint_projects

Request

Parameters

Name

In

Type

Description

endpoint_id

path

string

The endpoint ID.

Response

Status Codes
Success

Code

Reason
200 - OK

Request was successful.
Error

Code

Reason
401 - Unauthorized

User must authenticate before making a request.
Example

Status: 200 OK

{
    "projects": [
        {
            "domain_id": "1789d1",
            "enabled": true,
            "id": "263fd9",
            "links": {
                "self": "http://example.com/identity/v3/projects/263fd9"
            },
            "name": "a project name 1",
            "description": "a project description 1"
        },
        {
            "domain_id": "1789d1",
            "enabled": true,
            "id": "61a1b7",
            "links": {
                "self": "http://example.com/identity/v3/projects/61a1b7"
            },
            "name": "a project name 2",
            "description": "a project description 2"
            }
    ],
    "links": {
        "self": "http://example.com/identity/v3/OS-EP-FILTER/endpoints/6fedc0/projects",
        "previous": null,
        "next": null
    }
}

Project and Endpoint Group Associations

Projects can be associated to muliple endpoints by being associated to a single endpoint group. All endpoints that match the filter in the endpoint group will be associated with the project. The following API calls describe how to associate a project to an endpoint group.

PUT
/v3/OS-EP-FILTER/endpoint_groups/{endpoint_group_id}/projects/{project_id}

Create Endpoint Group to Project Association

Creates an association between endpoint_group_id and project_id.

Relationship: https://docs.openstack.org/api/openstack-identity/3/ext/OS-EP-FILTER/1.0/rel/endpoint_group_project

Request

Parameters

Name

In

Type

Description

endpoint_group_id

path

string

The UUID of the endpoint group.

project_id

path

string

The UUID of the project.

Response

Status Codes
Success

Code

Reason
204 - No Content

The server has fulfilled the request.
Error

Code

Reason
401 - Unauthorized

User must authenticate before making a request.
Example

Status: 204 No Content

GET
/v3/OS-EP-FILTER/endpoint_groups/{endpoint_group_id}/projects/{project_id}

Get Endpoint Group to Project Association

Verifies the existence of an association between project_id and endpoint_group_id.

Relationship: https://docs.openstack.org/api/openstack-identity/3/ext/OS-EP-FILTER/1.0/rel/endpoint_group_project

Request

Parameters

Name

In

Type

Description

endpoint_group_id

path

string

The UUID of the endpoint group.

project_id

path

string

The UUID of the project.

Response

Status Codes
Success

Code

Reason
200 - OK

Request was successful.
Error

Code

Reason
401 - Unauthorized

User must authenticate before making a request.
Example

Status: 200 OK

{
    "project": {
        "domain_id": "1789d1",
        "enabled": true,
        "id": "263fd9",
        "links": {
            "self": "http://example.com/identity/v3/projects/263fd9"
        },
        "name": "project name #1",
        "description": "project description #1"
    }
}
HEAD
/v3/OS-EP-FILTER/endpoint_groups/{endpoint_group_id}/projects/{project_id}

Check Endpoint Group to Project Association

Verifies the existence of an association between project_id and endpoint_group_id.

Relationship: https://docs.openstack.org/api/openstack-identity/3/ext/OS-EP-FILTER/1.0/rel/endpoint_group_project

Request

Parameters

Name

In

Type

Description

endpoint_group_id

path

string

The UUID of the endpoint group.

project_id

path

string

The UUID of the project.

Response

Status Codes
Success

Code

Reason
200 - OK

Request was successful.
Error

Code

Reason
401 - Unauthorized

User must authenticate before making a request.
Example

Status: 200 OK

DELETE
/v3/OS-EP-FILTER/endpoint_groups/{endpoint_group_id}/projects/{project_id}

Delete Endpoint Group to Project Association

Removes the association between project_id and endpoint_group_id.

Relationship: https://docs.openstack.org/api/openstack-identity/3/ext/OS-EP-FILTER/1.0/rel/endpoint_group_project

Request

Parameters

Name

In

Type

Description

endpoint_group_id

path

string

The UUID of the endpoint group.

project_id

path

string

The UUID of the project.

Response

Status Codes
Success

Code

Reason
204 - No Content

The server has fulfilled the request.
Error

Code

Reason
401 - Unauthorized

User must authenticate before making a request.
Example

Status: 204 No Content

GET
/v3/OS-EP-FILTER/endpoint_groups/{endpoint_group_id}/projects

List Projects Associated with Endpoint Group

Returns all projects that are currently associated with endpoint_group_id.

Relationship: https://docs.openstack.org/api/openstack-identity/3/ext/OS-EP-FILTER/1.0/rel/endpoint_group_projects

Request

Parameters

Name

In

Type

Description

endpoint_group_id

path

string

The UUID of the endpoint group.

Response

Status Codes
Success

Code

Reason
200 - OK

Request was successful.
Error

Code

Reason
401 - Unauthorized

User must authenticate before making a request.
Example

Status: 200 OK

{
    "projects": [
        {
            "domain_id": "1789d1",
            "enabled": true,
            "id": "263fd9",
            "links": {
                "self": "http://example.com/identity/v3/projects/263fd9"
            },
            "name": "a project name 1",
            "description": "a project description 1"
        },
        {
            "domain_id": "1789d1",
            "enabled": true,
            "id": "61a1b7",
            "links": {
                "self": "http://example.com/identity/v3/projects/61a1b7"
            },
            "name": "a project name 2",
            "description": "a project description 2"
            }
    ],
    "links": {
        "self": "http://example.com/identity/v3/OS-EP-FILTER/endpoints/6fedc0/projects",
        "previous": null,
        "next": null
    }
}
GET
/v3/OS-EP-FILTER/endpoint_groups/{endpoint_group_id}/endpoints

List Endpoints Associated with Endpoint Group

Returns all the endpoints that are currently associated with endpoint_group_id.

Relationship: https://docs.openstack.org/api/openstack-identity/3/ext/OS-EP-FILTER/1.0/rel/endpoint_group_endpoints

Request

Parameters

Name

In

Type

Description

endpoint_group_id

path

string

The UUID of the endpoint group.

Response

Status Codes
Success

Code

Reason
200 - OK

Request was successful.
Error

Code

Reason
401 - Unauthorized

User must authenticate before making a request.
Example

Status: 200 OK

{
    "endpoints": [
        {
            "enabled": true,
            "id": "6fedc0"
            "interface": "admin",
            "legacy_endpoint_id": "6fedc0",
            "links": {
                "self": "http://example.com/identity/v3/endpoints/6fedc0"
            },
            "region": "RegionOne",
            "service_id": "1b501a",
            "url": "http://localhost:9292"
        },
        {
            "enabled": true,
            "id": "b501aa"
            "interface": "internal",
            "legacy_endpoint_id": "b501aa",
            "links": {
                "self": "http://example.com/identity/v3/endpoints/b501aa"
            },
            "region": "RegionOne",
            "service_id": "1b501a",
            "url": "http://localhost:9292"
        },
        {
            "enabled": true,
            "id": "b7c573"
            "interface": "public",
            "legacy_endpoint_id": "b7c573",
            "links": {
                "self": "http://example.com/identity/v3/endpoints/b7c573"
            },
            "region": "RegionOne",
            "service_id": "1b501a",
            "url": "http://localhost:9292"
        }
    ],
    "links": {
        "self": "http://example.com/identity/v3/OS-EP-FILTER/endpoint_groups/{endpoint_group_id}/endpoints",
        "previous": null,
        "next": null
    }
}
GET
/v3/OS-EP-FILTER/projects/{project_id}/endpoint_groups

List Endpoint Groups Associated with Project

Returns all the endpoint groups that are currently associated with project_id.

Relationship: https://docs.openstack.org/api/openstack-identity/3/ext/OS-EP-FILTER/1.0/rel/project_endpoint_groups

Request

Parameters

Name

In

Type

Description

project_id

path

string

The UUID of the project.

Response

Status Codes
Success

Code

Reason
200 - OK

Request was successful.
Error

Code

Reason
401 - Unauthorized

User must authenticate before making a request.
Example

Status: 200 OK

{
    "endpoint_groups": [
        {
            "endpoint_group": {
                "description": "endpoint group description #1",
                "filters": {
                    "interface": "admin",
                    "service_id": "1b501a"
                },
                "id": "ac4861",
                "links": {
                    "self": "http://example.com/identity/v3/OS-EP-FILTER/endpoint_groups/ac4861"
                },
                "name": "endpoint group name #1"
            }
        },
        {
            "endpoint_group": {
                "description": "endpoint group description #2",
                "filters": {
                    "interface": "admin"
                },
                "id": "3de68c",
                "links": {
                    "self": "http://example.com/identity/v3/OS-EP-FILTER/endpoint_groups/3de68c"
                },
                "name": "endpoint group name #2"
            }
        }
        ],
    "links": {
        "self": "https://example.com/identity/v3/OS-EP-FILTER/endpoint_groups",
        "previous": null,
        "next": null
    }
}

OS-FEDERATION API

Provide the ability for users to manage Identity Providers (IdPs) and establish a set of rules to map federation protocol attributes to Identity API attributes. Requires v3.0+ of the Identity API.

What’s New in Version 1.4

Corresponding to Identity API v3.12 release.

  • Added remote_id_attribute as an attribute of a Protocol.

What’s New in Version 1.3

Corresponding to Identity API v3.5 release.

  • Added Identity Provider specific websso routes.

What’s New in Version 1.2

Corresponding to Identity API v3.4 release.

  • Add websso routes.

What’s New in Version 1.1

Corresponding to Identity API v3.3 release. These features are considered stable as of September 4th, 2014.

  • Deprecate list projects and domains in favour of core functionality available in Identity API v3.3.

  • Introduced a mechanism to exchange an Identity Token for a SAML assertion.

  • Introduced a mechanism to retrieve Identity Provider Metadata.

Definitions

  • Trusted Identity Provider: An identity provider set up within the Identity API that is trusted to provide authenticated user information.

  • Service Provider: A system entity that provides services to principals or other system entities, in this case, the OpenStack Identity API is the Service Provider.

  • Attribute Mapping: The user information passed by a federation protocol for an already authenticated identity are called attributes. Those attributes may not align directly with the Identity API concepts. To help overcome such mismatches, a mapping can be done either on the sending side (third party identity provider), on the consuming side (Identity API service), or both.

  • Protocol: A protocol capable of performing federated identity authentication. For example, the OpenID Connect or SAML 2.0 protocols.

API Resources

Identity Providers

/v3/OS-FEDERATION/identity_providers

An Identity Provider (IdP) is a third party service that is trusted by the Identity API to authenticate identities.

Optional attributes:

  • domain_id (string)

    The ID of the domain that is associated with the IdP.

    If a value is not specified by the client, the service will automatically create a domain and associate it to the IdP. The domain_id is not unique so that users can link multiple IdPs to one domain.

  • description (string)

    Describes the identity provider.

    If a value is not specified by the client, the service will default this value to null.

  • enabled (boolean)

    Indicates whether this identity provider should accept federated authentication requests.

    If a value is not specified by the client, the service will default this to false.

  • remote_ids (list)

    Valid remote IdP entity values from Identity Providers. If a value is not specified by the client, the list will be empty.

Protocols

/v3/OS-FEDERATION/identity_providers/{idp_id}/protocols

A protocol entry contains information that dictates which mapping rules to use for a given incoming request. An IdP may have multiple supported protocols.

Required attributes:

  • mapping_id (string)

    Indicates which mapping should be used to process federated authentication requests.

Optional attributes:

  • remote_id_attribute (string)

    Key to obtain the entity ID of the Identity Provider from the HTTPD environment. For mod_shib, this would be Shib-Identity-Provider. For mod_auth_openidc, this could be HTTP_OIDC_ISS. For mod_auth_mellon, this could be MELLON_IDP. This overrides the default value provided in keystone.conf.

Mappings

/v3/OS-FEDERATION/mappings

A mapping is a set of rules to map federation protocol attributes to Identity API objects. An Identity Provider can have a single mapping specified per protocol. A mapping is simply a list of rules.

Required attributes:

  • rules (list of objects)

    Each object contains a rule for mapping attributes to Identity API concepts. A rule contains a remote attribute description and the destination local attribute.

  • local (list of objects)

    References a local Identity API resource, such as a group or user to which the remote attributes will be mapped.

    Each object has one of two structures, as follows.

    To map a remote attribute value directly to a local attribute, identify the local resource type and attribute:

    [
    {
        "local": [
            {
                "user": {
                    "name": "{0}"
                }
            }
        ],
     }
 ]

    If the user attribute is missing when processing an assertion, server tries to directly map REMOTE_USER environment variable. If this variable is also unavailable the server returns an HTTP 401 Unauthorized error.

    If the user has the attribute type set to local as well as a domain specified, the user is treated as existing in the local keystone backend, and the server will attempt to fetch user details (id, name, roles, groups) from the identity backend.

    If, however, the user does not exist in the backend, the server will respond with an appropriate HTTP error code.

    If the type attribute is not set to local in the local rule and no domain is specified, the user is deemed ephemeral and becomes a member of the identity provider’s domain.

    An example of user object mapping to an existing local user:

    [
    {
        "local": [
            {
                 "user": {
                     "name": "username",
                     "type": "local",
                     "domain": {
                         "name": "domain_name"
                     }
                 }
            }
        ],
     }
 ]

    For attribute type and value mapping, identify the local resource type, attribute, and value:

    [
    {
        "local": [
            {
                "group": {
                    "id": "89678b"
                }
            }
        ],
    }
]

    This assigns authorization attributes, by way of role assignments on the specified group, to ephemeral users. The users are not added to the group, but for the duration of the token they will receive the same authorization as if they were.

    [
    {
        "local": [
            {
                "group_ids": "{0}"
            }
        ],
     }
 ]

    It is also possible to map multiple groups by providing a list of group ids. Those group ids can also be white/blacklisted.

  • remote (list of objects)

    At least one object must be included.

    If more than one object is included, the local attribute is applied only if all remote attributes match.

    The value identified by type is always passed through unless a constraint is specified using either any_one_of or not_one_of.

    • type (string)

      This represents an assertion type keyword.

    • any_one_of (list of strings)

      This is mutually exclusive with not_any_of.

      The rule is matched only if any of the specified strings appear in the remote attribute type.

    • not_any_of (list of strings)

      This is mutually exclusive with any_one_of.

      The rule is not matched if any of the specified strings appear in the remote attribute type.

    • regex (boolean)

      If true, then each string will be evaluated as a regular expression search against the remote attribute type.

    The blacklist and whitelist rules are always used in conjunction with type.

    • blacklist (list of strings)

      This is mutually exclusive with whitelist.

      The rule works as a filter, removing any specified strings that are listed there from the remote attribute type.

    • whitelist (list of strings)

      This is mutually exclusive with blacklist.

      The rule works as a filter, allowing only the specified strings in the remote attribute type to be passed ahead.

Service Providers

/v3/OS-FEDERATION/service_providers

A service provider is a third party service that is trusted by the Identity Service.

Required attributes:

  • auth_url (string)

Specifies the protected URL where tokens can be retrieved once the user is authenticated.

  • sp_url (string)

Specifies the URL at the remote peer where assertion should be sent.

Optional attributes:

  • description (string)

Describes the service provider

If a value is not specified by the client, the service may default this value to null.

  • enabled (boolean)

Indicates whether bursting into this service provider is enabled by cloud administrators. If set to false the SP will not appear in the catalog and requests to generate an assertion will result in a 403 error. If a value is not specified by the client, the service will default this to false.

  • relay_state_prefix (string)

Indicates the relay state prefix, used in the ECP wrapped SAML messages, by the Service Provider.

If a value is not specified by the client, the service will default this value to ss:mem:.

APIs

PUT
/v3/OS-FEDERATION/identity_providers/{id}

Register an identity provider

Register an identity provider to be used to authenticate federated users.

Relationship: https://docs.openstack.org/api/openstack-identity/3/ext/OS-FEDERATION/1.0/rel/identity_provider

Request

Parameters

Name

In

Type

Description

authorization_ttl (Optional)

body

integer

The length of validity in minutes for group memberships carried over through mapping and persisted in the database. If left unset, the default value configured in keystone will be used, if enabled.

domain_id

body

string

The ID of a domain that is associated with the Identity Provider. Federated users that authenticate with the Identity Provider will be created under the domain specified.

description (Optional)

body

string

The Identity Provider description

enabled

body

bool

Whether the Identity Provider is enabled or not

id

path

string

The Identity Provider ID

remote_ids

body

array

List of the unique Identity Provider’s remote IDs

As a domain may only be associated to a single identity provider, a 409 response code will be returned if the specified domain_id already maps an existing identity provider.

Example
{
    "identity_provider": {
        "domain_id": "1789d1",
        "description": "Stores ACME identities.",
        "remote_ids": ["acme_id_1", "acme_id_2"],
        "enabled": true
    }
}

Response

Parameters

Name

In

Type

Description

authorization_ttl (Optional)

body

integer

The length of validity in minutes for group memberships carried over through mapping and persisted in the database. If left unset, the default value configured in keystone will be used, if enabled.

domain_id

body

string

The ID of a domain that is associated with the Identity Provider. Federated users that authenticate with the Identity Provider will be created under the domain specified.

description (Optional)

body

string

The Identity Provider description

enabled

body

bool

Whether the Identity Provider is enabled or not

id

body

string

The Identity Provider unique ID

links

body

object

Links containing URI to the Identity Provider resource and its Protocols

remote_ids

body

array

List of the unique Identity Provider’s remote IDs
Status Codes
Success

Code

Reason
201 - Created

Resource was created and is ready to use.
Example
{
    "identity_provider": {
        "domain_id": "1789d1",
        "description": "Stores ACME identities",
        "remote_ids": ["acme_id_1", "acme_id_2"],
        "enabled": true,
        "id": "ACME",
        "links": {
            "protocols": "http://example.com/identity/v3/OS-FEDERATION/identity_providers/ACME/protocols",
            "self": "http://example.com/identity/v3/OS-FEDERATION/identity_providers/ACME"
        }
    }
}
GET
/v3/OS-FEDERATION/identity_providers

List identity providers

List registered identity providers.

Relationship: https://docs.openstack.org/api/openstack-identity/3/ext/OS-FEDERATION/1.0/rel/identity_providers

Request

Parameters

Name

In

Type

Description

id (Optional)

query

string

Filter for Identity Providers’ ID attribute

enabled (Optional)

query

bool

Filter for Identity Providers’ enabled attribute

Response

Parameters

Name

In

Type

Description

identity_providers

body

array

List of Identity Providers
Status Codes
Success

Code

Reason
200 - OK

Request was successful.
Example
{
    "identity_providers": [
        {
            "domain_id": "1789d1",
            "description": "Stores ACME identities",
            "remote_ids": ["acme_id_1", "acme_id_2"],
            "enabled": true,
            "id": "ACME",
            "links": {
                "protocols": "http://example.com/identity/v3/OS-FEDERATION/identity_providers/ACME/protocols",
                "self": "http://example.com/identity/v3/OS-FEDERATION/identity_providers/ACME"
            }
        },
        {
            "domain_id": "2890e2",
            "description": "Stores contractor identities",
            "remote_ids": ["sore_id_1", "store_id_2"],
            "enabled": false,
            "id": "ACME-contractors",
            "links": {
                "protocols": "http://example.com/identity/v3/OS-FEDERATION/identity_providers/ACME-contractors/protocols",
                "self": "http://example.com/identity/v3/OS-FEDERATION/identity_providers/ACME-contractors"
            }
        }
    ],
    "links": {
        "next": null,
        "previous": null,
        "self": "http://example.com/identity/v3/OS-FEDERATION/identity_providers"
    }
}
GET
/v3/OS-FEDERATION/identity_providers/{id}

Get identity provider

Get registered identity providers.

Relationship: https://docs.openstack.org/api/openstack-identity/3/ext/OS-FEDERATION/1.0/rel/identity_provider

Request

Parameters

Name

In

Type

Description

id

path

string

The Identity Provider ID

Response

Parameters

Name

In

Type

Description

authorization_ttl (Optional)

body

integer

The length of validity in minutes for group memberships carried over through mapping and persisted in the database. If left unset, the default value configured in keystone will be used, if enabled.

domain_id

body

string

The ID of a domain that is associated with the Identity Provider. Federated users that authenticate with the Identity Provider will be created under the domain specified.

description (Optional)

body

string

The Identity Provider description

enabled

body

bool

Whether the Identity Provider is enabled or not

id

body

string

The Identity Provider unique ID

links

body

object

Links containing URI to the Identity Provider resource and its Protocols

remote_ids

body

array

List of the unique Identity Provider’s remote IDs
Status Codes
Success

Code

Reason
200 - OK

Request was successful.
Example
{
    "identity_provider": {
        "authorization_ttl": null,
        "domain_id": "1789d1",
        "description": "Stores ACME identities",
        "remote_ids": ["acme_id_1", "acme_id_2"],
        "enabled": false,
        "id": "ACME",
        "links": {
            "protocols": "http://example.com/identity/v3/OS-FEDERATION/identity_providers/ACME/protocols",
            "self": "http://example.com/identity/v3/OS-FEDERATION/identity_providers/ACME"
        }
    }
}
DELETE
/v3/OS-FEDERATION/identity_providers/{id}

Delete identity provider

When an identity provider is deleted, any tokens generated by that identity provider will be revoked.

Relationship: https://docs.openstack.org/api/openstack-identity/3/ext/OS-FEDERATION/1.0/rel/identity_provider

Request

Parameters

Name

In

Type

Description

id

path

string

The Identity Provider ID

Response

Status Codes
Success

Code

Reason
204 - No Content

The server has fulfilled the request.
PATCH
/v3/OS-FEDERATION/identity_providers/{id}

Update identity provider

When an identity provider is disabled, any tokens generated by that identity provider will be revoked.

Relationship: https://docs.openstack.org/api/openstack-identity/3/ext/OS-FEDERATION/1.0/rel/identity_provider

Request

Except domain_id, any attribute of an Identity Provider may be passed in the request body. To update the domain_id, you will need to delete and recreate the Identity Provider. If domain_id is included in the request, a 400 response code will be returned.

Parameters

Name

In

Type

Description

id

path

string

The Identity Provider ID
Example
{
    "identity_provider": {
        "remote_ids": ["beta_id_1", "beta_id_2"],
        "enabled": true
    }
}

Response

Parameters

Name

In

Type

Description

authorization_ttl (Optional)

body

integer

The length of validity in minutes for group memberships carried over through mapping and persisted in the database. If left unset, the default value configured in keystone will be used, if enabled.

domain_id

body

string

The ID of a domain that is associated with the Identity Provider. Federated users that authenticate with the Identity Provider will be created under the domain specified.

description (Optional)

body

string

The Identity Provider description

enabled

body

bool

Whether the Identity Provider is enabled or not

id

body

string

The Identity Provider unique ID

links

body

object

Links containing URI to the Identity Provider resource and its Protocols

remote_ids

body

array

List of the unique Identity Provider’s remote IDs
Status Codes
Success

Code

Reason
200 - OK

Request was successful.
Example
{
    "identity_provider": {
        "authorization_ttl": null,
        "domain_id": "1789d1",
        "description": "Beta dev idp",
        "remote_ids": ["beta_id_1", "beta_id_2"],
        "enabled": true,
        "id": "ACME",
        "links": {
            "protocols": "http://example.com/identity/v3/OS-FEDERATION/identity_providers/ACME/protocols",
            "self": "http://example.com/identity/v3/OS-FEDERATION/identity_providers/ACME"
        }
    }
}
PUT
/v3/OS-FEDERATION/identity_providers/{idp_id}/protocols/{protocol_id}

Add protocol to identity provider

Add a protocol and attribute mapping to an identity provider.

Relationship: https://docs.openstack.org/api/openstack-identity/3/ext/OS-FEDERATION/1.0/rel/identity_provider_protocol

Request

Parameters

Name

In

Type

Description

idp_id

path

string

The Identity Provider ID

protocol_id

path

string

The federation protocol ID

protocol

body

object

The Federation Protocol object
Example
{
    "protocol": {
        "mapping_id": "xyz234"
    }
}

Response

Parameters

Name

In

Type

Description

protocol

body

object

The Federation Protocol object
Status Codes
Success

Code

Reason
201 - Created

Resource was created and is ready to use.
Example
{
    "protocol": {
        "id": "saml2",
        "links": {
            "identity_provider": "http://example.com/identity/v3/OS-FEDERATION/identity_providers/ACME",
            "self": "http://example.com/identity/v3/OS-FEDERATION/identity_providers/ACME/protocols/saml2"
        },
        "mapping_id": "xyz234"
    }
}
GET
/v3/OS-FEDERATION/identity_providers/{id}/protocols

List protocols of identity provider

List all protocol and attribute mappings of an identity provider.

Relationship: https://docs.openstack.org/api/openstack-identity/3/ext/OS-FEDERATION/1.0/rel/identity_provider_protocols

Request

Parameters

Name

In

Type

Description

id

path

string

The Identity Provider ID

Response

Parameters

Name

In

Type

Description

protocols

body

array

List of Federation Protocols

links

body

object

Link containing the URI to the collection of Federation Protocols
Status Codes
Success

Code

Reason
200 - OK

Request was successful.
Example
{
    "links": {
        "next": null,
        "previous": null,
        "self": "http://example.com/identity/v3/OS-FEDERATION/identity_providers/ACME/protocols"
    },
    "protocols": [
        {
            "id": "saml2",
            "links": {
                "identity_provider": "http://example.com/identity/v3/OS-FEDERATION/identity_providers/ACME",
                "self": "http://example.com/identity/v3/OS-FEDERATION/identity_providers/ACME/protocols/saml2"
            },
            "mapping_id": "xyz234"
        }
    ]
}
GET
/v3/OS-FEDERATION/identity_providers/{idp_id}/protocols/{protocol_id}

Get protocol for identity provider

Get a protocol and attribute mapping for an identity provider.

Relationship: https://docs.openstack.org/api/openstack-identity/3/ext/OS-FEDERATION/1.0/rel/identity_provider_protocol

Request

Parameters

Name

In

Type

Description

idp_id

path

string

The Identity Provider ID

protocol_id

path

string

The federation protocol ID

Response

Parameters

Name

In

Type

Description

protocol

body

object

The Federation Protocol object
Status Codes
Success

Code

Reason
200 - OK

Request was successful.
Example
{
    "protocol": {
        "id": "saml2",
        "links": {
            "identity_provider": "http://example.com/identity/v3/OS-FEDERATION/identity_providers/ACME",
            "self": "http://example.com/identity/v3/OS-FEDERATION/identity_providers/ACME/protocols/saml2"
        },
        "mapping_id": "xyz234"
    }
}
PATCH
/v3/OS-FEDERATION/identity_providers/{idp_id}/protocols/{protocol_id}

Update attribute mapping for identity provider

Update the attribute mapping for an identity provider and protocol.

Relationship: https://docs.openstack.org/api/openstack-identity/3/ext/OS-FEDERATION/1.0/rel/identity_provider_protocol

Request

Parameters

Name

In

Type

Description

idp_id

path

string

The Identity Provider ID

protocol_id

path

string

The federation protocol ID

protocol

body

object

The Federation Protocol object
Example
{
    "protocol": {
        "mapping_id": "xyz234"
    }
}

Response

Parameters

Name

In

Type

Description

protocol

body

object

The Federation Protocol object
Status Codes
Success

Code

Reason
200 - OK

Request was successful.
Example
{
    "protocol": {
        "id": "saml2",
        "links": {
            "identity_provider": "http://example.com/identity/v3/OS-FEDERATION/identity_providers/ACME",
            "self": "http://example.com/identity/v3/OS-FEDERATION/identity_providers/ACME/protocols/saml2"
        },
        "mapping_id": "xyz234"
    }
}
DELETE
/v3/OS-FEDERATION/identity_providers/{idp_id}/protocols/{protocol_id}

Delete a protocol from identity provider

Delete a protocol and attribute mapping from an identity provider.

Relationship: https://docs.openstack.org/api/openstack-identity/3/ext/OS-FEDERATION/1.0/rel/identity_provider_protocol

Request

Parameters

Name

In

Type

Description

idp_id

path

string

The Identity Provider ID

protocol_id

path

string

The federation protocol ID

Response

Status Codes
Success

Code

Reason
204 - No Content

The server has fulfilled the request.
PUT
/v3/OS-FEDERATION/mappings/{id}

Create a mapping

Create a federated mapping.

Relationship: https://docs.openstack.org/api/openstack-identity/3/ext/OS-FEDERATION/1.0/rel/mapping

Request

Parameters

Name

In

Type

Description

id

path

string

The Federation Mapping unique ID

rules

body

object

The list of rules used to map remote users into local users
Example
{
    "mapping": {
        "rules": [
            {
                "local": [
                    {
                        "user": {
                            "name": "{0}"
                        }
                    },
                    {
                        "group": {
                            "id": "0cd5e9"
                        }
                    }
                ],
                "remote": [
                    {
                        "type": "UserName"
                    },
                    {
                        "type": "orgPersonType",
                        "not_any_of": [
                            "Contractor",
                            "Guest"
                        ]
                    }
                ]
            }
        ]
    }
}

Response

Parameters

Name

In

Type

Description

id

body

string

The Federation Mapping unique ID

links

body

object

Link to the URI where the mapping is located

rules

body

object

The list of rules used to map remote users into local users
Status Codes
Success

Code

Reason
201 - Created

Resource was created and is ready to use.
Example
{
    "mapping": {
        "id": "ACME",
        "links": {
            "self": "http://example.com/identity/v3/OS-FEDERATION/mappings/ACME"
        },
        "rules": [
            {
                "local": [
                    {
                        "user": {
                            "name": "{0}"
                        }
                    },
                    {
                        "group": {
                            "id": "0cd5e9"
                        }
                    }
                ],
                "remote": [
                    {
                        "type": "UserName"
                    },
                    {
                        "type": "orgPersonType",
                        "not_any_of": [
                            "Contractor",
                            "Guest"
                        ]
                    }
                ]
            }
        ]
    }
}
GET
/v3/OS-FEDERATION/mappings/{id}

Get a mapping

Get a specific federated mapping.

Relationship: https://docs.openstack.org/api/openstack-identity/3/ext/OS-FEDERATION/1.0/rel/mapping

Request

Parameters

Name

In

Type

Description

id

path

string

The Federation Mapping unique ID

Response

Parameters

Name

In

Type

Description

id

body

string

The Federation Mapping unique ID

links

body

object

Link to the URI where the mapping is located

rules

body

object

The list of rules used to map remote users into local users
Status Codes
Success

Code

Reason
200 - OK

Request was successful.
Example
{
    "mapping": {
        "id": "ACME",
        "links": {
            "self": "http://example.com/identity/v3/OS-FEDERATION/mappings/ACME"
        },
        "rules": [
            {
                "local": [
                    {
                        "user": {
                            "name": "{0}"
                        }
                    },
                    {
                        "group": {
                            "id": "0cd5e9"
                        }
                    }
                ],
                "remote": [
                    {
                        "type": "UserName"
                    },
                    {
                        "type": "orgPersonType",
                        "not_any_of": [
                            "Contractor",
                            "Guest"
                        ]
                    }
                ]
            }
        ]
    }
}
PATCH
/v3/OS-FEDERATION/mappings/{id}

Update a mapping

Update a federated mapping.

Relationship: https://docs.openstack.org/api/openstack-identity/3/ext/OS-FEDERATION/1.0/rel/mapping

Request

Parameters

Name

In

Type

Description

id

path

string

The Federation Mapping unique ID

rules

body

object

The list of rules used to map remote users into local users
Example
{
    "mapping": {
        "rules": [
            {
                "local": [
                    {
                        "user": {
                            "name": "{0}"
                        }
                    },
                    {
                        "group": {
                            "id": "0cd5e9"
                        }
                    }
                ],
                "remote": [
                    {
                        "type": "UserName"
                    },
                    {
                        "type": "orgPersonType",
                        "any_one_of": [
                            "Contractor",
                            "SubContractor"
                        ]
                    }
                ]
            }
        ]
    }
}

Response

Parameters

Name

In

Type

Description

id

body

string

The Federation Mapping unique ID

links

body

object

Link to the URI where the mapping is located

rules

body

object

The list of rules used to map remote users into local users
Status Codes
Success

Code

Reason
200 - OK

Request was successful.
Example
{
    "mapping": {
        "id": "ACME",
        "links": {
            "self": "http://example.com/identity/v3/OS-FEDERATION/mappings/ACME"
        },
        "rules": [
            {
                "local": [
                    {
                        "user": {
                            "name": "{0}"
                        }
                    },
                    {
                        "group": {
                            "id": "0cd5e9"
                        }
                    }
                ],
                "remote": [
                    {
                        "type": "UserName"
                    },
                    {
                        "type": "orgPersonType",
                        "any_one_of": [
                            "Contractor",
                            "SubContractor"
                        ]
                    }
                ]
            }
        ]
    }
}
GET
/v3/OS-FEDERATION/mappings

List mappings

List all federated mappings.

Relationship: https://docs.openstack.org/api/openstack-identity/3/ext/OS-FEDERATION/1.0/rel/mappings

Response

Parameters

Name

In

Type

Description

links

body

object

Link to the URI where the mapping collection is located

mappings

body

array

The collection of Federation Mappings
Status Codes
Success

Code

Reason
200 - OK

Request was successful.
Example
{
    "links": {
        "next": null,
        "previous": null,
        "self": "http://example.com/identity/v3/OS-FEDERATION/mappings"
    },
    "mappings": [
        {
            "id": "ACME",
            "links": {
                "self": "http://example.com/identity/v3/OS-FEDERATION/mappings/ACME"
            },
            "rules": [
                {
                    "local": [
                        {
                            "user": {
                                "name": "{0}"
                            }
                        },
                        {
                            "group": {
                                "id": "0cd5e9"
                            }
                        }
                    ],
                    "remote": [
                        {
                            "type": "UserName"
                        },
                        {
                            "type": "orgPersonType",
                            "any_one_of": [
                                "Contractor",
                                "SubContractor"
                            ]
                        }
                    ]
                }
            ]
        }
    ]
}
DELETE
/v3/OS-FEDERATION/mappings/{id}

Delete a mapping

Remove a specific federated mapping.

Relationship: https://docs.openstack.org/api/openstack-identity/3/ext/OS-FEDERATION/1.0/rel/mapping

Request

Parameters

Name

In

Type

Description

id

path

string

The Federation Mapping unique ID
Status Codes
Success

Code

Reason
204 - No Content

The server has fulfilled the request.
PUT
/v3/OS-FEDERATION/service_providers/{id}

Register a service provider

Create a service provider entity.

Relationship: https://docs.openstack.org/api/openstack-identity/3/ext/OS-FEDERATION/1.0/rel/service_provider

Request

Parameters

Name

In

Type

Description

auth_url

body

string

The URL to authenticate against

description (Optional)

body

string

The description of the Service Provider

enabled

body

bool

Whether the Service Provider is enabled or not

id

path

string

The Service Provider unique ID

sp_url

body

string

The Service Provider’s URL
Example
{
    "service_provider": {
        "auth_url": "https://example.com/identity/v3/OS-FEDERATION/identity_providers/acme/protocols/saml2/auth",
        "description": "Remote Service Provider",
        "enabled": true,
        "sp_url": "https://example.com/identity/Shibboleth.sso/SAML2/ECP"
    }
}

Response

Parameters

Name

In

Type

Description

auth_url

body

string

The URL to authenticate against

description (Optional)

body

string

The description of the Service Provider

enabled

body

bool

Whether the Service Provider is enabled or not

id

body

string

The Service Provider unique ID

links

body

string

Link to the URI where the Service Provider is located

relay_state_prefix

body

string

The prefix of the RelayState SAML attribute

sp_url

body

string

The Service Provider’s URL
Status Codes
Success

Code

Reason
201 - Created

Resource was created and is ready to use.
Example
{
    "service_provider": {
        "auth_url": "https://example.com/identity/v3/OS-FEDERATION/identity_providers/acme/protocols/saml2/auth",
        "description": "Remote Service Provider",
        "enabled": true,
        "id": "ACME",
        "links": {
            "self": "https://example.com/identity/v3/OS-FEDERATION/service_providers/ACME"
        },
        "relay_state_prefix": "ss:mem:",
        "sp_url": "https://example.com/identity/Shibboleth.sso/SAML2/ECP"
    }
}
GET
/v3/OS-FEDERATION/service_providers

List service providers

List all service providers.

Relationship: https://docs.openstack.org/api/openstack-identity/3/ext/OS-FEDERATION/1.0/rel/service_providers

Response

Parameters

Name

In

Type

Description

links

body

string

Link to the URI where the Service Provider collection is located

service_providers

body

array

The list of Service Providers
Status Codes
Success

Code

Reason
200 - OK

Request was successful.
Example
{
    "links": {
        "next": null,
        "previous": null,
        "self": "http://example.com/identity/v3/OS-FEDERATION/service_providers"
    },
    "service_providers": [
        {
            "auth_url": "https://example.com/identity/v3/OS-FEDERATION/identity_providers/acme/protocols/saml2/auth",
            "description": "Stores ACME identities",
            "enabled": true,
            "id": "ACME",
            "links": {
                "self": "http://example.com/identity/v3/OS-FEDERATION/service_providers/ACME"
            },
            "relay_state_prefix": "ss:mem:",
            "sp_url": "https://example.com/identity/Shibboleth.sso/SAML2/ECP"
        },
        {
            "auth_url": "https://other.example.com/identity/v3/OS-FEDERATION/identity_providers/acme/protocols/saml2/auth",
            "description": "Stores contractor identities",
            "enabled": false,
            "id": "ACME-contractors",
            "links": {
                "self": "http://example.com/identity/v3/OS-FEDERATION/service_providers/ACME-contractors"
            },
            "relay_state_prefix": "ss:mem:",
            "sp_url": "https://other.example.com/identity/Shibboleth.sso/SAML2/ECP"
        }
    ]
}
GET
/v3/OS-FEDERATION/service_providers/{id}

Get service provider

Get a specific service provider reference.

Relationship: https://docs.openstack.org/api/openstack-identity/3/ext/OS-FEDERATION/1.0/rel/service_provider

Request

Parameters

Name

In

Type

Description

id

path

string

The Service Provider unique ID

Response

Parameters

Name

In

Type

Description

auth_url

body

string

The URL to authenticate against

description (Optional)

body

string

The description of the Service Provider

enabled

body

bool

Whether the Service Provider is enabled or not

id

body

string

The Service Provider unique ID

links

body

string

Link to the URI where the Service Provider is located

relay_state_prefix

body

string

The prefix of the RelayState SAML attribute

sp_url

body

string

The Service Provider’s URL
Status Codes
Success

Code

Reason
200 - OK

Request was successful.
Example
{
    "service_provider": {
        "auth_url": "https://example.com/identity/v3/OS-FEDERATION/identity_providers/acme/protocols/saml2/auth",
        "description": "Remote Service Provider",
        "enabled": true,
        "id": "ACME",
        "links": {
            "self": "https://example.com/identity/v3/OS-FEDERATION/service_providers/ACME"
        },
        "relay_state_prefix": "ss:mem:",
        "sp_url": "https://example.com/identity/Shibboleth.sso/SAML2/ECP"
    }
}
DELETE
/v3/OS-FEDERATION/service_providers/{id}

Delete service provider

Delete a service provider.

Relationship: https://docs.openstack.org/api/openstack-identity/3/ext/OS-FEDERATION/1.0/rel/service_provider

Request

Parameters

Name

In

Type

Description

id

path

string

The Service Provider unique ID

Response

Status Codes
Success

Code

Reason
204 - No Content

The server has fulfilled the request.
PATCH
/v3/OS-FEDERATION/service_providers/{id}

Update service provider

Update a service provider’s attributes.

Relationship: https://docs.openstack.org/api/openstack-identity/3/ext/OS-FEDERATION/1.0/rel/service_provider

Request

Parameters

Name

In

Type

Description

id

path

string

The Service Provider unique ID

auth_url

body

string

The URL to authenticate against

description (Optional)

body

string

The description of the Service Provider

enabled

body

bool

Whether the Service Provider is enabled or not

sp_url

body

string

The Service Provider’s URL
Example
{
    "service_provider": {
        "auth_url": "https://new.example.com/identity/v3/OS-FEDERATION/identity_providers/protocol/saml2/auth",
        "enabled": true,
        "relay_state_prefix": "ss:temp:",
        "sp_auth": "https://new.example.com/identity/Shibboleth.sso/SAML2/ECP"
    }
}

Response

Parameters

Name

In

Type

Description

auth_url

body

string

The URL to authenticate against

description (Optional)

body

string

The description of the Service Provider

enabled

body

bool

Whether the Service Provider is enabled or not

id

body

string

The Service Provider unique ID

links

body

string

Link to the URI where the Service Provider is located

relay_state_prefix

body

string

The prefix of the RelayState SAML attribute

sp_url

body

string

The Service Provider’s URL
Status Codes
Success

Code

Reason
200 - OK

Request was successful.
Example
{
    "service_provider": {
        "auth_url": "https://new.example.com/identity/v3/OS-FEDERATION/identity_providers/protocol/saml2/auth",
        "description": "Remote Service Provider",
        "enabled": true,
        "id": "ACME",
        "links": {
            "self": "https://example.com/identity/v3/OS-FEDERATION/service_providers/ACME"
        },
        "relay_state_prefix": "ss:temp:",
        "sp_url": "https://new.example.com/identity/Shibboleth.sso/SAML2/ECP"
    }
}
GET
/v3/OS-FEDERATION/projects

List projects a federated user can access

Deprecated in v1.1. Use core GET /auth/projects. This call has the same response format.

Returns a collection of projects to which the federated user has authorization to access. To access this resource, an unscoped token is used, the user can then select a project and request a scoped token. Note that only enabled projects will be returned.

Relationship: https://docs.openstack.org/api/openstack-identity/3/ext/OS-FEDERATION/1.0/rel/projects

Response

Parameters

Name

In

Type

Description

links

body

object

Link to the URI where the project collection is located

projects

body

array

The list of projects the authenticated user may scope to
Status Codes
Success

Code

Reason
200 - OK

Request was successful.
Example
{
    "projects": [
        {
            "domain_id": "37ef61",
            "enabled": true,
            "id": "12d706",
            "links": {
                "self": "http://example.com/identity/v3/projects/12d706"
            },
            "name": "a project name"
        },
        {
            "domain_id": "37ef61",
            "enabled": true,
            "id": "9ca0eb",
            "links": {
                "self": "http://example.com/identity/v3/projects/9ca0eb"
            },
            "name": "another project"
        }
    ],
    "links": {
        "self": "http://example.com/identity/v3/OS-FEDERATION/projects",
        "previous": null,
        "next": null
    }
}
GET
/v3/OS-FEDERATION/domains

List domains a federated user can access

Deprecated in v1.1. Use core GET /auth/domains. This call has the same response format.

Returns a collection of domains to which the federated user has authorization to access. To access this resource, an unscoped token is used, the user can then select a domain and request a scoped token. Note that only enabled domains will be returned.

Relationship: https://docs.openstack.org/api/openstack-identity/3/ext/OS-FEDERATION/1.0/rel/domains

Response

Parameters

Name

In

Type

Description

domains

body

array

The list of domains the authenticated user may scope to

links

body

object

Link to the URI where the domain collection is located
Status Codes
Success

Code

Reason
200 - OK

Request was successful.
Example
{
    "domains": [
        {
            "description": "desc of domain",
            "enabled": true,
            "id": "37ef61",
            "links": {
                "self": "http://example.com/identity/v3/domains/37ef61"
            },
            "name": "my domain"
        }
    ],
    "links": {
        "self": "http://example.com/identity/v3/OS-FEDERATION/domains",
        "previous": null,
        "next": null
    }
}
GET
/v3/OS-FEDERATION/identity_providers/{idp_id}/protocols/{protocol_id}/auth

Request an unscoped OS-FEDERATION token

A federated ephemeral user may request an unscoped token, which can be used to get a scoped token.

If the user is mapped directly (mapped to an existing user), a standard, unscoped token will be issued.

Due to the fact that this part of authentication is strictly connected with the SAML2 authentication workflow, a client should not send any data, as the content may be lost when a client is being redirected between Service Provider and Identity Provider. Both HTTP methods - GET and POST should be allowed as Web Single Sign-On (WebSSO) and Enhanced Client Proxy (ECP) mechanisms have different authentication workflows and use different HTTP methods while accessing protected endpoints.

The returned token will contain information about the groups to which the federated user belongs.

Relationship: https://docs.openstack.org/api/openstack-identity/3/ext/OS-FEDERATION/1.0/rel/identity_provider_protocol_auth

Request

Parameters

Name

In

Type

Description

idp_id

path

string

Identity Provider’s unique ID

protocol_id

path

string

Federation Protocol’s unique ID

Response

Parameters

Name

In

Type

Description

X-Subject-Token

header

string

The authentication token. An authentication response returns the token ID in this header rather than in the response body.

token

body

object

Federation unscoped token containing methods and user information
Example
{
    "token": {
        "methods": [
            "mapped"
        ],
        "user": {
            "domain": {
                "id": "Federated"
            },
            "id": "username%40example.com",
            "name": "username@example.com",
            "OS-FEDERATION": {
                "identity_provider": "ACME",
                "protocol": "SAML",
                "groups": [
                    {"id": "abc123"},
                    {"id": "bcd234"}
                ]
            }
        }
    }
}
POST
/v3/auth/tokens

Request a scoped OS-FEDERATION token

A federated user may request a scoped token, by using the unscoped token. A project or domain may be specified by either id or name. An id is sufficient to uniquely identify a project or domain.

Relationship: https://docs.openstack.org/api/openstack-identity/3/rel/auth_tokens

Request

Parameters

Name

In

Type

Description

auth

body

object

Auth data containing user’s identity and scope information
Example
{
    "auth": {
        "identity": {
            "methods": [
                "token"
            ],
            "token": {
                "id": "--federated-token-id--"
            }
        },
        "scope": {
            "project": {
                "id": "263fd9"
            }
        }
    }
}

Similarly to the returned unscoped token, the returned scoped token will have an OS-FEDERATION section added to the user portion of the token.

Response

Parameters

Name

In

Type

Description

X-Subject-Token

header

string

The authentication token. An authentication response returns the token ID in this header rather than in the response body.

token

body

object

Federation scoped token containing methods, roles, user, scope, catalog, issuance and expiry information
Example
{
    "token": {
        "methods": [
            "token"
        ],
        "roles": [
            {
                "id": "36a8989f52b24872a7f0c59828ab2a26",
                "name": "admin"
            }
        ],
        "expires_at": "2014-08-06T13:43:43.367202Z",
        "project": {
            "domain": {
                "id": "1789d1",
                "links": {
                    "self": "http://example.com/identity/v3/domains/1789d1"
                },
                "name": "example.com"
            },
            "id": "263fd9",
            "links": {
                "self": "http://example.com/identity/v3/projects/263fd9"
            },
            "name": "project-x"
        },
        "catalog": [
            {
                "endpoints": [
                    {
                        "id": "39dc322ce86c4111b4f06c2eeae0841b",
                        "interface": "public",
                        "region": "RegionOne",
                        "url": "http://example.com/identity"
                    },
                    {
                        "id": "ec642f27474842e78bf059f6c48f4e99",
                        "interface": "internal",
                        "region": "RegionOne",
                        "url": "http://example.com/identity"
                    },
                    {
                        "id": "c609fc430175452290b62a4242e8a7e8",
                        "interface": "admin",
                        "region": "RegionOne",
                        "url": "http://example.com/identity"
                    }
                ],
                "id": "266c2aa381ea46df81bb05ddb02bd14a",
                "name": "keystone",
                "type": "identity"
            }
        ],
        "user": {
            "domain": {
                "id": "Federated"
            },
            "id": "username%40example.com",
            "name": "username@example.com",
            "OS-FEDERATION": {
                "identity_provider": "ACME",
                "protocol": "SAML",
                "groups": [
                    {"id": "abc123"},
                    {"id": "bcd234"}
                ]
            }
        },
        "issued_at": "2014-08-06T12:43:43.367288Z"
    }
}
GET
/v3/auth/OS-FEDERATION/websso/{protocol_id}?origin=https%3A//horizon.example.com

Web Single Sign On authentication (New in version 1.2)

For Web Single Sign On (WebSSO) authentication, users are expected to enter another URL endpoint. Upon successful authentication, instead of issuing a standard unscoped token, keystone will issue JavaScript code that redirects the web browser to the originating Horizon. An unscoped federated token will be included in the form being sent.

Request

Parameters

Name

In

Type

Description

protocol_id

path

string

Federation Protocol’s unique ID
GET
/v3/auth/OS-FEDERATION/identity_providers/{idp_id}/protocol/{protocol_id}/websso?origin=https%3A//horizon.example.com

Web Single Sign On authentication (New in version 1.3)

In contrast to the above route, this route begins a Web Single Sign On request that is specific to the supplied Identity Provider and Protocol. Keystone will issue JavaScript that handles redirections in the same way as the other route. An unscoped federated token will be included in the form being sent.

Request

Parameters

Name

In

Type

Description

idp_id

path

string

Identity Provider’s unique ID

protocol_id

path

string

Federation Protocol’s unique ID

New in version 1.1

POST
/v3/auth/OS-FEDERATION/saml2

Generate a SAML assertion

A user may generate a SAML assertion document based on the scoped token that is used in the request.

Request Parameters:

To generate a SAML assertion, a user must provides a scoped token ID and Service Provider ID in the request body.

Relationship: https://docs.openstack.org/api/openstack-identity/3/ext/OS-FEDERATION/1.0/rel/saml2

Request

Parameters

Name

In

Type

Description

auth

body

object

Auth data with user’s identity and Service Provider scope information
Example
{
    "auth": {
        "identity": {
            "methods": [
                "token"
            ],
            "token": {
                "id": "--token_id--"
            }
        },
        "scope": {
            "service_provider": {
                "id": "--sp_id--"
            }
        }
    }
}

The response will be a full SAML assertion. Note that for readability the certificate has been truncated. Server will also set two HTTP headers: X-sp-url and X-auth-url. The former is the URL where assertion should be sent, whereas the latter remote URL where token will be issued once the client is finally authenticated.

Response

Parameters

Name

In

Type

Description

Headers

body

object

XML headers

xml

body

object

SAML assertion in XML format
Example
Headers:
    Content-Type: text/xml
    X-sp-url: http://beta.example.com/Shibboleth.sso/POST/ECP
    X-auth-url: http://beta.example.com/identity/v3/OS-FEDERATION/identity_providers/beta/protocols/auth

<?xml version="1.0" encoding="UTF-8"?>
<ns0:Response xmlns:ns0="urn:oasis:names:tc:SAML:2.0:protocol" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" xmlns:xmldsig="http://www.w3.org/2000/09/xmldsig#" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" Destination="http://beta.example.com/Shibboleth.sso/POST/ECP" ID="818dee98a5d44a238ae3038d26cbebb6" IssueInstant="2015-05-27T13:23:48Z" Version="2.0">
<saml:Issuer Format="urn:oasis:names:tc:SAML:2.0:nameid-format:entity">http://keystone.idp/v3/OS-FEDERATION/saml2/idp</saml:Issuer>
<ns0:Status>
    <ns0:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success"/>
</ns0:Status>
<saml:Assertion ID="68237000470e47a690bdd513bb264460" IssueInstant="2015-05-27T13:23:47Z" Version="2.0">
    <saml:Issuer Format="urn:oasis:names:tc:SAML:2.0:nameid-format:entity">http://keystone.idp/v3/OS-FEDERATION/saml2/idp</saml:Issuer>
    <xmldsig:Signature>
        <xmldsig:SignedInfo>
            <xmldsig:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
            <xmldsig:SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/>
            <xmldsig:Reference URI="#68237000470e47a690bdd513bb264460">
                <xmldsig:Transforms>
                    <xmldsig:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
                    <xmldsig:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
                </xmldsig:Transforms>
                <xmldsig:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
                <xmldsig:DigestValue>IgfoWcCoBpmv64ianaK/qj63QQQ=</xmldsig:DigestValue>
            </xmldsig:Reference>
        </xmldsig:SignedInfo>
        <xmldsig:SignatureValue>H6GvkAcDW0BSoBaktpVTxUFtvUAcFMXRqYXLFvmse5DeOSnByvGOgW/yJMjIqzwG
        LjCqJXYMePIkEUYb4kqbbkN1wNFuxKtmACcC3T3/7rAavrIz3I4cT6mCipN9qFlE
        tzR0mD2IZhExuTzyMaON8krTWWoddx8LIYEfQ03O4eSYObi5fHmGJRGs9D5De0aK
        XkIeKo7HRAjZsU5fAMGlEKfazemTZMBbnpUD//oFsxf1yFcFTOyiAHddAaG7Rqv3
        4SYjYo4dRKAI/yQuA+MVmHDcJUE+KVqVoJZJSVJe+Lz+X1ReRlEgvP0mhaM0yY+R
        w7FozqQyKSKJW9abmxJTFQ==</xmldsig:SignatureValue>
        <xmldsig:KeyInfo>
            <xmldsig:X509Data>
                <xmldsig:X509Certificate>...</xmldsig:X509Certificate>
            </xmldsig:X509Data>
        </xmldsig:KeyInfo>
    </xmldsig:Signature>
    <saml:Subject>
        <saml:NameID>admin</saml:NameID>
        <saml:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
            <saml:SubjectConfirmationData NotOnOrAfter="2015-05-27T14:23:47.711682Z" Recipient="http://beta.example.com/Shibboleth.sso/POST/ECP/">
        </saml:SubjectConfirmation>
    </saml:Subject>
    <saml:AuthnStatement AuthnInstant="2015-05-27T13:23:47Z" SessionIndex="cd839a3ff0fc4a4aab52e55fae8094a2" SessionNotOnOrAfter="2015-05-27T14:23:47.711682Z">
        <saml:AuthnContext>
            <saml:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:Password</saml:AuthnContextClassRef>
            <saml:AuthenticatingAuthority>http://keystone.idp/v3/OS-FEDERATION/saml2/idp</saml:AuthenticatingAuthority>
        </saml:AuthnContext>
    </saml:AuthnStatement>
    <saml:AttributeStatement>
        <saml:Attribute Name="openstack_user" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
            <saml:AttributeValue xsi:type="xs:string">admin</saml:AttributeValue>
        </saml:Attribute>
        <saml:Attribute Name="openstack_user_domain" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
            <saml:AttributeValue xsi:type="xs:string">Default</saml:AttributeValue>
        </saml:Attribute>
        <saml:Attribute Name="openstack_roles" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
            <saml:AttributeValue xsi:type="xs:string">admin</saml:AttributeValue>
        </saml:Attribute>
        <saml:Attribute Name="openstack_project" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
            <saml:AttributeValue xsi:type="xs:string">admin</saml:AttributeValue>
        </saml:Attribute>
        <saml:Attribute Name="openstack_project_domain" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
            <saml:AttributeValue xsi:type="xs:string">Default</saml:AttributeValue>
        </saml:Attribute>
    </saml:AttributeStatement>
</saml:Assertion>
</ns0:Response>

For more information about how a SAML assertion is structured, refer to the specification.

POST
/v3/auth/OS-FEDERATION/saml2/ecp

Generate an ECP wrapped SAML assertion

A user may generate a SAML assertion document to work with the Enhanced Client or Proxy (ECP) profile based on the scoped token that is used in the request.

Request Parameters:

To generate an ECP wrapped SAML assertion, a user must provides a scoped token ID and Service Provider ID in the request body.

Relationship: https://docs.openstack.org/api/openstack-identity/3/ext/OS-FEDERATION/1.0/rel/saml2/ecp

Request

Parameters

Name

In

Type

Description

auth

body

object

Auth data with user’s identity and Service Provider scope information
Example
{
    "auth": {
        "identity": {
            "methods": [
                "token"
            ],
            "token": {
                "id": "--token_id--"
            }
        },
        "scope": {
            "service_provider": {
                "id": "--sp_id--"
            }
        }
    }
}

The response will be an ECP wrapped SAML assertion. Note that for readability the certificate has been truncated. Server will also set two HTTP headers: X-sp-url and X-auth-url. The former is the URL where assertion should be sent, whereas the latter remote URL where token will be issued once the client is finally authenticated.

Response

Parameters

Name

In

Type

Description

Headers

body

object

XML headers

xml

body

object

SAML assertion in XML format
Example
Headers:
    Content-Type: text/xml
    X-sp-url: http://beta.example.com/Shibboleth.sso/POST/ECP
    X-auth-url: http://beta.example.com/identity/v3/OS-FEDERATION/identity_providers/beta/protocols/auth

<?xml version='1.0' encoding='UTF-8'?>
<ns0:Envelope
    xmlns:ns0="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:ns1="urn:oasis:names:tc:SAML:2.0:profiles:SSO:ecp"
    xmlns:ns2="urn:oasis:names:tc:SAML:2.0:protocol"
    xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
    xmlns:xmldsig="http://www.w3.org/2000/09/xmldsig#"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <ns0:Header>
        <ns1:RelayState ns0:actor="http://schemas.xmlsoap.org/soap/actor/next" ns0:mustUnderstand="1">ss:mem:1ddfe8b0f58341a5a840d2e8717b0737</ns1:RelayState>
    </ns0:Header>
    <ns0:Body>
        <ns2:Response Destination="http://beta.example.com/Shibboleth.sso/POST/ECP" ID="8c21de08d2f2435c9acf13e72c982846" IssueInstant="2015-03-25T14:43:21Z" Version="2.0">
            <saml:Issuer Format="urn:oasis:names:tc:SAML:2.0:nameid-format:entity">http://keystone.idp/v3/OS-FEDERATION/saml2/idp</saml:Issuer>
            <ns2:Status>
                <ns2:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success" />
            </ns2:Status>
            <saml:Assertion ID="a5f02efb0bff4044b294b4583c7dfc5d" IssueInstant="2015-03-25T14:43:21Z" Version="2.0">
                <saml:Issuer Format="urn:oasis:names:tc:SAML:2.0:nameid-format:entity">http://keystone.idp/v3/OS-FEDERATION/saml2/idp</saml:Issuer>
                <xmldsig:Signature>
                    <xmldsig:SignedInfo>
                        <xmldsig:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#" />
                        <xmldsig:SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1" />
                        <xmldsig:Reference URI="#a5f02efb0bff4044b294b4583c7dfc5d">
                            <xmldsig:Transforms>
                                <xmldsig:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature" />
                                <xmldsig:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#" />
                            </xmldsig:Transforms>
                            <xmldsig:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1" />
                            <xmldsig:DigestValue>0KH2CxdkfzU+6eiRhTC+mbObUKI=</xmldsig:DigestValue>
                        </xmldsig:Reference>
                    </xmldsig:SignedInfo>
                    <xmldsig:SignatureValue>m2jh5gDvX/1k+4uKtbb08CHp2b9UWsLwjtMijs9C9gZV2dIJKiF9SJBWE4C79qT4
uktgeB0RQiFrgxOGfpp1gyQunmNyZcipcetOk4PebH4/z+po/59w8oGp89fPfdRj
WhWA0fWP32Pr5eslRQjbHnSRTFMp3ycBZHsCCsTWdhyiWC6aERsspHeeGjkzxRAZ
HxJ8oLMj/TWBJ2iaUDUT6cxa1svmtumoC3GPPOreuGELXTL5MtKotTVqYN6lZP8B
Ueaji11oRI1HE9XMuPu0iYlSo1i3JyejciSFgplgdHsebpM29PMo8oz2TCybY39p
kmuD4y9XX3lRBcpJRxku7w==</xmldsig:SignatureValue>
                    <xmldsig:KeyInfo>
                        <xmldsig:X509Data>
                            <xmldsig:X509Certificate>...</xmldsig:X509Certificate>
                        </xmldsig:X509Data>
                    </xmldsig:KeyInfo>
                </xmldsig:Signature>
                <saml:Subject>
                    <saml:NameID>admin</saml:NameID>
                    <saml:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
                        <saml:SubjectConfirmationData NotOnOrAfter="2015-03-25T15:43:21.172385Z" Recipient="http://beta.example.com/Shibboleth.sso/POST/ECP" />
                    </saml:SubjectConfirmation>
                </saml:Subject>
                <saml:AuthnStatement AuthnInstant="2015-03-25T14:43:21Z" SessionIndex="9790eb729858456f8a33b7a11f0a637e" SessionNotOnOrAfter="2015-03-25T15:43:21.172385Z">
                    <saml:AuthnContext>
                        <saml:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:Password</saml:AuthnContextClassRef>
                        <saml:AuthenticatingAuthority>http://keystone.idp/v3/OS-FEDERATION/saml2/idp</saml:AuthenticatingAuthority>
                    </saml:AuthnContext>
                </saml:AuthnStatement>
                <saml:AttributeStatement>
                    <saml:Attribute Name="openstack_user" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
                        <saml:AttributeValue xsi:type="xs:string">admin</saml:AttributeValue>
                    </saml:Attribute>
                    <saml:Attribute Name="openstack_user_domain" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
                        <saml:AttributeValue xsi:type="xs:string">Default</saml:AttributeValue>
                    </saml:Attribute>
                    <saml:Attribute Name="openstack_roles" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
                        <saml:AttributeValue xsi:type="xs:string">admin</saml:AttributeValue>
                    </saml:Attribute>
                    <saml:Attribute Name="openstack_project" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
                        <saml:AttributeValue xsi:type="xs:string">admin</saml:AttributeValue>
                    </saml:Attribute>
                    <saml:Attribute Name="openstack_project_domain" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
                        <saml:AttributeValue xsi:type="xs:string">Default</saml:AttributeValue>
                    </saml:Attribute>
                </saml:AttributeStatement>
            </saml:Assertion>
        </ns2:Response>
    </ns0:Body>
</ns0:Envelope>
GET
/v3/OS-FEDERATION/saml2/metadata

Retrieve Metadata properties

A user may retrieve Metadata about an Identity Service acting as an Identity Provider.

The response will be a full document with Metadata properties. Note that for readability, this example certificate has been truncated.

Relationship: https://docs.openstack.org/api/openstack-identity/3/ext/OS-FEDERATION/1.0/rel/metadata

Response

Parameters

Name

In

Type

Description

Headers

body

object

XML headers

xml

body

object

Identity Provider metadata information in XML format
Example
Headers:
    Content-Type: text/xml

<?xml version="1.0" encoding="UTF-8"?>
<ns0:EntityDescriptor xmlns:ns0="urn:oasis:names:tc:SAML:2.0:metadata"
   xmlns:ns1="http://www.w3.org/2000/09/xmldsig#" entityID="k2k.com/v3/OS-FEDERATION/idp"
   validUntil="2014-08-19T21:24:17.411289Z">
  <ns0:IDPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
    <ns0:KeyDescriptor use="signing">
      <ns1:KeyInfo>
        <ns1:X509Data>
          <ns1:X509Certificate>MIIDpTCCAo0CAREwDQYJKoZIhvcNAQEFBQAwgZ</ns1:X509Certificate>
        </ns1:X509Data>
      </ns1:KeyInfo>
    </ns0:KeyDescriptor>
  </ns0:IDPSSODescriptor>
  <ns0:Organization>
    <ns0:OrganizationName xml:lang="en">openstack</ns0:OrganizationName>
    <ns0:OrganizationDisplayName xml:lang="en">openstack</ns0:OrganizationDisplayName>
    <ns0:OrganizationURL xml:lang="en">openstack</ns0:OrganizationURL>
  </ns0:Organization>
  <ns0:ContactPerson contactType="technical">
    <ns0:Company>openstack</ns0:Company>
    <ns0:GivenName>first</ns0:GivenName>
    <ns0:SurName>lastname</ns0:SurName>
    <ns0:EmailAddress>admin@example.com</ns0:EmailAddress>
    <ns0:TelephoneNumber>555-555-5555</ns0:TelephoneNumber>
  </ns0:ContactPerson>
</ns0:EntityDescriptor>

For more information about how a SAML assertion is structured, refer to the specification.

OS-SIMPLE-CERT API

Allows the retrieval of information for Certificate Authorities and certificates. Requires v3.0+ of the Identity API.

GET
/v3/OS-SIMPLE-CERT/ca

Show CA Certificate

Show the availbable CA certificate.

Response

Status Codes
Success

Code

Reason
200 - OK

Request was successful.
Error

Code

Reason
401 - Unauthorized

User must authenticate before making a request.
500 - Internal Server Error

Something went wrong inside the service. This should not happen usually. If it does happen, it means the server has experienced some serious problems.
Example
MIIDgTCCAmmgAwIBAgIJAIr3n9+0RSC7MA0GCSqGSIb3DQEBCwUAMFcxCzAJBgNV
BAYTAlVTMQ4wDAYDVQQIDAVVbnNldDEOMAwGA1UEBwwFVW5zZXQxDjAMBgNVBAoM
BVVuc2V0MRgwFgYDVQQDDA93d3cuZXhhbXBsZS5jb20wHhcNMTYxMDIwMTMwMjE4
WhcNMjYxMDE4MTMwMjE4WjBXMQswCQYDVQQGEwJVUzEOMAwGA1UECAwFVW5zZXQx
DjAMBgNVBAcMBVVuc2V0MQ4wDAYDVQQKDAVVbnNldDEYMBYGA1UEAwwPd3d3LmV4
YW1wbGUuY29tMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAwoJkYpfJ
Bvqfq0eAuqTIziiunNQdnSUX/aMS5UuI6tjzSkYnR5FCdf9UP8OrpA37gthvz3KK
XhNLqnnV8MLzEo3+lN5IAr+TE1foXnqGs6vNvj5Jn1lViXXpIeaHxMwkJpJjPwxJ
nFLtxL1m9hIx5anV5ZyJWV8RIaMqnzOJ7QYiX07aouRvmtT5O1LQzr2ht2l4EzPY
YDt9UV/daSikrmroBnwgWMecaFJOC1pxSyvO2PAnw+yhX6NHgGPJmOu0TSN2IK1p
o07ZVM3QJLLbEZFjcUK7FXNRk5ZfzjkCrJA1l0Ys3ByHTb2offffIyTYPuatQtfF
0XvTIwMN5eIAswIDAQABo1AwTjAMBgNVHRMEBTADAQH/MB0GA1UdDgQWBBTZ4Nls
7DRmUBcrYhYDLSsDM0BCWzAfBgNVHSMEGDAWgBTZ4Nls7DRmUBcrYhYDLSsDM0BC
WzANBgkqhkiG9w0BAQsFAAOCAQEALil6WvVii6yNVwu0zgt2iDYqHvnnHWnSVhEJ
eKeBFRxpuwiH+UOeygFB0/6lD2r11cD0SdgaMfLAKkKspQucJIsp3BYLwBJ25oxn
NL2yB3HLZeEebAQzXQwnRbWUbIpcp/XPlKjybiA3unqE+X/qdQZgxJ2Xgtp7bHhN
yzDCSOUZlHrkKNXtFNvqRtoCeMBs2+jfqx2ap64ORSnLihEi57lOcUn2DbAR45OI
+wppD5CcUTDsE0r+XbBK3Cm3dn6pVyVcawv5qDidRB7JdsDbx6VC7gcBbdgdbLWz
Xf4KS8N77jeGjqKJ7QY5jkHdXhY+gGbeponch4y2VqLgMI0VGQ==
GET
/v3/OS-SIMPLE-CERT/certificates

Show Signing Certificate

Show the available signing certificate.

Response

Status Codes
Success

Code

Reason
200 - OK

Request was successful.
Error

Code

Reason
401 - Unauthorized

User must authenticate before making a request.
500 - Internal Server Error

Something went wrong inside the service. This should not happen usually. If it does happen, it means the server has experienced some serious problems.
Example
MIIDZjCCAk6gAwIBAgIBATANBgkqhkiG9w0BAQsFADBXMQswCQYDVQQGEwJVUzEO
MAwGA1UECAwFVW5zZXQxDjAMBgNVBAcMBVVuc2V0MQ4wDAYDVQQKDAVVbnNldDEY
MBYGA1UEAwwPd3d3LmV4YW1wbGUuY29tMB4XDTE2MTAyMDEzMDIxOFoXDTI2MTAx
ODEzMDIxOFowRzELMAkGA1UEBhMCVVMxDjAMBgNVBAgMBVVuc2V0MQ4wDAYDVQQK
DAVVbnNldDEYMBYGA1UEAwwPd3d3LmV4YW1wbGUuY29tMIIBIjANBgkqhkiG9w0B
AQEFAAOCAQ8AMIIBCgKCAQEAua3cVYSD9KY31+wNXZv3HBS5MyzTfoY+nh4nJ2x8
Ram6liu4gkHYRonTUriIrgDLyo+2fuXrmyFcq1+8ke4KD3n24i8pzcrt6BOGAVYP
KdPyXU0EkZECNmH/tKjvVqMLHcq2apsZdZ5ujBtE5G4zbTjVIEzz90AbAmRVJy7S
seluCxBKtg3IGa1WwqgU4B5pgog+VDpT8XPKFvHi1cVaX76qS6MOUxXA7kuOQUct
JxcyITS26Mxym7wOTI+7JV5A9Ow/dUN6CrGMrfHB59Psx3os/BfoopFmIbbnHdOO
ETOeifelkhwLWLfmmOHxWgYYX/aEyW3L/xCU5QDCz9B0wQIDAQABo00wSzAJBgNV
HRMEAjAAMB0GA1UdDgQWBBQeoHzsYSUSfGymk6kem/lpGVJS9DAfBgNVHSMEGDAW
gBTZ4Nls7DRmUBcrYhYDLSsDM0BCWzANBgkqhkiG9w0BAQsFAAOCAQEAfsH6AN7p
XWBg062LUtpfDsRyXqOLYofR4Y0Mzo1rH0jaozJsnOxsj42BdP+hBGjtZB9eUwgP
gx+MJQC4pz+Wuc/xMysDT6f0hyjZmsakXM92lsztlW7+Y7u9ATa2lDTER1Fv7X6D
I+kN+dhphq0lrIRWZvAf3TlZpEUG38cTxLD8OsdOlq4BxSzmvKFQf4mcbu39OX7i
0fGih0SxSa03idx9NWEOEp9IaGLo/mfL84nb4YjgV9yJj+3CkxYvqPlpiM2rHD/C
hMgz/UB52OxbjYjbWoyStZwvlSwKWY75C9iYA04TZrhs5UWvAT+I2Y2UY/krrZ2a
Rke2Bj7NAvXPHw==