Roles resource
Use the following role API operations to view and manage roles and user role assignments.
- List roles for managing service access
- Get role by ID
- List global roles assigned to a user
- List effective roles assigned to a user
- Add role to user
- Grant roles to a user
- Delete global role from user
- List users with role
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 ifuserId
and theuser-default
token have the same value fortenant
.
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
- Through the user itself
- All forms of role assignment such as the following items:
- On domain
- On individual tenants
- On RCN
- On domain
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
oridentity:user-manage
role can list roles for users within their domain and with theidentity: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.
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:
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
andd1t2
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 tenantd2t1
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
andd1t2
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 theidentity:admin
role, users with theidentity:user-admin
role, and sub-users.- Users with the
identity:admin
role can add a role to a user for users with theidentity:user-admin
role and sub-users.- Users with the
identity:user-admin
oridentity:user-manage
role can add a role to a user for users within their domain and with theidentity: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 theidentity:admin
role, users with theidentity:user-admin
role, and sub-users.- Users with the
identity:admin
role can grant roles to a user for users with theidentity:user-admin
role and sub-users.- Users with the
identity:user-admin
oridentity:user-manage
role can grant roles to a user for users within their domain and with theidentity: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 theidentity:admin
role, users with theidentity:user-admin
role, and sub-users.- Users with the
identity:admin
role can delete a global role from a user for users with theidentity:user-admin
role and sub-users.- Users with the
identity:user-admin
oridentity:user-manage
role can delete a global role from sub-users within their domain that have theidentity: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 theidentity:manage
role andidentity: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="[email protected]"
enabled="true"/>
<user
rax-auth:contactId="1234"
rax-auth:domainId="5830280"
rax-auth:defaultRegion="DFW"
rax-auth:multiFactorEnabled="false"
id="938439"
username="poejo"
email="[email protected]"
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": "[email protected]",
"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": "[email protected]",
"rax-auth:defaultRegion":"DFW",
"rax-auth:multiFactorEnabled":"false"
}
]
}
Updated 10 months ago