Clarify scope responses in authentication api ref

The documentation was a bit misleading because it listed projects,
domains, and the system as not being optional. This is confusing
because it's not possible to scope a token to more than one target.

This commit attempts to clarify those details.

Closes-Bug: 1774229
Change-Id: I27fb15e2b53529b91c0f2bd3a2744d60b54495c8
This commit is contained in:
Lance Bragstad 2018-06-04 20:49:14 +00:00
parent 90fa2757ca
commit 75da4da476
20 changed files with 759 additions and 38 deletions

View File

@ -180,11 +180,13 @@ Password authentication with scoped authorization
.. rest_method:: POST /v3/auth/tokens
Authenticates an identity and generates a token. Uses the password authentication method and scopes authorization to a project or domain.
Authenticates an identity and generates a token. Uses the password
authentication method and scopes authorization to a project, domain, or the
system.
The request body must include a payload that specifies the
``password`` authentication method, the credentials, and the
``project`` or ``domain`` authorization scope.
The request body must include a payload that specifies the ``password``
authentication method which includes the credentials in addition to a
``project``, ``domain``, or ``system`` authorization scope.
Relationship: ``https://docs.openstack.org/api/openstack-identity/3/rel/auth_tokens``
@ -206,10 +208,34 @@ Parameters
- identity: identity
- methods: auth_methods_passwd
Example
~~~~~~~
System-Scoped Example
~~~~~~~~~~~~~~~~~~~~~
.. literalinclude:: ./samples/admin/auth-password-project-scoped-request.json
.. literalinclude:: ./samples/auth/requests/system-password.json
:language: javascript
Domain-Scoped with Domain ID Example
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. literalinclude:: ./samples/auth/requests/domain-id-password.json
:language: javascript
Domain-Scoped with Domain Name Example
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. literalinclude:: ./samples/auth/requests/domain-name-password.json
:language: javascript
Project-Scoped with Project ID Example
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. literalinclude:: ./samples/auth/requests/project-id-password.json
:language: javascript
Project-Scoped with Project Name Example
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. literalinclude:: ./samples/auth/requests/project-name-password.json
:language: javascript
Response
@ -221,7 +247,6 @@ Parameters
.. rest_parameters:: parameters.yaml
- X-Subject-Token: X-Subject-Token
- domain: domain
- region_id: region_id_required
- methods: auth_methods_passwd
- roles: roles
@ -229,8 +254,9 @@ Parameters
- region: endpoint_region
- token: token
- expires_at: expires_at
- project: project
- system: system
- system: system_scope_response_body_optional
- domain: domain_scope_response_body_optional
- project: project_scope_response_body_optional
- issued_at: issued_at
- catalog: catalog
- user: user
@ -260,12 +286,23 @@ Status Codes
- 415
- 503
Example
~~~~~~~
System-Scoped Example
~~~~~~~~~~~~~~~~~~~~~
.. literalinclude:: ./samples/admin/auth-password-project-scoped-response.json
.. literalinclude:: ./samples/auth/responses/system-scoped-password.json
:language: javascript
Domain-Scoped Example
~~~~~~~~~~~~~~~~~~~~~
.. literalinclude:: ./samples/auth/responses/domain-scoped-password.json
:language: javascript
Project-Scoped Example
~~~~~~~~~~~~~~~~~~~~~~
.. literalinclude:: ./samples/auth/responses/project-scoped-password.json
:language: javascript
Password authentication with explicit unscoped authorization
============================================================
@ -422,10 +459,12 @@ Token authentication with scoped authorization
.. rest_method:: POST /v3/auth/tokens
Authenticates an identity and generates a token. Uses the token authentication method and scopes authorization to a project or domain.
Authenticates an identity and generates a token. Uses the token authentication
method and scopes authorization to a project, domain, or the system.
In the request body, provide the token ID and the ``project`` or
``domain`` authorization scope.
The request body must include a payload that specifies the ``token``
authentication method which includes the token in addition to a ``project``,
``domain``, or ``system`` authorization scope.
Relationship: ``https://docs.openstack.org/api/openstack-identity/3/rel/auth_tokens``
@ -446,10 +485,34 @@ Parameters
- id: auth_token_id
- identity: identity
Example
~~~~~~~
System-Scoped Example
~~~~~~~~~~~~~~~~~~~~~
.. literalinclude:: ./samples/admin/auth-token-scoped-request.json
.. literalinclude:: ./samples/auth/requests/system-token.json
:language: javascript
Domain-Scoped with Domain ID Example
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. literalinclude:: ./samples/auth/requests/domain-id-token.json
:language: javascript
Domain-Scoped with Domain Name Example
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. literalinclude:: ./samples/auth/requests/domain-name-token.json
:language: javascript
Project-Scoped with Project ID Example
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. literalinclude:: ./samples/auth/requests/project-id-token.json
:language: javascript
Project-Scoped with Project Name Example
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. literalinclude:: ./samples/auth/requests/project-name-token.json
:language: javascript
Response
@ -461,6 +524,25 @@ Parameters
.. rest_parameters:: parameters.yaml
- X-Subject-Token: X-Subject-Token
- region_id: region_id_required
- methods: auth_methods_passwd
- roles: roles
- url: endpoint_url
- region: endpoint_region
- token: token
- expires_at: expires_at
- system: system_scope_response_body_optional
- domain: domain_scope_response_body_optional
- project: project_scope_response_body_optional
- issued_at: issued_at
- catalog: catalog
- user: user
- audit_ids: audit_ids
- interface: endpoint_interface
- endpoints: endpoints
- type: endpoint_type
- id: user_id
- name: user_name
Status Codes
~~~~~~~~~~~~
@ -481,12 +563,23 @@ Status Codes
- 415
- 503
Example
~~~~~~~
System-Scoped Example
~~~~~~~~~~~~~~~~~~~~~
.. literalinclude:: ./samples/admin/auth-token-scoped-response.json
.. literalinclude:: ./samples/auth/responses/system-scoped-token.json
:language: javascript
Domain-Scoped Example
~~~~~~~~~~~~~~~~~~~~~
.. literalinclude:: ./samples/auth/responses/domain-scoped-token.json
:language: javascript
Project-Scoped Example
~~~~~~~~~~~~~~~~~~~~~~
.. literalinclude:: ./samples/auth/responses/project-scoped-token.json
:language: javascript
Token authentication with explicit unscoped authorization
=========================================================
@ -596,14 +689,15 @@ Parameters
.. rest_parameters:: parameters.yaml
- X-Subject-Token: X-Subject-Token
- domain: domain
- methods: auth_methods
- links: domain_link_response_body
- user: user
- token: token
- expires_at: expires_at
- project: project
- catalog: catalog
- catalog: catalog_response_body_optional
- system: system_scope_response_body_optional
- domain: domain_scope_response_body_optional
- project: project_scope_response_body_optional
- roles: roles
- audit_ids: audit_ids
- issued_at: issued_at
@ -627,12 +721,29 @@ Status Codes
- 413
- 503
Example
~~~~~~~
Unscoped Example
~~~~~~~~~~~~~~~~
.. literalinclude:: ./samples/admin/auth-token-unscoped-response.json
.. literalinclude:: ./samples/auth/responses/unscoped-password.json
:language: javascript
System-Scoped Example
~~~~~~~~~~~~~~~~~~~~~
.. literalinclude:: ./samples/auth/responses/system-scoped-password.json
:language: javascript
Domain-Scoped Example
~~~~~~~~~~~~~~~~~~~~~
.. literalinclude:: ./samples/auth/responses/domain-scoped-password.json
:language: javascript
Project-Scoped Example
~~~~~~~~~~~~~~~~~~~~~~
.. literalinclude:: ./samples/auth/responses/project-scoped-password.json
:language: javascript
Check token
===========

View File

@ -526,6 +526,12 @@ catalog:
in: body
required: true
type: array
catalog_response_body_optional:
description: |
A ``catalog`` object.
in: body
required: false
type: array
credential:
description: |
A ``credential`` object.
@ -767,6 +773,14 @@ domain_name_update_request_body:
in: body
required: false
type: string
domain_scope_response_body_optional:
description: |
A ``domain`` object including the ``id`` and ``name`` representing the
domain the token is scoped to. This is only included in tokens that are
scoped to a domain.
in: body
required: false
type: object
domain_url:
description: |
The LDAP URL.
@ -1369,6 +1383,14 @@ project_parent_id_response_body:
required: true
type: string
min_version: 3.4
project_scope_response_body_optional:
description: |
A ``project`` object including the ``id``, ``name`` and ``domain`` object
representing the project the token is scoped to. This is only included in
tokens that are scoped to a project.
in: body
required: false
type: object
project_tags_request_body:
description: |
A list of simple strings assigned to a project.
@ -1664,16 +1686,15 @@ roles:
type: array
scope_string:
description: |
The authorization scope, including the system (Since v3.10), a
project, or a domain (Since v3.4). If both a domain and a project
are specified, an HTTP ``400 Bad Request`` will be returned, as a
token cannot be simultaneously scoped to both a project
and a domain. An ID is sufficient to uniquely identify
a project but if a project is specified by name, then
the domain of the project must also be specified in order
to uniquely identify the project by name. A domain scope may be
specified by either the domain's ID or name with
equivalent results.
The authorization scope, including the system (Since v3.10), a project, or
a domain (Since v3.4). If multiple scopes are specified in the same request
(e.g. ``project`` and ``domain`` or ``domain`` and ``system``) an HTTP
``400 Bad Request`` will be returned, as a token cannot be simultaneously
scoped to multiple authorization targets. An ID is sufficient to uniquely
identify a project but if a project is specified by name, then the domain
of the project must also be specified in order to uniquely identify the
project by name. A domain scope may be specified by either the domain's ID
or name with equivalent results.
in: body
required: false
type: string
@ -1780,6 +1801,15 @@ system_roles_response_body:
in: body
required: true
type: array
system_scope_response_body_optional:
description: |
A ``system`` object containing information about which parts of the system
the token is scoped to. If the token is scoped to the entire deployment
system, the ``system`` object will consist of ``{"all": true}``. This is
only included in tokens that are scoped to the system.
in: body
required: false
type: object
system_scope_string:
description: |
Authorization scope specific to the deployment system (Since v3.10).

View File

@ -0,0 +1,20 @@
{
"auth": {
"identity": {
"methods": [
"password"
],
"password": {
"user": {
"id": "ee4dfb6e5540447cb3741905149d9b6e",
"password": "devstacker"
}
}
},
"scope": {
"domain": {
"id": "default"
}
}
}
}

View File

@ -0,0 +1,17 @@
{
"auth": {
"identity": {
"methods": [
"token"
],
"token": {
"id": "'$OS_TOKEN'"
}
},
"scope": {
"domain": {
"id": "default"
}
}
}
}

View File

@ -0,0 +1,20 @@
{
"auth": {
"identity": {
"methods": [
"password"
],
"password": {
"user": {
"id": "ee4dfb6e5540447cb3741905149d9b6e",
"password": "devstacker"
}
}
},
"scope": {
"domain": {
"name": "Default"
}
}
}
}

View File

@ -0,0 +1,17 @@
{
"auth": {
"identity": {
"methods": [
"token"
],
"token": {
"id": "'$OS_TOKEN'"
}
},
"scope": {
"domain": {
"name": "Default"
}
}
}
}

View File

@ -0,0 +1,17 @@
{
"auth": {
"identity": {
"methods": [
"token"
],
"token": {
"id": "'$OS_TOKEN'"
}
},
"scope": {
"project": {
"id": "a6944d763bf64ee6a275f1263fae0352"
}
}
}
}

View File

@ -0,0 +1,23 @@
{
"auth": {
"identity": {
"methods": [
"password"
],
"password": {
"user": {
"id": "ee4dfb6e5540447cb3741905149d9b6e",
"password": "devstacker"
}
}
},
"scope": {
"project": {
"domain": {
"id": "default"
},
"name": "admin"
}
}
}
}

View File

@ -0,0 +1,20 @@
{
"auth": {
"identity": {
"methods": [
"token"
],
"token": {
"id": "'$OS_TOKEN'"
}
},
"scope": {
"project": {
"domain": {
"id": "default"
},
"name": "admin"
}
}
}
}

View File

@ -0,0 +1,20 @@
{
"auth": {
"identity": {
"methods": [
"password"
],
"password": {
"user": {
"id": "ee4dfb6e5540447cb3741905149d9b6e",
"password": "devstacker"
}
}
},
"scope": {
"system": {
"all": true
}
}
}
}

View File

@ -0,0 +1,17 @@
{
"auth": {
"identity": {
"methods": [
"token"
],
"token": {
"id": "'$OS_TOKEN'"
}
},
"scope": {
"system": {
"all": true
}
}
}
}

View File

@ -0,0 +1,61 @@
{
"token": {
"audit_ids": [
"3T2dc1CGQxyJsHdDu1xkcw"
],
"catalog": [
{
"endpoints": [
{
"id": "068d1b359ee84b438266cb736d81de97",
"interface": "public",
"region": "RegionOne",
"region_id": "RegionOne",
"url": "http://example.com/identity"
},
{
"id": "8bfc846841ab441ca38471be6d164ced",
"interface": "admin",
"region": "RegionOne",
"region_id": "RegionOne",
"url": "http://example.com/identity"
},
{
"id": "beb6d358c3654b4bada04d4663b640b9",
"interface": "internal",
"region": "RegionOne",
"region_id": "RegionOne",
"url": "http://example.com/identity"
}
],
"type": "identity",
"id": "050726f278654128aba89757ae25950c",
"name": "keystone"
}
],
"domain": {
"id": "default",
"name": "Default"
},
"expires_at": "2015-11-07T02:58:43.578887Z",
"issued_at": "2015-11-07T01:58:43.578929Z",
"methods": [
"password"
],
"roles": [
{
"id": "51cc68287d524c759f47c811e6463340",
"name": "admin"
}
],
"user": {
"domain": {
"id": "default",
"name": "Default"
},
"id": "ee4dfb6e5540447cb3741905149d9b6e",
"name": "admin",
"password_expires_at": "2016-11-06T15:32:17.000000"
}
}
}

View File

@ -0,0 +1,63 @@
{
"token": {
"audit_ids": [
"3T2dc1CGQxyJsHdDu1xkcw",
"oppr9r6pQo6mWb5Ji4zgwg"
],
"catalog": [
{
"endpoints": [
{
"id": "068d1b359ee84b438266cb736d81de97",
"interface": "public",
"region": "RegionOne",
"region_id": "RegionOne",
"url": "http://example.com/identity"
},
{
"id": "8bfc846841ab441ca38471be6d164ced",
"interface": "admin",
"region": "RegionOne",
"region_id": "RegionOne",
"url": "http://example.com/identity"
},
{
"id": "beb6d358c3654b4bada04d4663b640b9",
"interface": "internal",
"region": "RegionOne",
"region_id": "RegionOne",
"url": "http://example.com/identity"
}
],
"type": "identity",
"id": "050726f278654128aba89757ae25950c",
"name": "keystone"
}
],
"domain": {
"id": "default",
"name": "Default"
},
"expires_at": "2015-11-07T02:58:43.578887Z",
"issued_at": "2015-11-07T01:58:43.578929Z",
"methods": [
"token",
"password"
],
"roles": [
{
"id": "51cc68287d524c759f47c811e6463340",
"name": "admin"
}
],
"user": {
"domain": {
"id": "default",
"name": "Default"
},
"id": "ee4dfb6e5540447cb3741905149d9b6e",
"name": "admin",
"password_expires_at": "2016-11-06T15:32:17.000000"
}
}
}

View File

@ -0,0 +1,66 @@
{
"token": {
"audit_ids": [
"3T2dc1CGQxyJsHdDu1xkcw"
],
"catalog": [
{
"endpoints": [
{
"id": "068d1b359ee84b438266cb736d81de97",
"interface": "public",
"region": "RegionOne",
"region_id": "RegionOne",
"url": "http://example.com/identity"
},
{
"id": "8bfc846841ab441ca38471be6d164ced",
"interface": "admin",
"region": "RegionOne",
"region_id": "RegionOne",
"url": "http://example.com/identity"
},
{
"id": "beb6d358c3654b4bada04d4663b640b9",
"interface": "internal",
"region": "RegionOne",
"region_id": "RegionOne",
"url": "http://example.com/identity"
}
],
"type": "identity",
"id": "050726f278654128aba89757ae25950c",
"name": "keystone"
}
],
"expires_at": "2015-11-07T02:58:43.578887Z",
"is_domain": false,
"issued_at": "2015-11-07T01:58:43.578929Z",
"methods": [
"password"
],
"project": {
"domain": {
"id": "default",
"name": "Default"
},
"id": "a6944d763bf64ee6a275f1263fae0352",
"name": "admin"
},
"roles": [
{
"id": "51cc68287d524c759f47c811e6463340",
"name": "admin"
}
],
"user": {
"domain": {
"id": "default",
"name": "Default"
},
"id": "ee4dfb6e5540447cb3741905149d9b6e",
"name": "admin",
"password_expires_at": "2016-11-06T15:32:17.000000"
}
}
}

View File

@ -0,0 +1,68 @@
{
"token": {
"audit_ids": [
"3T2dc1CGQxyJsHdDu1xkcw",
"oppr9r6pQo6mWb5Ji4zgwg"
],
"catalog": [
{
"endpoints": [
{
"id": "068d1b359ee84b438266cb736d81de97",
"interface": "public",
"region": "RegionOne",
"region_id": "RegionOne",
"url": "http://example.com/identity"
},
{
"id": "8bfc846841ab441ca38471be6d164ced",
"interface": "admin",
"region": "RegionOne",
"region_id": "RegionOne",
"url": "http://example.com/identity"
},
{
"id": "beb6d358c3654b4bada04d4663b640b9",
"interface": "internal",
"region": "RegionOne",
"region_id": "RegionOne",
"url": "http://example.com/identity"
}
],
"type": "identity",
"id": "050726f278654128aba89757ae25950c",
"name": "keystone"
}
],
"expires_at": "2015-11-07T02:58:43.578887Z",
"is_domain": false,
"issued_at": "2015-11-07T01:58:43.578929Z",
"methods": [
"token",
"password"
],
"project": {
"domain": {
"id": "default",
"name": "Default"
},
"id": "a6944d763bf64ee6a275f1263fae0352",
"name": "admin"
},
"roles": [
{
"id": "51cc68287d524c759f47c811e6463340",
"name": "admin"
}
],
"user": {
"domain": {
"id": "default",
"name": "Default"
},
"id": "ee4dfb6e5540447cb3741905149d9b6e",
"name": "admin",
"password_expires_at": "2016-11-06T15:32:17.000000"
}
}
}

View File

@ -0,0 +1,61 @@
{
"token": {
"audit_ids": [
"3T2dc1CGQxyJsHdDu1xkcw"
],
"catalog": [
{
"endpoints": [
{
"id": "068d1b359ee84b438266cb736d81de97",
"interface": "public",
"region": "RegionOne",
"region_id": "RegionOne",
"url": "http://example.com/identity"
},
{
"id": "8bfc846841ab441ca38471be6d164ced",
"interface": "admin",
"region": "RegionOne",
"region_id": "RegionOne",
"url": "http://example.com/identity"
},
{
"id": "beb6d358c3654b4bada04d4663b640b9",
"interface": "internal",
"region": "RegionOne",
"region_id": "RegionOne",
"url": "http://example.com/identity"
}
],
"type": "identity",
"id": "050726f278654128aba89757ae25950c",
"name": "keystone"
}
],
"expires_at": "2015-11-07T02:58:43.578887Z",
"issued_at": "2015-11-07T01:58:43.578929Z",
"methods": [
"password"
],
"roles": [
{
"id": "51cc68287d524c759f47c811e6463340",
"name": "admin"
}
],
"system": {
"all": true
},
"user": {
"domain": {
"id": "default",
"name": "Default"
},
"id": "ee4dfb6e5540447cb3741905149d9b6e",
"name": "admin",
"password_expires_at": "2016-11-06T15:32:17.000000"
}
}
}

View File

@ -0,0 +1,63 @@
{
"token": {
"audit_ids": [
"3T2dc1CGQxyJsHdDu1xkcw",
"oppr9r6pQo6mWb5Ji4zgwg"
],
"catalog": [
{
"endpoints": [
{
"id": "068d1b359ee84b438266cb736d81de97",
"interface": "public",
"region": "RegionOne",
"region_id": "RegionOne",
"url": "http://example.com/identity"
},
{
"id": "8bfc846841ab441ca38471be6d164ced",
"interface": "admin",
"region": "RegionOne",
"region_id": "RegionOne",
"url": "http://example.com/identity"
},
{
"id": "beb6d358c3654b4bada04d4663b640b9",
"interface": "internal",
"region": "RegionOne",
"region_id": "RegionOne",
"url": "http://example.com/identity"
}
],
"type": "identity",
"id": "050726f278654128aba89757ae25950c",
"name": "keystone"
}
],
"expires_at": "2015-11-07T02:58:43.578887Z",
"issued_at": "2015-11-07T01:58:43.578929Z",
"methods": [
"token",
"password"
],
"roles": [
{
"id": "51cc68287d524c759f47c811e6463340",
"name": "admin"
}
],
"system": {
"all": true
},
"user": {
"domain": {
"id": "default",
"name": "Default"
},
"id": "ee4dfb6e5540447cb3741905149d9b6e",
"name": "admin",
"password_expires_at": "2016-11-06T15:32:17.000000"
}
}
}

View File

@ -0,0 +1,21 @@
{
"token": {
"audit_ids": [
"mAjXQhiYRyKwkB4qygdLVg"
],
"expires_at": "2015-11-05T22:00:11.000000Z",
"issued_at": "2015-11-05T21:00:33.819948Z",
"methods": [
"password"
],
"user": {
"domain": {
"id": "default",
"name": "Default"
},
"id": "10a2e6e717a245d9acad3e5f97aeca3d",
"name": "admin",
"password_expires_at": null
}
}
}

View File

@ -0,0 +1,6 @@
---
fixes:
- |
[`bug 1774229 <https://bugs.launchpad.net/keystone/+bug/1774229>`_]
The API reference for token management now includes more specific examples
for different token scopes.