Identity API v3 extensions (CURRENT)

This page describes these Identity API v3 extensions:

OS-INHERIT extension (OS-INHERIT)

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

The OS-INHERIT extension was extended in API v3.4 to allow inheritance from projects in addition to inheritance from domains. To access project inheritance, the Identity service server must run at least API v3.4.

GET
/v3/role_assignments
List role assignments

Lists role assignments.

 

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

The list of all role assignments can be long. To filter the list, use the query parameters.

Some typical examples are:

GET /role_assignments?user.id={user_id} lists all role assignments for the specified user.

GET /role_assignments?scope.project.id={project_id} lists all role assignments for the specified project.

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

Use the effective query parameter to list effective assignments at the user, project, and domain level. This parameter allows for the effects of group membership as well as inheritance from the parent domain or project, for role assignments that were made using OS-INHERIT assignment APIs.

The group role assignment entities themselves are not returned in the collection. Because, like group membership, the effects of inheritance have already been allowed for, the role assignment entities themselves that specify the inheritance are not returned in the collection. This represents the effective role assignments that would be included in a scoped token. You can use the other query parameters with the effective parameter.

For example, to determine what a user can actually do, issue this request: GET /role_assignments?user.id={user_id}&effective

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

In the response, the entity links section for entities that are included by virtue of group members also contains a url that you can use to access the membership of the group.

An additional scope.OS-INHERIT:inherited_to query filter enables filtering based on role assignments that are inherited. The scope.OS-INHERIT:inherited_to value of projects is currently supported. This value indicates that this role is inherited to all projects of the owning domain or parent project.

An example response for an API call with the query string effective specified follows:

Normal response codes
200
Error response codes
Bad Request (400), Unauthorized (401), Forbidden (403), Method Not Allowed (405), Request Entity Too Large (413), Service Unavailable (503), Not Found (404)
Request parameters
Parameter Style Type Description
group.id (Optional) query xsd:string

Filters on group ID. Specify group.id={group_id} to list all role assignments for the specified group.

role.id (Optional) query xsd:string

Filters on role ID. Specify role.id={role_id} to list all role assignments for the specified role.

scope.domain.id (Optional) query xsd:string

Filters on domain ID. Specify scope.domain.id={domain_id} to list all role assignments for the specified domain.

scope.project.id (Optional) query xsd:string

Filters on project ID. Specify scope.project.id={project_id} to list all role assignments for the specified project.

user.id (Optional) query xsd:string

Filters on user ID. Specify user.id={user_id} to list all role assignments for the specified user.

effective (Optional) query xsd:key

Lists effective assignments at the user, project, and domain level, allowing for the effects of group membership.

The group role assignment entities themselves are not returned in the collection.

This represents the effective role assignments that would be included in a scoped token. You can use the other query parameters with the effective parameter. 

{
    "role_assignments": [
        {
            "links": {
                "assignment": "http://identity:35357/v3/OS-INHERIT/domains/1234/users/5678/roles/91011/inherited_to_projects"
            },
            "role": {
                "id": "91011"
            },
            "scope": {
                "domain": {
                    "id": "1234"
                },
                "OS-INHERIT:inherited_to": "projects"
            },
            "user": {
                "id": "5678"
            }
        },
        {
            "group": {
                "id": "5678"
            },
            "links": {
                "assignment": "http://identity:35357/v3/projects/1234/groups/5678/roles/91011"
            },
            "role": {
                "id": "91011"
            },
            "scope": {
                "project": {
                    "id": "1234"
                }
            }
        }
    ],
    "links": {
        "self": "http://identity:35357/v3/role_assignments",
        "previous": null,
        "next": null
    }
}

{
    "role_assignments": [
        {
            "links": {
                "assignment": "http://identity:35357/v3/OS-INHERIT/domains/12131/users/41516/roles/91011/inherited_to_projects"
            },
            "role": {
                "id": "91011"
            },
            "scope": {
                "project": {
                    "id": "1234"
                }
            },
            "user": {
                "id": "41516"
            }
        },
        {
            "links": {
                "assignment": "http://identity:35357/v3/projects/1234/groups/5678/roles/91011",
                "membership": "http://identity:35357/v3/groups/5678/users/41516"
            },
            "role": {
                "id": "91011"
            },
            "scope": {
                "project": {
                    "id": "1234"
                }
            },
            "user": {
                "id": "41516"
            }
        }
    ],
    "links": {
        "self": "http://identity:35357/v3/role_assignments?effective",
        "previous": null,
        "next": null
    }
}

This operation does not accept a request body.

GET
/v3/OS-INHERIT/projects/​{project_id}​/users/​{user_id}​/roles/inherited_to_projects
List roles for user

Lists the inherited project roles for a specified user on a specified project.

 

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

Normal response codes
200
Request parameters
Parameter Style Type Description
project_id URI csapi:uuid The ID of the project.
user_id URI csapi:uuid

The ID of the user.

 
{
    "roles": [
        {
            "id": "91011",
            "links": {
                "self": "http://identity:35357/v3/roles/91011"
            },
            "name": "admin"
        },
        {
            "id": "91011",
            "links": {
                "self": "http://identity:35357/v3/roles/91011"
            },
            "name": "admin"
        }
    ],
    "links": {
        "self": "http://identity:35357/v3/OS-INHERIT/projects/1234/users/5678/roles/inherited_to_projects",
        "previous": null,
        "next": null
    }
}

This operation does not accept a request body.

PUT
/v3/OS-INHERIT/projects/​{project_id}​/users/​{user_id}​/roles/​{role_id}​/inherited_to_projects
Assign role to user

Assigns a specified role to a specified user on projects in a subtree.

 

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

A user can have both a regular, non-inherited role assignment and an inherited role assignment on the same project.

Normal response codes
204
Request parameters
Parameter Style Type Description
project_id URI csapi:uuid The ID of the project.
user_id URI csapi:uuid

The ID of the user.
role_id URI csapi:uuid

The ID of the role.

This operation does not accept a request body and does not return a response body.

HEAD
/v3/OS-INHERIT/projects/​{project_id}​/users/​{user_id}​/roles/​{role_id}​/inherited_to_projects
Check role for user

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

 
Normal response codes
200
Request parameters
Parameter Style Type Description
project_id URI csapi:uuid The ID of the project.
user_id URI csapi:uuid

The ID of the user.
role_id URI csapi:uuid

The ID of the role.

This operation does not accept a request body and does not return a response body.

DELETE
/v3/OS-INHERIT/projects/​{project_id}​/users/​{user_id}​/roles/​{role_id}​/inherited_to_projects
Revoke role from user

Revokes an inherited role from a specified user a specified project.

 
Normal response codes
204
Request parameters
Parameter Style Type Description
project_id URI csapi:uuid The ID of the project.
user_id URI csapi:uuid

The ID of the user.
role_id URI csapi:uuid

The ID of the role.

This operation does not accept a request body and does not return a response body.

GET
/v3/OS-INHERIT/projects/​{project_id}​/groups/​{group_id}​/roles/inherited_to_projects
List roles for group

Lists the inherited project roles for a specified group on a specified project.

 

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

Normal response codes
200
Request parameters
Parameter Style Type Description
project_id URI csapi:uuid The ID of the project.
group_id URI csapi:uuid

The ID of the group.

 
{
    "roles": [
        {
            "id": "91011",
            "links": {
                "self": "http://identity:35357/v3/roles/91011"
            },
            "name": "admin"
        },
        {
            "id": "91011",
            "links": {
                "self": "http://identity:35357/v3/roles/91011"
            },
            "name": "admin"
        }
    ],
    "links": {
        "self": "http://identity:35357/v3/OS-INHERIT/projects/1234/groups/5678/roles/inherited_to_projects",
        "previous": null,
        "next": null
    }
}

This operation does not accept a request body.

PUT
/v3/OS-INHERIT/projects/​{project_id}​/groups/​{group_id}​/roles/​{role_id}​/inherited_to_projects
Assign role to group

Assigns a specified role to a specified group on projects in a subtree.

 

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

A group can have both a regular, non-inherited role assignment and an inherited role assignment on the same project.

Normal response codes
204
Request parameters
Parameter Style Type Description
project_id URI csapi:uuid The ID of the project.
group_id URI csapi:uuid

The ID of the group.
role_id URI csapi:uuid

The ID of the role.

This operation does not accept a request body and does not return a response body.

HEAD
/v3/OS-INHERIT/projects/​{project_id}​/groups/​{group_id}​/roles/​{role_id}​/inherited_to_projects
Check role for group

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

 
Normal response codes
200
Request parameters
Parameter Style Type Description
project_id URI csapi:uuid The ID of the project.
group_id URI csapi:uuid

The ID of the group.
role_id URI csapi:uuid

The ID of the role.

This operation does not accept a request body and does not return a response body.

DELETE
/v3/OS-INHERIT/projects/​{project_id}​/groups/​{group_id}​/roles/​{role_id}​/inherited_to_projects
Revoke role from group

Revokes an inherited role from a specified group on a specified project.

 
Normal response codes
204
Request parameters
Parameter Style Type Description
project_id URI csapi:uuid The ID of the project.
group_id URI csapi:uuid

The ID of the group.
role_id URI csapi:uuid

The ID of the role.

This operation does not accept a request body and does not return a response body.

GET
/v3/OS-INHERIT/domains/​{domain_id}​/users/​{user_id}​/roles/inherited_to_projects
List project roles for user on domain

Lists the inherited project roles on a specified domain for a specified user.

 

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

Normal response codes
200
Request parameters
Parameter Style Type Description
domain_id URI csapi:uuid The ID of the domain.
user_id URI csapi:uuid

The ID of the user.

 
{
    "roles": [
        {
            "id": "91011",
            "links": {
                "self": "http://identity:35357/v3/roles/91011"
            },
            "name": "admin"
        },
        {
            "id": "91011",
            "links": {
                "self": "http://identity:35357/v3/roles/91011"
            },
            "name": "admin"
        }
    ],
    "links": {
        "self": "http://identity:35357/v3/OS-INHERIT/domains/1234/users/5678/roles/inherited_to_projects",
        "previous": null,
        "next": null
    }
}

This operation does not accept a request body.

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

Assigns a specified role to a specified user on projects owned by a specified domain.

 

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

Normal response codes
204
Request parameters
Parameter Style Type Description
domain_id URI csapi:uuid The ID of the domain.
user_id URI csapi:uuid

The ID of the user.
role_id URI csapi:uuid

The ID of the role.

This operation does not accept a request body and does not return a response body.

HEAD
/v3/OS-INHERIT/domains/​{domain_id}​/users/​{user_id}​/roles/​{role_id}​/inherited_to_projects
Check project role for user on domain

Checks whether a specified user has an inherited project role on a specified domain.

 
Normal response codes
200
Request parameters
Parameter Style Type Description
domain_id URI csapi:uuid The ID of the domain.
user_id URI csapi:uuid

The ID of the user.
role_id URI csapi:uuid

The ID of the role.

This operation does not accept a request body and does not return a response body.

DELETE
/v3/OS-INHERIT/domains/​{domain_id}​/users/​{user_id}​/roles/​{role_id}​/inherited_to_projects
Revoke project role from user on domain

Revokes an inherited project role from a specified user on a specified domain.

 
Normal response codes
204
Request parameters
Parameter Style Type Description
domain_id URI csapi:uuid The ID of the domain.
user_id URI csapi:uuid

The ID of the user.
role_id URI csapi:uuid

The ID of the role.

This operation does not accept a request body and does not return a response body.

GET
/v3/OS-INHERIT/domains/​{domain_id}​/groups/​{group_id}​/roles/inherited_to_projects
List project roles for group on domain

Lists the inherited project roles on a specified domain for a specified group.

 

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

Normal response codes
200
Request parameters
Parameter Style Type Description
domain_id URI csapi:uuid The ID of the domain.
group_id URI csapi:uuid

The ID of the group.

 
{
    "roles": [
        {
            "id": "91011",
            "links": {
                "self": "http://identity:35357/v3/roles/91011"
            },
            "name": "admin"
        },
        {
            "id": "91011",
            "links": {
                "self": "http://identity:35357/v3/roles/91011"
            },
            "name": "admin"
        }
    ],
    "links": {
        "self": "http://identity:35357/v3/OS-INHERIT/domains/1234/groups/5678/roles/inherited_to_projects",
        "previous": null,
        "next": null
    }
}

This operation does not accept a request body.

PUT
/v3/OS-INHERIT/domains/​{domain_id}​/groups/​{group_id}​/roles/​{role_id}​/inherited_to_projects
Assign role to group on domain projects

Assigns a specified role to a specified group on projects owned by a specified domain.

 

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

Normal response codes
204
Request parameters
Parameter Style Type Description
domain_id URI csapi:uuid The ID of the domain.
group_id URI csapi:uuid

The ID of the group.
role_id URI csapi:uuid

The ID of the role.

This operation does not accept a request body and does not return a response body.

HEAD
/v3/OS-INHERIT/domains/​{domain_id}​/groups/​{group_id}​/roles/​{role_id}​/inherited_to_projects
Check project role for group on domain

Checks whether a specified group has an inherited project role on a specified domain.

 
Normal response codes
200
Request parameters
Parameter Style Type Description
domain_id URI csapi:uuid The ID of the domain.
group_id URI csapi:uuid

The ID of the group.
role_id URI csapi:uuid

The ID of the role.

This operation does not accept a request body and does not return a response body.

DELETE
/v3/OS-INHERIT/domains/​{domain_id}​/groups/​{group_id}​/roles/​{role_id}​/inherited_to_projects
Revoke project role from group on domain

Revokes an inherited project role from a specified group on a specified domain.

 
Normal response codes
204
Request parameters
Parameter Style Type Description
domain_id URI csapi:uuid The ID of the domain.
group_id URI csapi:uuid

The ID of the group.
role_id URI csapi:uuid

The ID of the role.

This operation does not accept a request body and does not return a response body.

Key Distribution Server (KDS) extension (OS-KDS)

The Key Distribution Server (KDS) is a trusted third party that generates and securely distributes signing and encryption keys to communicating parties. These shared keys enable parties to exchange authenticated, confidential messages. KDS is an integral part of the RPC message security implementation. To establish a trusted relationship between the party and the KDS, a properly authorized user, such as a cloud administrator, must assign a long-term shared key to the communicating party. Assigning a key to a party requires assigning an identity to that party in the KDS. An identity includes a unique party name and the associated long-term shared key. This party name is used to identify a party when it communicates with KDS or another party.

The KDS enables two individual parties or one individual party and a group party to exchange secure messages. To get keys so that it can communicate with another party, a party makes an authenticated request to KDS for a ticket. The KDS returns an encrypted ticket to the requesting party. The KDS encrypts the ticket with the long-term shared key that is associated with that party. Only the associated party or the KDS itself can decrypt the ticket.

The KDS issues a ticket that contains a copy of the shared encryption and signing keys. These keys are for the source party, which is the party that requests the ticket. The ticket also contains a payload that is intended for the destination party, which is the party with whom the source party wants to communicate. This payload contains the information that the destination party can use to derive the shared encryption and signing keys. When the destination party is:

  • An individual. The payload is encrypted with the long-term shared key that is associated with the destination party.

  • A group. The payload is encrypted with a shared group key that the KDS makes available to all members of the group. This encryption enables the destination party to trust that the information in the payload was supplied by the KDS.

When the source party is ready to communicate with the destination party, it sends this encrypted payload to the destination party along with whatever data it has protected with the shared signing and encryption keys. The destination party can decrypt the payload and derive the shared encryption and signing keys by using the payload information. Both parties have a copy of the shared signing and encryption keys that are trusted as being issued by the KDS. The destination party uses these shared keys to authenticate and decrypt the data sent by the source party.

Other guidelines:

  • When a source party must send secure messages to multiple recipients, an authorized user can define a KDS group for the recipients. Membership in a group is determined by comparing a party name with the group name. The party is considered to be a member if the party name matches <group name>.*. For example, a party named scheduler.host.example.com is considered a member of the scheduler group. This method is the same method that is used to name message queues in OpenStack.

  • When a source party requests a ticket for a destination party that is a group, KDS generates a short-lived group key and assigns it to the group. This group key is used to encrypt the payload in the ticket, which contains the information that the destination party uses to derive the shared signing and encryption keys.

  • When an individual destination party must decrypt the payload that it receives from the source party as a part of a group message, it makes an authenticated request to KDS to get the short-lived group key. If the requester is a member of the target group, KDS provides the short-lived group key encrypted with the long-term shared key associated with the individual destination party. The individual destination party can then decrypt the group key, which enables it to decrypt the payload and derive the shared signing and encryption keys to use to authenticate and decrypt the data sent by the source party.

  • When a sender gets keys to send a message to a group, all group members and the sender share the signing and encryption keys, which makes it impossible for an individual destination party to determine whether a message was sent by the source party or by another destination party who is a group member. The destination party can confirm only that the message was sent by a party who has the shared signing and encryption keys. When a sender uses keys to send a message to a group, all group members must trust other members to operate in good faith.

The signing and encryption keys that communicating parties share are short-lived. The life span of these keys is defined by a validity period that is set by the KDS when it issues the ticket. A suggested reasonable default validity period is 15 minutes, though the implementation determines the appropriate validity period.

After the validity period for the keys expires, a party should refuse to use those keys to prevent the use of compromised keys. This requires the source party to request a new ticket from the KDS to get a new set of keys. An implementation can implement a grace period to account for clock skew between parties. This grace period enables a destination party to accept messages that use recently expired keys. If you use a grace period, its duration should be five or fewer minutes.

A key server, unlike a pure public key-based system, can regulate the encryption and signing key exchange. When keys are requested, the key server actively distributes keys to communicating parties, applies access control, and denies communication between arbitrary peers in the system. This enables centralized access control, prevents unauthorized communication, and eliminates the need to perform post-authentication access control and policy lookups on the receiving side.

The KDS requires that all ticket requests are authenticated and data is encrypted where appropriate. You must specify all timestamp values that are used in the API as a UTC ISO 8601 extended format date and time string that includes microseconds. For example, 2012-03-26T10:01:01.720000.

The default algorithms for message authentication and encryption are, respectively, HMAC-SHA-256 and AES-128-CBC. Therefore, the default block size is 128bit.

The source party that requests a ticket must send the encrypted esek payload to the destination party. The source and destination strings used when requesting the ticket also must be sent to the destination party to enable it to derive the shared signing end encryption keys. The messaging implementation is responsible for transferring this data to the destination party.

The key derivation used to generate the shared signing and encryption keys uses the Hashed Message Authentication Code (HMAC)-based key derivation function (HKDF) standard, as described in RFC 5869. The destination party must use the HKDF expand function by using the information that it receives from the source party to complete derivation of the shared signing and encryption keys. The inputs to the HKDF expand function are: 

HKDF-Expand(esek.key, info, 256)

The info input for the HKDF expand function is a string that concatenates the source, destination, and esek.timestamp strings by using a comma (,) separator between each element. An example of a valid info string where scheduler.host.example.com is the source, compute.host.example.com is the destination, and 2012-03-26T10:01:01.720000 is the esek.timestamp is: 

scheduler.host.example.com,compute.host.example.com,2012-03-26T10:01:01.720000

The output of the HKDF expand function is an array of bytes of 256 bit length. The first half is the signing key, and the second half is the encryption key.

Create and delete requests for long-term keys are restricted to authorized users, such as cloud administrators. The authentication and authorization for these requests is left up to the implementation, though the implementation should leverage the Identity API for these purposes.

POST
/v1/keys/​{name}​
Create key

Creates a long-term key in the KDS.

 

The request body contains the key.

The response shows the key name and generation value.

Normal response codes
201
Error response codes
Bad Request (400), Unauthorized (401), Forbidden (403), Method Not Allowed (405), Request Entity Too Large (413), Service Unavailable (503)
Request parameters
Parameter Style Type Description
name URI csapi:string

The name of the party that is associated with the key.

Response parameters
Parameter Style Type Description
name plain xsd:string

The name of the party that is associated with the key.

generation plain xsd:int

A unique integer value that identifies the key. The generation value changes only if you set a new key. If the request sets the key to the same value that already exists, the response shows the existing generation value, which makes the request idempotent. 

{
    "key": "TXkgcHJlY2lvdXNzcy4u..."
}

{
    "name": "TXkgcHJlY2lvdXNzcy4u...",
    "generation": 2
}
DELETE
/v1/keys/​{name}​
Delete key

Deletes a long-term key from the KDS.

 
Normal response codes
204
Request parameters
Parameter Style Type Description
name URI csapi:string

The name of the party that is associated with the key.

This operation does not accept a request body and does not return a response body.

POST
/v1/tickets
Generate ticket

Generates a ticket to facilitate messaging between a source and destination.

 

A generate ticket request contains metadata that you specify as a base64-encoded JSON object and a signature.

The response shows the metadata, encrypted ticket, and signature.

Normal response codes
201
Error response codes
Bad Request (400), Unauthorized (401), Forbidden (403), Method Not Allowed (405), Request Entity Too Large (413), Service Unavailable (503)
Request parameters
Parameter Style Type Description
metadata plain xsd:string

A base64-encoded JSON object that contains these key and value pairs:

  • source. The identity who is requesting a ticket.

  • destination. The target for which the ticket will be valid.

  • timestamp. Current timestamp from the requester.

  • nonce. Random single-use data.

The timestamp and nonce are required to prevent replay attacks.

For example:

{
    "source": "scheduler.host.example.com",
    "destination": "compute.host.example.com",
    "timestamp": "2012-03-26T10:01:01.720000",
    "nonce": 1234567890
}
signature plain xsd:string

A base64-encoded HMAC signature over the base64-encoded request metadata object. For example:

Base64encode(HMAC(SigningKey, RequestMetadata))

The long-term key of the requester is used for the signature. When the request is received, the KDS must verify the signature. To do so, the KDS must access the source from the request metadata to look up the associated long-term key to use to verify the signature. The KDS should not access any other data contained in the request metadata before verifying the signature. If the KDS fails to verify the signature, it risks issuing a ticket to a party who is impersonating the source.

generation plain xsd:int

A unique integer value that identifies the key. The generation value changes only if you set a new key. If the request sets the key to the same value that already exists, the response shows the existing generation value, which makes the request idempotent.

Response parameters
Parameter Style Type Description
metadata plain xsd:string

A base64-encoded JSON object that contains these key and value pairs:

  • source. The identity who requests the ticket.

  • destination. The target for which the ticket will be valid.

  • timestamp. Current timestamp from the requester.

  • nonce. Random single-use data.

The timestamp and nonce are required to prevent replay attacks.

For example:

{
    "source": "scheduler.host.example.com",
    "destination": "compute.host.example.com",
    "timestamp": "2012-03-26T10:01:01.720000",
    "nonce": 1234567890
}
ticket plain xsd:string

The ticket is encrypted with the long-term key of the source and contains a base64-encoded JSON object containing the following key and value pairs:

  • skey. The newly-generated base64-encoded message signing key.

  • ekey. The newly-generated base64-encoded message encryption key.

  • esek. Encrypted signing and encryption key pair for the receiver.

For example:

{
    "skey": "ZjhkuYZH8y87rzhgi7...",
    "ekey": "Fk8yksa8z8zKtakc8s...",
    "esek": "KBo8fajfo8ysad5hq2..."
}

The long-term key of the destination is used to encrypt the esek value. The esek value contains a base64-encoded JSON object that contains the following key and value pairs:

  • key. The base64-encoded random key that is used to generate the signing and encryption keys.

  • timestamp. Timestamp when the key was created.

  • ttl. An integer value that specifies the validity length of the key, in seconds.

For example:

{
    "key": "Afa8sad2hgsd7asv7ad...",
    "timestamp": "2012-03-26T10:01:01.720000",
    "ttl": 28800
}

The key and timestamp values are used as inputs to the HKDF expand function to generate the signing and encryption keys, as described in the overview on this page.

The timestamp and ttl values must equal the expiration timestamp value that is contained in the response metadata.

signature plain xsd:string

A base64-encoded HMAC signature over the base64-encoded request metadata object. For example:

Base64encode(HMAC(SigningKey, RequestMetadata))

The long-term key of the requester is used for the signature. When the KDS receives the request, the KDS must access the source value from the request metadata to look up the associated long-term key to use to verify the signature. The KDS should not access any other data that is contained in the request metadata before verifying the signature. If the KDS fails to verify the signature, it risks issuing a ticket to a party who is impersonating the source. 

{
    "metadata": "Zhn8yhasf8hihkf...",
    "signature": "c2lnbmF0dXJl..."
}

{
    "source": "scheduler.host.example.com",
    "destination": "compute.host.example.com",
    "timestamp": "2012-03-26T10:01:01.720000",
    "nonce": 1234567890
}
GET
/v1/groups
Get group key

Gets the key for a group in the KDS.

 

When a ticket is requested where the destination is a group, a group key is generated that is valid for a predetermined amount of time. Any member of the group can get the key as long as it is still valid. Group keys are necessary to verify signatures and decrypt messages that have a group name as the target.

Normal response codes
201
Error response codes
Bad Request (400), Unauthorized (401), Forbidden (403), Method Not Allowed (405), Request Entity Too Large (413), Service Unavailable (503)
Response parameters
Parameter Style Type Description
name plain xsd:string

The name of the group. 

{
    "name": "--group-name--"
}

This operation does not accept a request body.

POST
/v1/groups/​{name}​
Create group

Creates a group in the KDS.

 

Membership in groups is based on the party name. For example, a scheduler group implicitly includes any party name that starts with scheduler. For example, a member named scheduler.host.example.com.

Normal response codes
201
Error response codes
Bad Request (400), Unauthorized (401), Forbidden (403), Method Not Allowed (405), Request Entity Too Large (413), Service Unavailable (503)
Request parameters
Parameter Style Type Description
name URI csapi:string

The name of the group.

Response parameters
Parameter Style Type Description
name plain xsd:string

The name of the group. 

{
    "name": "--group-name--"
}

This operation does not accept a request body.

DELETE
/v1/groups/​{name}​
Delete group

Deletes a group from the KDS.

 
Normal response codes
204
Request parameters
Parameter Style Type Description
name URI csapi:string

The name of the group.

This operation does not accept a request body and does not return a response body.

OAuth extension (OS-OAUTH1)

Enables users to delegate roles to third-party consumers through the The OAuth 1.0 Protocol.

A user is an Identity API user who delegates its roles and who authorizes request tokens. A consumer is a third-party application that uses OAuth to access a protected resource. An OAuth-derived token enables admin users to act on behalf of the authorizing user. A request token is a token that the consumer uses to get authorization from the user and exchanges with an OAuth verifier for an access token. The OAuth verifier is a required string that is provided with the corresponding request token in exchange for an access token. An access token is a token that the consumer uses to request Identity API tokens on behalf of the authorizing user instead of using the credentials for the user.

Request and access tokens use token keys to identify themselves. For OpenStack purposes, the token key is the token ID. The consumer uses a token secret to establish ownership of a specified token. Both request and access tokens have token secrets.

Delegated authentication through OAuth occurs as follows:

  1. A user creates a consumer.

  2. The consumer gets an unauthorized request token. Then, the consumer uses the request token to initiate user authorization.

  3. The user authorizes the request token.

  4. The consumer exchanges the authorized request token and the OAuth verifier for an access token.

    The authorizing user receives the request token key from the consumer out-of-band.

  5. The consumer uses the access token to request an Identity API token.

POST
/v3/OS-OAUTH1/consumers
Create consumer

Enables a user to create a consumer.

 
Normal response codes
201
Error response codes
Bad Request (400), Unauthorized (401), Forbidden (403), Method Not Allowed (405), Request Entity Too Large (413), Service Unavailable (503)
Response parameters
Parameter Style Type Description
secret plain xsd:string

A secret for the consumer, which is returned only when the consumer is created.

description (Optional) plain xsd:string

The consumer description.
id plain csapi:uuid

The ID of the consumer. In OpenStack, the ID is the key.

links plain xsd:dict

Consumer links.

 
{
    "consumer": {
        "description": "My consumer"
    }
}
{
    "consumer": {
        "secret": "secretsecret",
        "description": "My consumer",
        "id": "7fea2d",
        "links": {
            "self": "http://identity:35357/v3/OS-OAUTH1/consumers/7fea2d"
        }
    }
}
GET
/v3/OS-OAUTH1/consumers
List consumers

Lists consumers.

 
Normal response codes
200
Error response codes
Bad Request (400), Unauthorized (401), Forbidden (403), Method Not Allowed (405), Request Entity Too Large (413), Service Unavailable (503), Not Found (404)
Response parameters
Parameter Style Type Description
description (Optional) plain xsd:string

The consumer description.
id plain csapi:uuid

The ID of the consumer. In OpenStack, the ID is the key.

links plain xsd:dict

Consumer links.
next (Optional) plain xsd:anyURI

Moves to the next item in the list.

previous (Optional) plain xsd:anyURI

Moves to the previous item in the list. 

{
    "consumers": [
        {
            "id": "0c2a74",
            "links": {
                "self": "http://identity:35357/v3/OS-OAUTH1/consumers/0c2a74"
            }
        },
        {
            "description": "My consumer",
            "id": "7fea2d",
            "links": {
                "self": "http://identity:35357/v3/OS-OAUTH1/consumers/7fea2d"
            }
        }
    ],
    "links": {
        "next": null,
        "previous": null,
        "self": "http://identity:35357/v3/OS-OAUTH1/consumers"
    }
}

This operation does not accept a request body.

GET
/v3/OS-OAUTH1/consumers/​{consumer_id}​
Show consumer

Shows information for a specified consumer.

 
Normal response codes
200
Error response codes
Bad Request (400), Unauthorized (401), Forbidden (403), Method Not Allowed (405), Request Entity Too Large (413), Service Unavailable (503), Not Found (404)
Request parameters
Parameter Style Type Description
consumer_id URI csapi:uuid The ID of the consumer.
Response parameters
Parameter Style Type Description
id plain csapi:uuid

The ID of the consumer. In OpenStack, the ID is the key.

description (Optional) plain xsd:string

The consumer description.
links plain xsd:dict

Consumer links.

 
{
    "consumer": {
        "id": "7fea2d",
        "description": "My consumer",
        "links": {
            "self": "http://identity:35357/v3/OS-OAUTH1/consumers/7fea2d"
        }
    }
}

This operation does not accept a request body.

PATCH
/v3/OS-OAUTH1/consumers/​{consumer_id}​
Update consumer

Updates the description for a specified consumer.

 

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

Normal response codes
200
Error response codes
Bad Request (400), Unauthorized (401), Forbidden (403), Method Not Allowed (405), Request Entity Too Large (413), Service Unavailable (503)
Request parameters
Parameter Style Type Description
consumer_id URI csapi:uuid The ID of the consumer.
Response parameters
Parameter Style Type Description
description (Optional) plain xsd:string

The consumer description.
id plain csapi:uuid

The ID of the consumer. In OpenStack, the ID is the key.

links plain xsd:dict

Consumer links.

 
{
    "consumer": {
        "description": "My new consumer"
    }
}
{
    "consumer": {
        "description": "My new consumer",
        "id": "7fea2d",
        "links": {
            "self": "http://identity:35357/v3/OS-OAUTH1/consumers/7fea2d"
        }
    }
}
DELETE
/v3/OS-OAUTH1/consumers/​{consumer_id}​
Delete consumer

Deletes a specified consumer.

 

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

Normal response codes
204
Error response codes
Bad Request (400), Unauthorized (401), Forbidden (403), Method Not Allowed (405), Request Entity Too Large (413), Service Unavailable (503)
Request parameters
Parameter Style Type Description
consumer_id URI csapi:uuid The ID of the consumer.

This operation does not accept a request body and does not return a response body.

POST
/v3/OS-OAUTH1/request_token
Get unauthorized 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.

Normal response codes
200
Error response codes
Bad Request (400), Unauthorized (401), Forbidden (403), Method Not Allowed (405), Request Entity Too Large (413), Service Unavailable (503)
Response parameters
Parameter Style Type Description
oauth_token plain xsd:dict

The request token key that the Identity API returns.

oauth_token_secret plain xsd:dict

The secret associated with the request token.

oauth_expires_at (Optional) plain xsd:dict

The ISO 8601 date time when a request token expires. If the Identity API does not include this attribute or the attribute is null, the token lasts indefinitely. 

oauth_token=29971f&oauth_token_secret=238eb8&oauth_expires_at=2013-09-11T06:07:51.501805Z
POST
/v3/OS-OAUTH1/access_token
Create access token

Enables a consumer to create an access token by exchanging a request token for an access token.

 

After the 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 Obtains a Request Token.

Supported signature methods: HMAC-SHA1.

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

Normal response codes
200
Error response codes
Bad Request (400), Unauthorized (401), Forbidden (403), Method Not Allowed (405), Request Entity Too Large (413), Service Unavailable (503)
Response parameters
Parameter Style Type Description
oauth_expires_at (Optional) plain xsd:dict

The ISO 8601 date time when a request token expires. If the Identity Service API does not include this attribute or the attribute is null, the token lasts indefinitely.

oauth_token plain xsd:dict

The request token key that the Identity Service returns.

oauth_token_secret plain xsd:dict

The secret associated with the request token. 

oauth_token=accd36&oauth_token_secret=aa47da&oauth_expires_at=2013-09-11T06:07:51.501805Z
GET
/v3/OS-OAUTH1/users/​{user_id}​/access_tokens
List authorized access tokens

Lists authorized access tokens.

 
Normal response codes
200
Error response codes
Bad Request (400), Unauthorized (401), Forbidden (403), Method Not Allowed (405), Request Entity Too Large (413), Service Unavailable (503)
Request parameters
Parameter Style Type Description
user_id URI csapi:uuid

The ID of the user.
Response parameters
Parameter Style Type Description
consumer_id URI csapi:uuid

The ID of the consumer.
id plain csapi:uuid

The ID for the access token.

expires_at (Optional) plain xsd:dict

The ISO 8601 date time when an access token expires. If the Identity Service API does not include this attribute or the attribute is null, the token lasts indefinitely.

links plain xsd:dict

Access token links.
project_id plain csapi:uuid

The ID of the project.
authorizing_user_id plain csapi:uuid

The ID of the authorizing user.

 
{
    "access_tokens": [
        {
            "consumer_id": "7fea2d",
            "id": "6be26a",
            "expires_at": "2013-09-11T06:07:51.501805Z",
            "links": {
                "roles": "http://identity:35357/v3/users/ce9e07/OS-OAUTH1/access_tokens/6be26a/roles",
                "self": "http://identity:35357/v3/users/ce9e07/OS-OAUTH1/access_tokens/6be26a"
            },
            "project_id": "b9fca3",
            "authorizing_user_id": "ce9e07"
        }
    ],
    "links": {
        "next": null,
        "previous": null,
        "self": "http://identity:35357/v3/users/ce9e07/OS-OAUTH1/access_tokens"
    }
}

This operation does not accept a request body.

GET
/v3/OS-OAUTH1/users/​{user_id}​/access_tokens/​{access_token_id}​
Get authorized access token

Gets an authorized access token.

 
Normal response codes
200
Error response codes
Bad Request (400), Unauthorized (401), Forbidden (403), Method Not Allowed (405), Request Entity Too Large (413), Service Unavailable (503)
Request parameters
Parameter Style Type Description
user_id URI csapi:uuid

The ID of the user.
access_token_id URI csapi:uuid

The ID of the access token.

Response parameters
Parameter Style Type Description
consumer_id URI csapi:uuid

The ID of the consumer.
id plain csapi:uuid

The ID for the access token.

expires_at (Optional) plain xsd:dict

The ISO 8601 date time when an access token expires. If the Identity Service API does not include this attribute or the attribute is null, the token lasts indefinitely.

links plain xsd:dict

Access token links.
project_id plain csapi:uuid

The ID of the project.
authorizing_user_id plain csapi:uuid

The ID of the authorizing user.

 
{
    "access_token": {
        "consumer_id": "7fea2d",
        "id": "6be26a",
        "expires_at": "2013-09-11T06:07:51.501805Z",
        "links": {
            "roles": "http://identity:35357/v3/users/ce9e07/OS-OAUTH1/access_tokens/6be26a/roles",
            "self": "http://identity:35357/v3/users/ce9e07/OS-OAUTH1/access_tokens/6be26a"
        },
        "project_id": "b9fca3",
        "authorizing_user_id": "ce9e07"
    }
}

This operation does not accept a request body.

DELETE
/v3/OS-OAUTH1/users/​{user_id}​/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.

 
Normal response codes
204
Request parameters
Parameter Style Type Description
user_id URI csapi:uuid

The ID of the user.
access_token_id URI csapi:uuid

The ID of the access token.

This operation does not accept a request body and does not return a response body.

GET
/v3/OS-OAUTH1/users/​{user_id}​/access_tokens/​{access_token_id}​/roles
List roles for an access token

Lists associated roles for a specified access token.

 
Normal response codes
200
Error response codes
Bad Request (400), Unauthorized (401), Forbidden (403), Method Not Allowed (405), Request Entity Too Large (413), Service Unavailable (503)
Request parameters
Parameter Style Type Description
user_id URI csapi:uuid

The ID of the user.
access_token_id URI csapi:uuid

The ID of the access token.

This operation does not accept a request body and does not return a response body.

GET
/v3/OS-OAUTH1/users/​{user_id}​/access_tokens/​{access_token_id}​/roles/​{role_id}​
Get role information for an access token

Gets information about a specified role for a specified access token.

 
Normal response codes
200
Error response codes
Bad Request (400), Unauthorized (401), Forbidden (403), Method Not Allowed (405), Request Entity Too Large (413), Service Unavailable (503)
Request parameters
Parameter Style Type Description
user_id URI csapi:uuid

The ID of the user.
access_token_id URI csapi:uuid

The ID of the access token.

role_id URI csapi:uuid

The ID of the role.
Response parameters
Parameter Style Type Description
id plain csapi:uuid

The role ID.
links plain xsd:dict

Links to roles.
name plain xsd:string

The role name.

This operation does not accept a request body.

POST
/v3/auth/tokens
Get an Identity Service token

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 Consumer Obtains a Request Token.

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"
}
Normal response codes
200
Error response codes
Bad Request (400), Unauthorized (401), Forbidden (403), Method Not Allowed (405), Request Entity Too Large (413), Service Unavailable (503), Not Found (404)

Trust extension (OS-TRUST)

Creates a trust.

A trust is an OpenStack Identity extension that enables delegation and, optionally, impersonation through keystone. A trust extension defines a relationship between a trustor and trustee. A trustor is the user who delegates a limited set of their own rights to another user. A trustee is the user whose trust is being delegated to, for a limited time.

The trust can eventually enable the trustee to impersonate the trustor. For security reasons, some safety measures are added. For example, if a trustor loses a given role, any trusts and the related tokens that the user issued with that role are automatically revoked.

For more information, see Use trusts.

POST
/v3/OS-TRUST/trust
Create trust

Creates a trust.

 
Normal response codes
201
Error response codes
Bad Request (400), Unauthorized (401), Forbidden (403), Method Not Allowed (405), Request Entity Too Large (413), Service Unavailable (503)
Request parameters
Parameter Style Type Description
trust plain xsd:string

A trust object.
expires_at (Optional) plain xsd:dict

The ISO 8601 date time when a trust expires. If the Identity API does not include this attribute or the attribute is null, the trust lasts indefinitely.

impersonation (Optional) plain xsd:boolean

The impersonation flag. Default is false.
project_id plain csapi:uuid

The ID of the project.
remaining_uses (Optional) plain xsd:boolean

Remaining uses flag. Default is null.
roles plain xsd:dict

A roles object.
name plain xsd:string

The role name.
trustee_user_id plain xsd:string

The trustee user ID.
trustor_user_id plain xsd:string

The trustor user ID.
Response parameters
Parameter Style Type Description
trust plain xsd:string

A trust object.
expires_at (Optional) plain xsd:dict

The ISO 8601 date time when a trust expires. If you omit this attribute, the trust lasts indefinitely.

id plain csapi:uuid

The ID of the trust.
impersonation plain xsd:boolean

The impersonation flag.
links plain xsd:dict

Trust links.
project_id plain csapi:uuid

The ID of the project.
remaining_uses plain xsd:boolean

Remaining uses flag.
roles plain xsd:dict

A roles object. Includes id, name, and links for any roles.

roles_links plain xsd:dict

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

trustee_user_id plain xsd:string

The trustee user ID.
trustor_user_id plain xsd:string

The trustor user ID.

 
{
    "trust": {
        "expires_at": "2014-12-30T23:59:59.999999Z",
        "impersonation": false,
        "project_id": "'$PROJECT_ID'",
        "roles": [
            {
                "name": "admin"
            }
        ],
        "trustee_user_id": "'$DEMO_USER_ID'",
        "trustor_user_id": "'$ADMIN_USER_ID'"
    }
}

{
    "trust": {
        "expires_at": "2014-12-30T23:59:59.999999Z",
        "id": "394998fa61f14736b1f0c1f322882949",
        "impersonation": false,
        "links": {
            "self": "http://localhost:5000/v3/OS-TRUST/trusts/394998fa61f14736b1f0c1f322882949"
        },
        "project_id": "3d4c2c82bd5948f0bcab0cf3a7c9b48c",
        "remaining_uses": null,
        "roles": [
            {
                "id": "c703057be878458588961ce9a0ce686b",
                "links": {
                    "self": "http://localhost:5000/v3/roles/c703057be878458588961ce9a0ce686b"
                },
                "name": "admin"
            }
        ],
        "roles_links": {
            "next": null,
            "previous": null,
            "self": "http: //localhost:5000/v3/OS-TRUST/trusts/394998fa61f14736b1f0c1f322882949/roles"
        },
        "trustee_user_id": "269348fdd9374b8885da1418e0730af1",
        "trustor_user_id": "3ec3164f750146be97f21559ee4d9c51"
    }
}