Roles resource#

Use the following role API operations to view and manage roles and user role assignments.

Note

The functionality described in this section is provided by the OS-KSADM extension.

List roles for managing service access#

GET /v2.0/OS-KSADM/roles

Lists available roles for managing access to Rackspace Cloud services.

Use the List roles API operation to retrieve the available roles. The response returns the roles object with information about each role, including the id for the service that the role applies to.

If you use the limit and marker parameter, the previous and next links are in the header.

This table shows the possible response codes for this operation:

Response Code

Name

Description

200

OK

Request completed successfully.

400

Bad Request

The request is missing one or more elements, or the values of some elements are invalid.

401

Unauthorized

You are not authorized to complete this operation. This error can occur if the request is submitted with an invalid authentication token.

403

Forbidden

The request was valid, but the server is refusing to respond because you do not have permission to access the requested resource. Submit a request to your account administrator to determine how to gain access.

404

Not Found

The requested resource was not found.

405

Invalid Method

The method specified in the request is not valid for the resource identified in the request URI.

413

Over Limit

The number of items returned is above the allowed limit.

503

Service Fault

Service is not available.

Request#

This table shows the header parameters for the request:

Name

Type

Description

X-Auth-Token

Header String (Required)

A valid admin authentication token.

This table shows the query parameters for the request:

Name

Type

Description

limit

Int (Optional)

Requests a specified page size of returned items from the query. Returns a number of items up to the specified limit value. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request.

marker

String (Optional)

Specifies the ID of the last-seen item. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request.

This operation does not accept a request body.

Example: Lists available roles to manage service access request: XML

GET /v2.0/OS-KSADM/roles HTTP/1.1
Host: identity.api.rackspacecloud.com
X-Auth-Token:82994d2fb9a0483a85b6ba622c212345
Accept: application/xml
Content-type: application/xml

Example: Lists available roles to manage service access: JSON request

GET /v2.0/OS-KSADM/roles HTTP/1.1
Host: identity.api.rackspacecloud.com
X-Auth-Token:82994d2fb9a0483a85b6ba622c2c4934
Accept: application/json
Content-type: application/json

Response#

This table shows the body parameters for the response:

Name

Type

Description

roles

String

Role object.

roles.id

String

The role ID.

roles.name

String

The role name.

roles.description

String

The role description.

roles.serviceId

String

The id for the Rackspace Cloud service to which the role applies.

roles.RAX-AUTH:propagate

Boolean (Optional)

Indicates whether this role is assigned to an account owner (identity:user-admin) and automatically inherited by all account users (identity:default).

Example: Lists available roles to manage service access: XML response

HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 3872
Connection: keep-alive
Link: <http://identity.api.rackspacecloud.com/cloud/v2.0/OS-KSADM/roles?marker=75&limit=25>; rel="last",
  <http://identity.api.rackspacecloud.com/cloud/v2.0/OS-KSADM/roles?marker=25&limit=25>; rel="next"
<?xml version="1.0" encoding="UTF-8"?>
  <roles
    xmlns:atom="http://www.w3.org/2005/Atom"
    xmlns:rax-auth="http://docs.rackspace.com/identity/api/ext/RAX-AUTH/v1.0"
    xmlns="http://docs.openstack.org/identity/api/v2.0"
    xmlns:ns4="http://docs.rackspace.com/identity/api/ext/RAX-KSGRP/v1.0"
    xmlns:rax-ksqa="http://docs.rackspace.com/identity/api/ext/RAX-KSQA/v1.0"
    xmlns:os-ksadm="http://docs.openstack.org/identity/api/ext/OS-KSADM/v1.0"
    xmlns:rax-kskey="http://docs.rackspace.com/identity/api/ext/RAX-KSKEY/v1.0"
    xmlns:os-ksec2="http://docs.openstack.org/identity/api/ext/OS-KSEC2/v1.0">

    <role id="100" name="devops" description="DevOps center" serviceId="cke5372rw2rty8bb70a0e702a4626977x4406e5" rax-auth:propagate="true"/>
    <role id="30007896" name="acctCreator:public" description="Account creator public role" serviceId="cke5372ebabeeabb70a0e702a4626977x4406e5" rax-auth:propagate="false"/>
    <role id="30007897" name="acctCreator:trusted" description="Account creator trusted role" serviceId="bde1268ebabeeabb70a0e702a4626977c331d5c4" rax-auth:propagate="false"/>
    <role id="30007653" name="database:admin" description="admin role for cloud files" serviceId="bde1268ebabeeabb70a0e702a4626977c331d5c4" rax-auth:propagate="false"/>
</roles>

Example: Lists available roles to manage service access: JSON response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 3872
Connection: keep-alive
Link: <http://identity.api.rackspacecloud.com/cloud/v2.0/OS-KSADM/roles?marker=75&limit=25>; rel="last",
  <http://identity.api.rackspacecloud.com/cloud/v2.0/OS-KSADM/roles?marker=25&limit=25>; rel="next"
{
    "roles": [
        {
            "description": "DevOps center",
            "id": "100",
            "name": "devops",
            "serviceId": "cke5372rw2rty8bb70a0e702a4626977x4406e5"
        },
        {
            "description": "Account creator public role",
            "id": "30007896",
            "name": "acctCreator:public",
            "serviceId": "cke5372ebabeeabb70a0e702a4626977x4406e5"
        },
        {
            "description": "Admin creator trusted role",
            "id": "30007897",
            "name": "acctCreator:trusted",
            "serviceId": "cke5372ebabeeabb70a0e702a4626977x4406e5"
        },
        {
            "description": "Admin role for database service",
            "id": "30007653",
            "name": "database:admin",
            "serviceId": "cke5372ebabeeabb70a0e702a4626977x4406e5"
        },

    ]
}

Get role by ID#

GET /v2.0/OS-KSADM/roles/{roleId}

This operation retrieves information about the specified role ID.

This table shows the possible response codes for this operation:

Response Code

Name

Description

200

OK

Request completed successfully.

400

Bad Request

The request is missing one or more elements, or the values of some elements are invalid.

401

Unauthorized

You are not authorized to complete this operation. This error can occur if the request is submitted with an invalid authentication token.

403

Forbidden

The request was valid, but the server is refusing to respond because you do not have permission to access the requested resource. Submit a request to your account administrator to determine how to gain access.

404

Not Found

The requested resource was not found.

405

Invalid Method

The method specified in the request is not valid for the resource identified in the request URI.

413

Over Limit

The number of items returned is above the allowed limit.

415

Bad Media Type

Bad media type. This may result if the wrong media type is used in the API request. Check the content-type and accept headers included in the request.

503

Service Fault

Service is not available.

Request#

This table shows the header and URI parameters for the request:

Name

Type

Description

X-Auth-Token

Header String (Required)

A valid admin authentication token.

{userId}

URI String (Required)

A user ID assigned by system when user is added.

This operation does not accept a request body.

Example: Get role by ID request: XML

GET /v2.0/OS-KSADM/roles/10000209 HTTP/1.1
Host: identity.api.rackspacecloud.com
X-Auth-Token:82994d2fb9a0483a85b6ba622c2c4934
Accept: application/xml
Content-type: application/xml

Example: Get role by ID request: JSON

GET /v2.0/OS-KSADM/roles/10000209 HTTP/1.1
Host: identity.api.rackspacecloud.com
X-Auth-Token:82994d2fb9a0483a85b6ba622c2c4934
Accept: application/json
Content-type: application/json

Response#

This table shows the body parameters for the response:

Name

Type

Description

role

Object

Returns the information role information for the specified role ID.

role.id

Int

The role ID.

role.name

String

The role name.

role.description

String

The role description.

role.serviceId

String

The id for the Rackspace Cloud service to which the role applies.

role.RAX-AUTH:propagate

Boolean (Optional)

Indicates whether this role is assigned to an account owner (identity:user-admin) and automatically inherited by all account users (identity:default).

Example: Get role by ID response: XML

HTTP/1.1 200 OK
Content-Type: application/xml
<?xml version="1.0" encoding="UTF-8"?>

<role xmlns="http://docs.openstack.org/identity/api/v2.0"
  id="123" name="database:admin" description="Admin role for database service" \
  serviceId="abc4321ebabeeabb70a0e702a4626977c331d5c4" rax-auth:propagate="false"/>

Example: Get role by ID response: JSON

HTTP/1.1 200 OK
Content-Type: application/json
{
  "role": {
    "id": "123",
    "serviceId": "abc4321ebabeeabb70a0e702a4626977c331d5c4"
    "description": "Admin role for database service",
    "name": "database:admin",
    "RAX-AUTH:propagate": false
  }
}

List global roles assigned to a user#

GET /v2.0/users/{userId}/roles

This operation returns a list of global roles that are assigned to the account with the specified user Id. If you don’t know the ID, use the list users operation to find it.

For each role listed, the response includes identifying information such as the role ID (such as 123 ), name (such as Admin, and description (such as All Access). The list of global roles excludes any tenant roles associated with this user.

Note

  • This call is available to users who hold either the admin role (identity:user-admin) or the user role ( identity:default ).

  • For users holding the user role, the call is valid only if userId and the user-default token have the same value for tenant.

This table shows the possible response codes for this operation:

Response Code

Name

Description

200

OK

Request completed successfully.

400

Bad Request

The request is missing one or more elements, or the values of some elements are invalid.

401

Unauthorized

You are not authorized to complete this operation. This error can occur if the request is submitted with an invalid authentication token.

403

Forbidden

The request was valid, but the server is refusing to respond because you do not have permission to access the requested resource. Submit a request to your account administrator to determine how to gain access.

404

Not Found

The requested resource was not found.

405

Invalid Method

The method specified in the request is not valid for the resource identified in the request URI.

413

Over Limit

The number of items returned is above the allowed limit.

503

Service Fault

Service is not available.

Request#

This table shows the URI parameters for the request:

Name

Type

Description

X-Auth-Token

String (Required)

You need a valid admin token for access.

{userId}

String (Required)

The ID of the user for which you want to perform the request.

This table shows the query parameters for the request:

Name

Type

Description

serviceId

String (Optional)

Allows filtering the requested roles for user by service ID.

apply_rcn_roles

Boolean (Optional)

When true, RCN roles assigned to the user are returned. Defaults to false.

domainId

String (Optional)

Filter roles that have been granted to a user under the specified domain ID.

This operation does not accept a request body.

Example List global roles assigned to a user: XML request

GET /v2.0/users/123456/roles HTTP/1.1
Host: identity.api.rackspacecloud.com
X-Auth-Token: 771dd18634734a46b49f2af620112345
Accept: application/xml
Content-type: application/xml

Example List global roles assigned to a user: JSON request

GET /v2.0/users/123456/roles HTTP/1.1
Host: identity.api.rackspacecloud.com
X-Auth-Token: 771dd18634734a46b49f2af620112345
Accept: application/json
Content-type: application/json

Response#

Example List global roles assigned to a user: XML response

 <?xml version="1.0" encoding="UTF-8"?>
     <roles
     xmlns:atom="http://www.w3.org/2005/Atom"
     xmlns:rax-auth="http://docs.rackspace.com/identity/api/ext/RAX-AUTH/v1.0"
     xmlns="http://docs.openstack.org/identity/api/v2.0"
     xmlns:ns4="http://docs.rackspace.com/identity/api/ext/RAX-KSGRP/v1.0"
     xmlns:rax-ksqa="http://docs.rackspace.com/identity/api/ext/RAX-KSQA/v1.0"
     xmlns:os-ksadm="http://docs.openstack.org/identity/api/ext/OS-KSADM/v1.0"
     xmlns:rax-kskey="http://docs.rackspace.com/identity/api/ext/RAX-KSKEY/v1.0"
     xmlns:os-ksec2="http://docs.openstack.org/identity/api/ext/OS-KSEC2/v1.0">

     <role id="100" name="devops" description="DevOps center" serviceId="cke5372rw2rty8bb70a0e702a4626977x4406e5" rax-auth:propagate="true"/>
     <role id="30007896" name="acctCreator:public" description="Account creator public role" serviceId="cke5372ebabeeabb70a0e702a4626977x4406e5" rax-auth:propagate="false"/>
     <role id="30007897" name="acctCreator:trusted" description="Account creator trusted role" serviceId="bde1268ebabeeabb70a0e702a4626977c331d5c4" rax-auth:propagate="false"/>
     <role id="30007653" name="database:admin" description="admin role for cloud files" serviceId="bde1268ebabeeabb70a0e702a4626977c331d5c4" rax-auth:propagate="false"/>
     <role id="123" name="rcnRole" description="An RCN role" serviceId="12345678" rax-auth:roleType="RCN">
         <rax-auth:types>
             <rax-auth:type>*</rax-auth:type>
         </rax-auth:types>
     </role>
</roles>

Example List global roles assigned to a user: JSON response

 {
     "roles": [
         {
             "description": "DevOps center",
             "id": "100",
             "name": "devops",
             "serviceId": "cke5372rw2rty8bb70a0e702a4626977x4406e5"
         },
         {
             "description": "Account creator public role",
             "id": "30007896",
             "name": "acctCreator:public",
             "serviceId": "cke5372ebabeeabb70a0e702a4626977x4406e5"
         },
         {
             "description": "Admin creator trusted role",
             "id": "30007897",
             "name": "acctCreator:trusted",
             "serviceId": "cke5372ebabeeabb70a0e702a4626977x4406e5"
         },
         {
             "description": "Admin role for database service",
             "id": "30007653",
             "name": "database:admin",
             "serviceId": "cke5372ebabeeabb70a0e702a4626977x4406e5"
         },
         {
             "description": "An RCN role",
             "id": "123",
             "name": "rcnRole",
             "serviceId": "12345678",
             "RAX-AUTH:roleType": "RCN",
             "RAX-AUTH:types": [
                 "*"
             ],
         },
     ]
}

List effective roles assigned to a user#

GET /v2.0/users/{userId}/RAX-AUTH/roles

This operation returns the list of all roles that are assigned to the user with the specified userId. If you don’t know the user ID, use the List users operation with query parameter name to find it.

For each role listed, the response includes identifying information such as the role ID, name, the tenants to which the role is assigned, and the sources that determined how the user received the role on the specified tenants.

This calls differs from the similar List global roles assigned to a user call because it includes the following things:

  • All means by which a user can be granted a role such as the following:

    • Through the user itself

    • Through membership in a user group

    • Through the system

  • All forms of role assignment such as the following items:

    • On domain

    • On individual tenants

    • On RCN

The List global roles assigned to a user call accounts only for roles assigned through the user on the domain.

Note

  • Users can always use this service to list roles for themselves.

  • Users with the identity:user-admin or identity:user-manage role can list roles for users within their domain and with the identity:default role.

Response code

Name

Description

200

OK

The request has been fulfilled. The roles have been retrieved.

401

Unauthorized

You are not authorized to complete this operation. This error can occur if the request is submitted with an invalid authentication token.

403

Forbidden

The request was valid, but the server is refusing to respond because you do not have permission to access the requested resource. Submit a request to your account administrator to determine how to gain access.

404

Not Found

The requested resource was not found.

405

Invalid Method

The method specified in the request is not valid for the resource identified in the request URI.

406

Not Acceptable

The server cannot send data in a format requested.

413

Over Limit

The number of items returned is above the allowed limit.

503

Service Fault

Service is not available.

Request#

This table shows the header parameters for the request:

Name

Type

Description

X-Auth-Token

String (Required)

A valid authentication token.

This table shows the URI parameters for the request:

Name

Type

Description

{userId}

String

The ID of the user for which roles should be returned.

This table shows the query parameters for the request:

Name

Type

Description

onTenantId

String (Optional)

Filter roles that have been granted on the specified tenantId for the user.

This operation does not accept a request body.

Example List global roles assigned to a user: XML request

GET /v2.0/users/123456/RAX-AUTH/roles HTTP/1.1
Host: identity.api.rackspacecloud.com
X-Auth-Token: 771dd18634734a46b49f2af620112345
Accept: application/xml
Content-type: application/xml

Example List global roles assigned to a user: JSON request

GET /v2.0/users/123456/RAX-AUTH/roles HTTP/1.1
Host: identity.api.rackspacecloud.com
X-Auth-Token: 771dd18634734a46b49f2af620112345
Accept: application/json
Content-type: application/json

Response#

The response groups return data by role. Each role is shown as a tenantAssignment and with all tenants on which the user has the role are included, regardless of the tenant’s domain.

Name

Type

Description

RAX-AUTH:roleAssignments

Object (Required)

A role assignments entity.

RAX-AUTH:roleAssignments.tenantAssignments

Object (Required)

An array of tenant assignments.

RAX-AUTH:roleAssignments.tenantAssignments.onRole

String (Required)

Role ID for tenant assignment.

RAX-AUTH:roleAssignments.tenantAssignments.onRoleName

String (Required)

Role name for tenant assignment.

RAX-AUTH:roleAssignments.tenantAssignments.forTenants

String (Required)

An array of tenant IDs to which the role is assigned. This is the union of all tenants across all sources for the role.

RAX-AUTH:roleAssignments.tenantAssignments.sources

An array of sources (Required)

An array of sources which grant the user the role on the specified tenant(s).

RAX-AUTH:roleAssignments.tenantAssignments.sources.sourceType

String (Required)

The source of the role assignment. This can be one of the following items:

  • USER

  • USERGROUP

  • SYSTEM

RAX-AUTH:roleAssignments.tenantAssignments.sources.sourceId

String (Required)

A unique identifier for the source. For users and groups this is the respective id. For SYSTEM, this is the source system (e.g. IDENTITY).

RAX-AUTH:roleAssignments.tenantAssignments.sources.assignmentType

String (Required)

How tenants are determined for the source. This can be one of the following items:

  • DOMAIN

  • TENANT

  • RCN

RAX-AUTH:roleAssignments.tenantAssignments.sources.forTenants

Array of Strings (Required)

The list of tenants to which the source grants the user the role.

Sources#

The response includes one or more sources for each role that the user has assigned. Each source includes a source type, source ID, assignment type, and tenants on which that source granted the user the specified role.

SourceType and SourceId#

A user can receive a given role through multiple methods, as shown in the following table.

Source Type#

Type

Description

USER

Direct role assignment to the user

USERGROUP

Indirect assignment to the user via user groups

SYSTEM

Identity System level functionality that automatically assigns certain roles

The sourceId identifies the ID of the sourceType. For example, the sourceId for the source with a USER source type is the ID of the user to which the role was directly assigned, whereas the sourceId for a USERGROUP type would be the ID of the user group.

Assignment type#

Role assignments are classified based on how the tenants, for which those assignments apply, are determined. The classifications are shown in the following table:

Source type#

Type

Description

DOMAIN

Assignment applied to all tenants within the user’s domain.

TENANT

Assignment only applies to tenants to which the role was explicitly assigned.

RCN

Applies to all tenants across all domains within the RCN for which the RCN role applies.

Examples#

Generic Example Response

This example is contrived to show the different sourceTypes in a single example and is not meant to represent a real-world example.

JSON:

{
   "RAX-AUTH:roleAssignments": {
       "tenantAssignments": [
           {
               "onRole": "1234",
               "onRoleName": "roleName",
                "forTenants": [
                    "t1",
                    "t2"
                ],
               "sources": [
                 {
                      "sourceType": "USER",
                      "sourceId": "userId",
                      "assignmentType": "DOMAIN"
                      "forTenants": [
                         "t1",
                         "t2"
                      ]
                 },
                 {
                      "sourceType": "USERGROUP",
                      "sourceId": "UserGroupAId",
                      "assignmentType": "DOMAIN",
                      "forTenants": [
                         "t1",
                         "t2"
                      ]
                 },
                 {
                      "sourceType": "USERGROUP",
                      "sourceId": "UserGroupBId",
                      "assignmentType": "TENANT",
                      "forTenants": [
                         "t1",
                         "t2"
                      ]
                 },
                 {
                      "sourceType": "USERGROUP",
                      "sourceId": "UserGroupCId",
                      "assignmentType": "TENANT",
                      "forTenants": [
                         "t1"
                      ]
                 },
                 {
                      "sourceType": "SYSTEM",
                      "sourceId": "IDENTITY",
                      "assignmentType": "TENANT",
                      "forTenants": [
                         "t2"
                      ]
                 }
               ]
           }
       ]
   }
}

Across Domains Assignment Example Response

This example depends on the following assumptions:

  • d1t1 and d1t2 are tenants within the same domain (Domain 1).

  • d2t1 is a tenant in a different domain (Domain 2).

  • The user has the ‘observer’ role assigned on tenant d1t1, d1t2 in Domain 1 and on tenant d2t1 on Domain 2.

JSON:

{
   "RAX-AUTH:roleAssignments": {
       "tenantAssignments": [
           {
               "onRole": "8899",
               "onRoleName": "observer",
               "forTenants": [
                    "d1t1",
                    "d1t2",
                    "d2t1"
                ],
               "sources": [
                 {
                      "sourceType": "USER",
                      "sourceId": "userId",
                      "assignmentType": "DOMAIN",
                      "forTenants": [
                        "d1t1",
                        "d1t2",
                        "d2t1"
                    ]
                 }
               ]
           }
       ]
   }
}

RCN Role Example Response

This example depends on the following assumptions:

  • The user’s RCN contains the domain Domain 1 with the d1t1 and d1t2 tenants.

  • The user’s RCN contains the domain Domain 2 with the d2t1 tenants.

  • The RCN role applies to all the mentioned tenants.

JSON:

{
   "RAX-AUTH:roleAssignments": {
       "tenantAssignments": [
           {
               "onRole": "8899",
               "onRoleName": "rcn:admin",
               "forTenants": [
                  "d1t1",
                  "d1t2",
                  "d2t1"
               ],
               "sources": [
                  {
                     "sourceType": "USER",
                     "sourceId": "userId",
                     "assignmentType": "RCN"
                     "forTenants": [
                        "d1t1",
                        "d1t2",
                        "d2t1"
                     ]
                  }
               ]
           }
       ]
   }
}

User without Tenants Example Response

A user could be assigned a role that doesn’t apply to any current tenants for the user. For example, the user may have only DOMAIN roles on a domain with no tenants. The user could also be assigned an RCN role that doesn’t match any tenant within the user’s RCN. The service returns the role, but shows that that source doesn’t apply to any tenants.

This example depends on the following assumptions:

  • The user’s domain does not contain any tenants.

  • The user has the identity:user-admin role.

JSON:

{
   "RAX-AUTH:roleAssignments": {
       "tenantAssignments": [
           {
               "onRole": "3",
               "onRoleName": "identity:user-admin",
               "forTenants": [],
               "sources": [
                 {
                      "sourceType": "USER",
                      "sourceId": "userId",
                      "assignmentType": "DOMAIN"
                      "forTenants": []
                 }
               ]
           }
       ]
   }
}

Add role to user#

PUT /v2.0/users/{userId}/roles/OS-KSADM/{roleid}

Adds a specific multi-product or custom (product-specific) role to a user.

Use this operation to add a specific multi-product or custom (product-specific) role to a user.

To add a role, specify the roleId and the userId in the request. Use the List roles and List users operations to find the ids.

If an Identity service Administrator (identity:service-admin) assigns a role to an account owner (identity:user-admin), the role is propagated to all account users (identity:default).

Note

  • Users with the identity:service-admin role can add a role to a user for users with the identity:admin role, users with the identity:user-admin role, and sub-users.

  • Users with the identity:admin role can add a role to a user for users with the identity:user-admin role and sub-users.

  • Users with the identity:user-admin or identity:user-manage role can add a role to a user for users within their domain and with the identity:default role.

This table shows the possible response codes for this operation:

Response Code

Name

Description

200

OK

Request completed successfully.

400

Bad Request

The request is missing one or more elements, or the values of some elements are invalid.

401

Unauthorized

You are not authorized to complete this operation. This error can occur if the request is submitted with an invalid authentication token.

403

Forbidden

The request was valid, but the server is refusing to respond because you do not have permission to access the requested resource. Submit a request to your account administrator to determine how to gain access.

404

Not Found

The requested resource was not found.

405

Invalid Method

The method specified in the request is not valid for the resource identified in the request URI.

413

Over Limit

The number of items returned is above the allowed limit.

415

Bad Media Type

Bad media type. This may result if the wrong media type is used in the API request. Check the content-type and accept headers included in the request.

503

Service Fault

Service is not available.

Request#

This table shows the header and URI parameters for the request:

Name

Type

Description

X-Auth-Token

Header String (Required)

A valid admin authentication token.

{userId}

URI String (Required)

A user ID assigned by system when user is added.

{roleId}

String (Required)

A role Id.

This operation does not accept a request body.

Example Add role to user: XML request

PUT /v2.0/users/123456/roles/OS-KSADM/30007896 HTTP/1.1
Host: identity.api.rackspacecloud.com
X-Auth-Token:82994d2fb9a0483a85b6ba622c212345
Accept: application/xml
Content-type: application/xml

Example Add role to user: JSON request

PUT /v2.0/users/123456/roles/OS-KSADM/30007896 HTTP/1.1
Host: identity.api.rackspacecloud.com
X-Auth-Token:82994d2fb9a0483a85b6ba622c212345
Accept: application/json
Content-type: application/json

Response#

This operation does not return a response body.

Grant roles to a user#

PUT /v2.0/users/{userId}/RAX-AUTH/roles

Grant roles to a provisioned user. Existing roles set on the user that are not being modified remain unchanged.

Note

  • Users with the identity:service-admin role can grant roles to a user for users with the identity:admin role, users with the identity:user-admin role, and sub-users.

  • Users with the identity:admin role can grant roles to a user for users with the identity:user-admin role and sub-users.

  • Users with the identity:user-admin or identity:user-manage role can grant roles to a user for users within their domain and with the identity:default role.

  • The caller must have at least the identity:user-manage role. If the caller has only domain access, verify that the caller’s domain matches the target user’s domain.

  • The tenants on assignments must belong to the same domain as the target user’s domain.

  • The role assignments cannot assign identity user type roles with the exception of identity:user-manage.

  • The caller must be authorized to assign the specified roles.

  • The tenant assignments can include either [“*”] or a set of tenant ids.

  • This request effectively replaces any assignment that already exists for these roles on the user.

This table shows the possible response codes for this operation:

Response code

Name

Description

200

OK

The request has been fulfilled.

400

Bad Request

The request is missing one or more elements, or the values of some elements are invalid.

401

Unauthorized

You are not authorized to complete this operation. This error can occur if the request is submitted with an invalid authentication token.

403

Forbidden

The request was valid, but the server is refusing to respond because you do not have permission to access the requested resource. Submit a request to your account administrator to determine how to gain access.

404

Not Found

The requested resource was not found.

405

Invalid Method

The method specified in the request is not valid for the resource identified in the request URI.

406

Not Acceptable

The server cannot send data in a format requested.

413

Over Limit

The number of items returned is above the allowed limit.

503

Service Fault

Service is not available.

Request#

This table shows the header parameters for the request:

Name

Type

Description

X-Auth-Token

String (Required)

A valid authentication token.

This table shows the URI parameters for the request:

Name

Type

Description

{userId}

String

A user ID.

This table shows the body parameters for the request:

Name

Type

Description

RAX-AUTH:roleAssignments

Object (Required)

A role assignments entity.

RAX-AUTH:roleAssignments.tenantAssignments

Object (Required)

An array of tenant assignments.

RAX-AUTH:roleAssignments.tenantAssignments.onRole

String (Required)

Role ID for tenant assignment.

RAX-AUTH:roleAssignments.tenantAssignments.forTenants

Object (Required)

An array of tenant IDs. Use [“*”] for global tenant assignment.

Example: Grant roles to a user request: XML

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<rax-auth:roleAssignments
    xmlns="http://docs.openstack.org/identity/api/v2.0"
    xmlns:rax-auth="http://docs.rackspace.com/identity/api/ext/RAX-AUTH/v1.0">
     <rax-auth:tenantAssignments>
        <rax-auth:tenantAssignment forTenants="t1 t2" onRole="1234"/>
    </rax-auth:tenantAssignments>
</rax-auth:roleAssignments>

Example: Grant roles to a user request: JSON

{
    "RAX-AUTH:roleAssignments": {
        "tenantAssignments": [
            {
                "onRole": "1234",
                 "forTenants": [
                     "t1",
                     "t2"
                 ]
            }
        ]
    }
}

Response#

Example: Grant roles to a user response: XML

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<rax-auth:roleAssignments
    xmlns="http://docs.openstack.org/identity/api/v2.0"
    xmlns:rax-auth="http://docs.rackspace.com/identity/api/ext/RAX-AUTH/v1.0">
     <rax-auth:tenantAssignments>
        <rax-auth:tenantAssignment forTenants="*" onRoleName="identity:user-admin" onRole="3"/>
        <rax-auth:tenantAssignment forTenants="t1 t2" onRoleName="roleName" onRole="1234"/>
    </rax-auth:tenantAssignments>
</rax-auth:roleAssignments>

Example: Grant roles to a user response: JSON

{
    "RAX-AUTH:roleAssignments": {
        "tenantAssignments": [
            {
                "onRole": "3",
                "onRoleName": "identity:user-admin"
                "forTenants": [
                    "*"
                ],
            },
            {
                "onRole": "1234",
                "onRoleName": "roleName",
                 "forTenants": [
                     "t1",
                     "t2"
                 ]
            }
        ]
    }
}

Delete global role from user#

DELETE /v2.0/users/{userId}/roles/OS-KSADM/{roleid}

Use this operation to delete a multi-product or custom (product-specific) role from a user account.

When you submit the request, include the system-assigned role id and user id in the request. Use the List role and List user operations to find the correct ids.

The DELETE operation allows the account owner (identity:user-admin) to manage non-protected role assignment for users (identity:default), granting and revoking access at will. Some roles like identity:rack_connect and identity:rax_managed cannot be managed by customers to prevent them from revoking privileges unintentionally.

Note

  • Users with the identity:service-admin role can delete a global role from a user for users with the identity:admin role, users with the identity:user-admin role, and sub-users.

  • Users with the identity:admin role can delete a global role from a user for users with the identity:user-admin role and sub-users.

  • Users with the identity:user-admin or identity:user-manage role can delete a global role from sub-users within their domain that have the identity:default role.

This table shows the possible response codes for this operation:

Response Code

Name

Description

204

No content

The request succeeded. The server fulfilled the request but does not need to return a body.

400

Bad Request

The request is missing one or more elements, or the values of some elements are invalid.

401

Unauthorized

You are not authorized to complete this operation. This error can occur if the request is submitted with an invalid authentication token.

403

Forbidden

The request was valid, but the server is refusing to respond because you do not have permission to access the requested resource. Submit a request to your account administrator to determine how to gain access.

404

Not Found

The requested resource was not found.

405

Invalid Method

The method specified in the request is not valid for the resource identified in the request URI.

413

Over Limit

The number of items returned is above the allowed limit.

503

Service Fault

Service is not available.

Request#

This table shows the header and URI parameters for the request:

Name

Type

Description

X-Auth-Token

Header String (Required)

A valid admin authentication token.

{userId}

URI String (Required)

A user ID assigned by system when user is added.

{roleId}

String (Required)

A role Id.

This operation does not accept a request body.

Example Delete global role from user: XML request

DELETE /v2.0/users/123456/roles/OS-KSADM/30007896 HTTP/1.1
Host: identity.api.rackspacecloud.com
X-Auth-Token:82994d2fb9a0483a85b6ba622c212345
Accept: application/xml
Content-type: application/xml

Example Delete global role from user: JSON request

DELETE /v2.0/users/123456/roles/OS-KSADM/30007896 HTTP/1.1
Host: identity.api.rackspacecloud.com
X-Auth-Token:82994d2fb9a0483a85b6ba622c212345
Accept: application/json
Content-type: application/json

Response#

This operation does not return a response body.

List users with role#

GET /v2.0/OS-KSADM/roles/{roleId}/RAX-AUTH/users

This operation returns a list of users with detailed account information about each user, including email, name, user ID, phone pin state, account configuration, and status information assigned to the specified role ID.

Note

  • Users with the identity:user-admin role can list sub-users within their domain that have the identity:manage role and identity:default role assigned to a specified role.

This table shows the possible response codes for this operation:

Response code

Name

Description

200

OK

The request has succeeded.

400

Bad Request

The request was invalid.

401

Unauthorized

You are not authorized to complete this operation. This error can occur if the request is submitted with an invalid authentication token.

403

Forbidden

Caller does not have an appropriate role.

404

Not Found

The requested resource was not found.

405

Invalid Method

The method specified in the request is not valid for the resource identified in the request URI.

413

Over Limit

The number of items returned is above the allowed limit.

503

Service Fault

Service is not available.

Request#

This table shows the header and URI parameters for the request:

Name

Type

Description

X-Auth-Token

Header String (Required)

A valid authentication token.

{roleId}

URI String (Required)

A role id assigned by a system when role is added.

This table shows the query parameters for the request:

Name

Type

Description

limit

Int (Optional)

Requests a specified page size of returned items from the query. Returns a number of items up to the specified limit value. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request.

marker

String (Optional)

Specifies the ID of the last-seen item. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request.

This operation does not accept a request body.

Example: List users: HTTP request

GET /v2.0/OS-KSADM/roles/10010175/RAX-AUTH/users HTTP/1.1
Host: identity.api.rackspacecloud.com
Accept: application/xml
X-Auth-Token: 0cb090705e82443fa71471e9c3456789
Content-type: application/xml

Example: List users: HTTP request

GET /v2.0/OS-KSADM/roles/10010175/RAX-AUTH/users HTTP/1.1
Host: identity.api.rackspacecloud.com
Accept: application/json
X-Auth-Token: 0cb090705e82443fa71471e9c3456789
Content-type: application/json

Response#

This table shows the body parameters for the response:

Name

Type

Description

users

Object (Required)

Returns the collection of users who match the specification in the List user API request.

users.user

Object (Required)

A user object that provides user account information.

user.RAX-AUTH:phonePinState

String (Required)

The phone pin state.

  • INACTIVE The user does not have a phone pin.

  • LOCKED The user has a phone pin, but the pin has been locked due to excessive failed verification attempts. The user must unlock the pin before pin verifications can occur.

  • ACTIVE The user has a phone pin against which verifications can be performed.

user.RAX-AUTH:defaultRegion

String (Optional)

The default region that the user is assigned to. Must be one of the regions available in the service catalog.

user.RAX-AUTH:domainId

String (Optional)

The ID for the domain that the user account has been assigned to.

user.RAX-AUTH:multiFactorEnabled

Boolean (Optional)

If an account has been configured to use multi-factor authentication, this field indicates if multi-factor authentication is currently enabled or disabled.

user.RAX-AUTH:multiFactorState

String (Optional)

This extended attribute indicates if a multifactor-enabled user account is locked as a result of failed authentication attempts. If the account has been locked at any point, the value is either LOCKED or ACTIVE. User administrators can use the Update multi-factor authentication settings on account operation to restore access to a locked account.

user.RAX-AUTH:userMultiFactorEnforcementLevel

String (Optional)

If present, this extended attribute specifies the multi-factor authentication enforcement policy that applies to the specified account.

  • REQUIRED The user must use multi-factor authentication to log in to their Rackspace Cloud account.

  • OPTIONAL. The user has the option to authenticate using multi-factor authentication.

  • DEFAULT. The user multi-factor authentication requirements are determined by the domain level enforcement setting for multi-factor authentication.

user.RAX-AUTH:contactId

String (Optional)

The core contact ID.

user.RAX-AUTH:passwordExpiration

String (Optional)

If present, this extended attribute specifies the time when the user’s current password will expire.

Example List user with role: HTTP response

HTTP/1.1 200 OK
Content-Type: application/xml

Example List user with role: XML response

<?xml version="1.0" encoding="UTF-8"?>
<users
      xmlns:atom="http://www.w3.org/2005/Atom"
      xmlns:rax-auth="http://docs.rackspace.com/identity/api/ext/RAX-AUTH/v1.0"
      xmlns="http://docs.openstack.org/identity/api/v2.0"
      xmlns:ns4="http://docs.rackspace.com/identity/api/ext/RAX-KSGRP/v1.0"
      xmlns:rax-ksqa="http://docs.rackspace.com/identity/api/ext/RAX-KSQA/v1.0"
      xmlns:os-ksadm="http://docs.openstack.org/identity/api/ext/OS-KSADM/v1.0"
      xmlns:rax-kskey="http://docs.rackspace.com/identity/api/ext/RAX-KSKEY/v1.0"
      xmlns:os-ksec2="http://docs.openstack.org/identity/api/ext/OS-KSEC2/v1.0" >

      <user
            rax-auth:domainId="5830280"
            rax-auth:defaultRegion="DFW"
            rax-auth:multiFactorEnabled="true"
            rax-auth:multiFactorState="ACTIVE"
            rax-auth:userMultiFactorEnforcementLevel="OPTIONAL"
            rax-auth:multi
            id="123456"
            username="jqsmith"
            email="john.smith@example.org"
            enabled="true"/>

      <user
            rax-auth:contactId="1234"
            rax-auth:domainId="5830280"
            rax-auth:defaultRegion="DFW"
            rax-auth:multiFactorEnabled="false"
            id="938439"
            username="poejo"
            email="poe.joe@object.org"
            enabled="true"/>
</users>

Example List user with role: HTTP response

HTTP/1.1 200 OK
Content-Type: application/json

Example List user with role: JSON response

{
  "users": [
    {
      "rax-auth:domainId":"5830280"
      "id": "123456",
      "enabled": true,
      "username": "jqsmith",
      "email": "john.smith@example.org",
      "rax-auth:defaultRegion":"DFW",
      "rax-auth:phonePinState": "ACTIVE",
      "rax-auth:multiFactorEnabled":"true",
      "rax-auth:multiFactorState":"ACTIVE",
      "rax-auth:userMultiFactorEnforcementLevel":"OPTIONAL"
    },
    {
      "rax-auth:contactId":"1234",
      "rax-auth:domainId":"5830280",
      "id": "938439",
      "enabled": false,
      "username": "poejo",
      "email": "poe.joe@example.org",
      "rax-auth:defaultRegion":"DFW",
      "rax-auth:multiFactorEnabled":"false"
      }
  ]
}