diff --git a/api-ref/src/docbkx/ch_identity-v3.xml b/api-ref/src/docbkx/ch_identity-v3.xml index 4458bc6b1..49cb4e712 100644 --- a/api-ref/src/docbkx/ch_identity-v3.xml +++ b/api-ref/src/docbkx/ch_identity-v3.xml @@ -8,16 +8,27 @@ version="5.0-extension RackBook-2.0" xml:id="identity-v3" role="api-reference"> Identity API v3 (CURRENT) - Gets an authentication token that permits access to the - OpenStack services REST API. + Gets an authentication token that permits access to the OpenStack + services REST API. + + + Like most OpenStack projects, OpenStack Identity protects its APIs by - defining policy rules based on a role-based access control (RBAC) approach. - These rules are stored in a JSON policy file. The Identity service - configuration file, keystone.conf, sets the name and - location of this policy file. For information about Identity API - protection, see Identity API protection with role-based access control - (RBAC) in the OpenStack Cloud Administrator Guide. + defining policy rules based on a role-based access control (RBAC) + approach. + + + The Identity service keystone.conf + configuration file sets the name and location of a JSON policy file + that stores these rules. + + + For information about Identity API protection, see Identity + API protection with role-based access control (RBAC) in the + OpenStack Cloud Administrator Guide.
API versions @@ -305,4 +316,24 @@
+
+ Regions + Manages regions. + + A region is a general division of an OpenStack deployment. + You can associate zero or more sub-regions with a region + to create a tree-like structured hierarchy. + + + Although a region does not have a geographical connotation, a + deployment can use a geographical name for a region, such as + us-east. + + + + + + + +
diff --git a/api-ref/src/wadls/identity-api/src/v3/samples/RegionCreateRequest.json b/api-ref/src/wadls/identity-api/src/v3/samples/RegionCreateRequest.json new file mode 100644 index 000000000..c727283e0 --- /dev/null +++ b/api-ref/src/wadls/identity-api/src/v3/samples/RegionCreateRequest.json @@ -0,0 +1,6 @@ +{ + "region": { + "description": "US West Subregion 1", + "parent_region_id": "829551" + } +} diff --git a/api-ref/src/wadls/identity-api/src/v3/samples/RegionCreateResponse.json b/api-ref/src/wadls/identity-api/src/v3/samples/RegionCreateResponse.json new file mode 100644 index 000000000..8deed6a24 --- /dev/null +++ b/api-ref/src/wadls/identity-api/src/v3/samples/RegionCreateResponse.json @@ -0,0 +1,11 @@ +{ + "region": { + "description": "US West Subregion 1", + "id": "8ebd7f", + "links": { + "self": "https://identity:35357/v3/regions/8ebd7f", + "child_regions": "https://identity:35357/v3/regions?parent_region_id=8ebd7f" + }, + "parent_region_id": "829551" + } +} diff --git a/api-ref/src/wadls/identity-api/src/v3/samples/RegionGetResponse.json b/api-ref/src/wadls/identity-api/src/v3/samples/RegionGetResponse.json new file mode 100644 index 000000000..722922782 --- /dev/null +++ b/api-ref/src/wadls/identity-api/src/v3/samples/RegionGetResponse.json @@ -0,0 +1,11 @@ +{ + "region": { + "description": "US Southwest Region", + "id": "us-southwest", + "links": { + "self": "https://identity:35357/v3/regions/us-southwest", + "child_regions": "http://identity:35357/v3/regions?parent_region_id=us-southwest" + }, + "parent_region_id": "us-west-coast" + } +} diff --git a/api-ref/src/wadls/identity-api/src/v3/samples/RegionUpdateRequest.json b/api-ref/src/wadls/identity-api/src/v3/samples/RegionUpdateRequest.json new file mode 100644 index 000000000..91293ffec --- /dev/null +++ b/api-ref/src/wadls/identity-api/src/v3/samples/RegionUpdateRequest.json @@ -0,0 +1,6 @@ +{ + "region": { + "description": "US Southwest Subregion", + "parent_region_id": "us-southwest" + } +} diff --git a/api-ref/src/wadls/identity-api/src/v3/samples/RegionUpdateResponse.json b/api-ref/src/wadls/identity-api/src/v3/samples/RegionUpdateResponse.json new file mode 100644 index 000000000..0e7a4d153 --- /dev/null +++ b/api-ref/src/wadls/identity-api/src/v3/samples/RegionUpdateResponse.json @@ -0,0 +1,11 @@ +{ + "region": { + "description": "US Southwest Subregion", + "id": "us-southwest-1", + "links": { + "self": "https://identity:35357/v3/regions/us-southwest-1", + "child_regions": "https://identity:35357/v3/regions?parent_region_id=us-southwest-1" + }, + "parent_region_id": "us-southwest" + } +} diff --git a/api-ref/src/wadls/identity-api/src/v3/samples/RegionsListResponse.json b/api-ref/src/wadls/identity-api/src/v3/samples/RegionsListResponse.json new file mode 100644 index 000000000..33b4721bc --- /dev/null +++ b/api-ref/src/wadls/identity-api/src/v3/samples/RegionsListResponse.json @@ -0,0 +1,18 @@ +{ + "regions": [ + { + "description": "US East Region", + "id": "us-east", + "links": { + "self": "https://identity:35357/v3/regions/us-east", + "child_regions": "https://identity:35357/v3/regions?parent_region_id=us-east" + }, + "parent_region_id": "us-east-coast" + } + ], + "links": { + "self": "https://identity:35357/v3/regions", + "previous": null, + "next": null + } +} diff --git a/api-ref/src/wadls/identity-api/src/v3/wadl/common.ent b/api-ref/src/wadls/identity-api/src/v3/wadl/common.ent index 59629324e..cbec94d63 100644 --- a/api-ref/src/wadls/identity-api/src/v3/wadl/common.ent +++ b/api-ref/src/wadls/identity-api/src/v3/wadl/common.ent @@ -415,7 +415,8 @@ identity object. '> + The authentication method, which is @@ -573,7 +574,7 @@ disabled. '> + The endpoint ID. '> @@ -1100,6 +1101,90 @@ The user password. Required for some authentication back ends. '> + + + The region object. + +'> + + + The regions object. + +'> + + + The region description. + +'> + + + + If the region is hierarchically a child of another region, set + this parameter to the ID of the parent region. + + +'> + + + The region description. + + + + + + The ID for the region. + + + + + The + links for the region. + + + + + The ID for the parent region. + + +'> + + + + Filters the results by the specified parent region, by ID. + + +'> + + The + links for the regions resource. +'> GET'> PUT'> diff --git a/api-ref/src/wadls/identity-api/src/v3/wadl/identity-admin-v3.wadl b/api-ref/src/wadls/identity-api/src/v3/wadl/identity-admin-v3.wadl index 3cb8cddae..eff07f77c 100644 --- a/api-ref/src/wadls/identity-api/src/v3/wadl/identity-admin-v3.wadl +++ b/api-ref/src/wadls/identity-api/src/v3/wadl/identity-admin-v3.wadl @@ -433,6 +433,36 @@ + &authTokenHeader; + + + + + The region + ID. + + + + + + + + A user-defined region + ID. + + + + @@ -480,8 +510,9 @@ - Authenticates and generates a - token. + + Authenticates and generates a token. + Each REST request against the Identity Service requires the X-Auth-Token header. Clients obtain this token @@ -517,8 +548,10 @@ scoped by domain ID or name, user ID and password scoped by project ID or name with or without domain scope, or token. - The following examples demonstrate authentication - requests with different types of credentials. + + The following examples demonstrate authentication requests + with different types of credentials. + If scope is included, project id @@ -528,8 +561,10 @@ domain ID or a domain name. - If the authentication token has expired, this call returns the HTTP - 401 status code. + + If the authentication token has expired, this call returns the + HTTP 401 status code. + If the subject token has expired, this call returns the HTTP 404 status code. The Identity API treats expired tokens as no longer valid @@ -540,30 +575,38 @@ response to an authentication request returns the token ID in the X-Subject-Token header instead of in the token data. - If the call has no explicit authorization scope, the - response does not contain the catalog, - project, domain, or - roles fields. However, the response - still uniquely identifies the user. - A token scoped to a project also has - both a service catalog and the user's - roles applicable to the project. + + If the call has no explicit authorization scope, the response + does not contain the catalog, + project, domain, or + roles fields. However, the response still + uniquely identifies the user. + + + A token scoped to a project also has both a + service catalog and the user's roles applicable + to the project. + A token scoped to a domain also has both a service catalog and the user's roles applicable to the project. - Optionally, The Identity API implementation might - return an authentication attribute to - indicate the supported authentication methods. - For authentication processes that require - multiple round trips, The Identity API implementation - might return an HTTP 401 Unauthorized - error with additional information for the next - authentication step. - The following examples illustrate several possible - HTTP 401 Unauthorized authentication errors. Other - errors like HTTP 403 - Forbidden are also - possible. + + Optionally, the Identity API implementation might return an + authentication attribute to indicate the + supported authentication methods. + + + For authentication processes that require multiple round + trips, The Identity API implementation might return an HTTP + Unauthorized (401) status code with additional + information for the next authentication step. + + + The following examples illustrate several possible HTTP + Unauthorized (401) authentication errors. Other + errors, like HTTP Forbidden (403), are also + possible. + @@ -698,12 +741,15 @@ - Validates a specified token. - Pass your own token in the X-Auth-Token - header and the token to be validated in the - X-Subject-Token header. The Identity - API returns the same response as when the subject - token was issued by POST /auth/tokens. + + Validates a specified token. + + + Pass your own token in the X-Auth-Token header. + Pass the token to be validated in the X-Subject-Token + header. The Identity API returns the same + response as when the subject token was issued by POST + /auth/tokens. @@ -739,18 +785,22 @@ - Validates a specified token. - This call is similar to GET - /auth/tokens, but no response body is - provided, even in the X-Subject-Token - header. + + Validates a specified token. + + + This call is similar to GET /auth/tokens but no + response body is provided even in the X-Subject-Token + header. + - The Identity API returns the same response as - when the subject token was issued by POST - /auth/tokens, even if an error occurs - because the token is not valid. A 204 response - indicates that the X-Subject-Token is - valid. + + The Identity API returns the same response as when the + subject token was issued by POST /auth/tokens + even if an error occurs because the token is not valid. An + HTTP 204 status code indicates that the + X-Subject-Token is valid. + @@ -771,13 +821,16 @@ - Revokes a specified token. - This call is similar to HEAD - /auth/tokens, except that the - X-Subject-Token token is immediately - not valid (regardless of the expires_at - attribute). An additional X-Auth-Token is - not required. + + Revokes a specified token. + + + This call is similar to HEAD /auth/tokens except + that the X-Subject-Token token is immediately not + valid, regardless of the expires_at attribute + value. An additional X -Auth-Token is not + required. + @@ -795,8 +848,9 @@ - Lists revoked PKI tokens. - This call shows revoked tokens. + + Lists revoked PKI tokens. + @@ -829,7 +883,9 @@ - Lists services. + + Lists services. + @@ -859,7 +915,9 @@ - Creates a service. + + Creates a service. + @@ -896,8 +954,9 @@ - Shows details for a specified - service. + + Shows details for a specified service. + @@ -921,7 +980,9 @@ - Updates a specified service. + + Updates a specified service. + @@ -951,11 +1012,15 @@ - Deletes a specified service. + + Deletes a specified service. + - Deleting a service when endpoints exist should - either (1) delete all associated endpoints or (2) - fail until endpoints are deleted. + + If you try to delete a service when endpoints exist, this + call either deletes all associated endpoints or fails + until all endpoints are deleted. + @@ -965,7 +1030,9 @@ - Lists available endpoints. + + Lists available endpoints. + @@ -1001,7 +1068,9 @@ - Creates an endpoint. + + Creates an endpoint. + @@ -1036,8 +1105,9 @@ - Updates a specified - endpoint. + + Updates a specified endpoint. + @@ -1072,8 +1142,9 @@ - Deletes a specified - endpoint. + + Deletes a specified endpoint. + &commonFaults; &getFaults; @@ -1082,7 +1153,9 @@ - Lists domains. + + Lists domains. + @@ -1108,7 +1181,9 @@ - Creates a domain. + + Creates a domain. + @@ -1142,8 +1217,9 @@ - Shows details for a specified - domain. + + Shows details for a specified domain. + @@ -1163,7 +1239,9 @@ - Updates a specified domain. + + Updates a specified domain. + @@ -1195,17 +1273,22 @@ - Deletes a specified domain. - To minimize the risk of accidentally deleting a - domain, you must first disable the domain by using the - update domain API. If you try to delete an enabled - domain, the call returns an HTTP 403 - Forbidden response. + + Deletes a specified domain. + + + To minimize the risk of accidentally deleting a domain, you + must first disable the domain by using the update domain method. + If you try to delete an enabled domain, this call returns an + HTTP Forbidden (403) status code. + - Deleting a domain deletes all entities owned by - it, such as users, groups, and projects, as well - as any credentials and granted roles that relate - to those entities. + + When you delete a domain, this call also deletes all + entities owned by it, such as users, groups, and projects, + and any credentials and granted roles that relate to those + entities. + @@ -1214,11 +1297,10 @@ - Lists roles for a user on a - domain. + + Lists roles for a user on a domain. + - - - Grants a role to a specified domain - user. + + Grants a role to a specified domain user. + &commonFaults; &getFaults; @@ -1244,8 +1327,10 @@ - Validates that a user has a role on - a domain. + + Validates that a specified user has a specified role on a + domain. + &commonFaults; &getFaults; @@ -1253,8 +1338,9 @@ - Revokes a role from a specified - domain user. + + Revokes a role from a specified domain user. + &commonFaults; &getFaults; @@ -1262,8 +1348,9 @@ - Lists roles for a specified domain - group. + + Lists roles for a specified domain group. + @@ -1291,8 +1378,10 @@ - Validates that a group has a role - on a domain. + + Validates that a specified group has a specified role on a + domain. + &commonFaults; &getFaults; @@ -1300,8 +1389,9 @@ - Revokes a role from a group on a - domain. + + Revokes a role from a group on a domain. + &commonFaults; &getFaults; @@ -1336,7 +1426,9 @@ - Creates a project. + + Creates a project. + @@ -1368,8 +1460,9 @@ - Shows details for a specified - project. + + Shows details for a specified project. + @@ -1389,7 +1482,9 @@ - Updates a specified project. + + Updates a specified project. + @@ -1419,7 +1514,9 @@ - Deletes a specified project. + + Deletes a specified project. + &commonFaults; &getFaults; @@ -1427,8 +1524,9 @@ - Lists roles for a user in a - project. + + Lists roles for a specified user in a project. + @@ -1447,8 +1545,10 @@ - Grants a role to a user on a - project. + + Grants a role to a specified user in a + project. + &commonFaults; &getFaults; @@ -1456,8 +1556,10 @@ - Validates that a user has a - specified role on a project. + + Validates that a specified user has a + specified role in a project. + &commonFaults; &getFaults; @@ -1465,8 +1567,10 @@ - Revokes a role from a project - user. + + Revokes a role from a specified project + user. + &commonFaults; &getFaults; @@ -1474,8 +1578,10 @@ - Lists roles for a project - group. + + Lists roles for a specified project + group. + @@ -1494,8 +1600,10 @@ - Grants a role to a project - group. + + Grants a specified role to a specified project + group. + &commonFaults; &getFaults; @@ -1503,8 +1611,10 @@ - Validates that a project group has - a role. + + Validates that a specified project group has + a specified role. + &commonFaults; &getFaults; @@ -1512,8 +1622,10 @@ - Revokes a role from a project - group. + + Revokes a specified role from a specified project + group. + &commonFaults; &getFaults; @@ -1522,7 +1634,9 @@ - Lists users. + + Lists users. + @@ -1546,7 +1660,9 @@ - Creates a user. + + Creates a user. + @@ -1577,8 +1693,10 @@ - Shows details for a specified - user. + + Shows details for a specified + user. + @@ -1596,11 +1714,15 @@ - Updates the password for or enables - or disables a specified user. - This operation might return the HTTP 501 Not - Implemented code if the back-end driver - does not allow this functionality. + + Updates the password for or enables + or disables a specified user. + + + If the back-end driver does not allow this functionality, this + call might return the HTTP Not Implemented (501) + status code. + @@ -1629,7 +1751,9 @@ - Deletes a specified user. + + Deletes a specified user. + &commonFaults; &getFaults; @@ -1637,8 +1761,9 @@ - List projects for a specified - user. + + List projects for a specified user. + @@ -1657,8 +1782,9 @@ - Lists groups for a specified - user. + + Lists groups for a specified user. + @@ -1678,7 +1804,9 @@ - Lists groups. + + Lists groups. + &domain_idQueryParam; @@ -1704,7 +1832,9 @@ - Creates a group. + + Creates a group. + @@ -1735,8 +1865,10 @@ - Shows details for a specified - group. + + Shows details for a specified + group. + @@ -1756,11 +1888,13 @@ - Updates a specified group. - Use this operation to update the name or description - of a group. This operation might return the HTTP - 501 Not Implemented code if the - back-end driver does not allow this functionality. + + Updates a specified group. + + + If the back-end driver does not allow this functionality, this + operation might return the HTTP Not Implemented + (501) status code. @@ -1791,7 +1925,9 @@ - Deletes a specified group. + + Deletes a specified group. + &commonFaults; &getFaults; @@ -1799,8 +1935,10 @@ - Assigns a specified user to a specified - group. + + Assigns a specified user to a specified + group. + &commonFaults; &getFaults; @@ -1808,7 +1946,9 @@ - Removes a user from a group. + + Removes a specified user from a specified group. + &commonFaults; &getFaults; @@ -1816,8 +1956,10 @@ - Validates that a user is in a - group. + + Validates that a specified user is in a specified + group. + &commonFaults; &getFaults; @@ -1825,8 +1967,10 @@ - Lists the users in a specified - group. + + Lists the users in a specified + group. + @@ -1853,7 +1997,9 @@ - Lists credentials. + + Lists credentials. + @@ -1879,7 +2025,9 @@ - Creates a credential. + + Creates a credential. + The following example shows how to create an EC2-style credential. The credential blob is a string that contains a @@ -1918,8 +2066,9 @@ - Shows details for a specified - credential. + + Shows details for a specified credential. + @@ -1938,8 +2087,9 @@ - Updates a specified - credential. + + Updates a specified credential. + @@ -1969,8 +2119,9 @@ - Deletes a specified - credential. + + Deletes a specified credential. + &commonFaults; &getFaults; @@ -1979,7 +2130,9 @@ - Lists roles. + + Lists roles. + @@ -2002,7 +2155,9 @@ - Creates a role. + + Creates a role. + @@ -2032,8 +2187,10 @@ - Shows details for a specified - role. + + Shows details for a specified + role. + @@ -2051,7 +2208,9 @@ - Updates a specified role. + + Updates a specified role. + @@ -2080,7 +2239,9 @@ - Deletes a specified role. + + Deletes a specified role. + &commonFaults; &getFaults; @@ -2088,40 +2249,57 @@ - Lists role assignments. - 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. 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. - 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. + + Lists role assignments. + + + Because the role assignments list can be long, use the query + parameters to filter the list. + + + Some typical examples are: + + + GET /role_assignments?user.id={user_id} lists + role assignments for the specified user. + + + GET + /role_assignments?scope.project.id={project_id} + lists 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. 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. + + + For example, to determine what a user can actually do, issue + the GET + /role_assignments?user.id={user_id}&effective + request. + + + To return the equivalent set of role assignments that would be + included in the token response of a project-scoped token, + issue the GET /role_assignments?user.id={user_id}&s + cope.project.id={project_id}&effective request. + + + In the response, the links entity 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. + @@ -2160,7 +2338,9 @@ - Lists policies. + + Lists policies. + @@ -2186,7 +2366,9 @@ - Creates a policy. + + Creates a policy. + @@ -2219,8 +2401,10 @@ - Shows details for a specified - policy. + + Shows details for a specified + policy. + @@ -2240,7 +2424,9 @@ - Updates a specified policy. + + Updates a specified policy. + @@ -2272,8 +2458,212 @@ - Deletes a specified policy. + + Deletes a specified policy. + &commonFaults; &getFaults; + + + + + Creates a region. + + + If you try to add a region with a parent region ID that does + not exist, this call returns the HTTP Not Found + (404) status code. + + + If you try to add a region with a parent region ID that would + form a circular relationship, this call returns the HTTP + Conflict (409) status code. + + + + + + + + + + ®ionObjectRequestParam; + ®ion_descriptionRequestParam; + &parent_region_idRequestParam; + + + + + + + + + ®ionObjectRequestParam; &RegionsResponseParams; + &commonFaults; &getFaults; + + + + Creates a region with a user-defined region ID. + + + The user-defined region ID must be unique to the OpenStack + deployment. If not, this call returns the HTTP Conflict + (409) status code. You must URL-encode the user-defined + region ID if it contains characters that are not allowed in an + URI. + + + If you try to add a region with a parent region ID that does + not exist, this call returns the HTTP Not Found + (404) status code. + + + If you try to add a region with a parent region ID that would + form a circular relationship, this call returns the HTTP + Conflict (409) status code. + + + + + + + + + + ®ionObjectRequestParam; + ®ion_descriptionRequestParam; + &parent_region_idRequestParam; + + + + + + + + + ®ionObjectRequestParam; &RegionsResponseParams; + &commonFaults; &getFaults; + + + + Lists regions. + + + + + &parent_region_idQueryParam; + + + + + + + + + + ®ionsObjectRequestParam; + &RegionsResponseParams; + &RegionLinksResponseParam; + + &commonFaults; &getFaults; + + + + Shows details for a specified region, by ID. + + + + + + + + + ®ionObjectRequestParam; + &RegionsResponseParams; + &commonFaults; &getFaults; + + + + Updates a specified region. + + + If you try to update a region with a parent region ID that + does not exist, this call returns the HTTP Not Found + (404) status code. + + + + + + + + + + ®ionObjectRequestParam; + ®ion_descriptionRequestParam; + &parent_region_idRequestParam; + + + + + + + + + + ®ionObjectRequestParam; &RegionsResponseParams; + + &commonFaults; &getFaults; + + + + Deletes a specified region. + + + + If you try to delete a region that has child regions, this + call returns the HTTP Conflict (409) status + code. + + + + &commonFaults; &getFaults; +