From 8da2c6d5cc33ee84d1e241c120c1e462016a7c1c Mon Sep 17 00:00:00 2001 From: SamriddhiJain Date: Sun, 26 Mar 2017 23:49:06 +0530 Subject: [PATCH] Updated scope parameter description in v3 API-ref The description of scope parameter in the API docs is inconsistent for scoped and explicit unscoped authorization. It doesn't explain clearly when the parameter should be set to keyword 'unscoped' (explicit unscoped authorization) and when to include ID/name of the project/ domain (scoped authorization). This patch covers the required update for the scope parameter by introducing separate descriptions for the above mentioned cases. For explicit unscoped authorization, the keystone server specifies scope value as 'unscoped' whereas in some old versions of keystoneauth the value is {'unscoped': {}}. Added a comment to keystone/auth/schema.py to make sure the type of scope parameter is object and not string, so that it is consistent with older versions too. In v3 API docs the case for token authentication with explicit unscoped authorization is missing. Added documentation and request example for that case. Partial-Bug #1637682 Change-Id: I10d38e4cc59934c421443322b14f4f971acf3a29 --- api-ref/source/v3/authenticate-v3.inc | 48 ++++++++++++++++++- api-ref/source/v3/parameters.yaml | 35 ++++++++++---- .../auth-token-explicit-unscoped-request.json | 13 +++++ keystone/auth/schema.py | 6 +++ 4 files changed, 91 insertions(+), 11 deletions(-) create mode 100644 api-ref/source/v3/samples/admin/auth-token-explicit-unscoped-request.json diff --git a/api-ref/source/v3/authenticate-v3.inc b/api-ref/source/v3/authenticate-v3.inc index 479c6d59f4..d669a02e09 100644 --- a/api-ref/source/v3/authenticate-v3.inc +++ b/api-ref/source/v3/authenticate-v3.inc @@ -247,7 +247,7 @@ Request - name: user_name - auth: auth - user: user - - scope: scope_string + - scope: explicit_unscoped_string - password: password - id: user_id - identity: identity @@ -365,6 +365,52 @@ Response Parameters - X-Auth-Token: X-Auth-Token +Token authentication with explicit unscoped authorization +========================================================= + +.. rest_method:: POST /v3/auth/tokens + +Relationship: ``https://docs.openstack.org/api/openstack-identity/3/rel/auth_tokens`` + +Authenticates an identity and generates a token. +Uses the token authentication method with explicit unscoped authorization. + +In the request body, provide the token ID and the +``unscoped`` authorization scope. + +Normal response codes: 201 + +Error response codes: 413,415,405,404,403,401,400,503,409 + +Request +------- + +.. rest_parameters:: parameters.yaml + + - nocatalog: nocatalog + - methods: auth_methods_token + - auth: auth + - token: auth_token + - audit_ids: audit_ids + - scope: explicit_unscoped_string + - id: auth_token_id + - identity: identity + + +Request Example +--------------- + +.. literalinclude:: ./samples/admin/auth-token-explicit-unscoped-request.json + :language: javascript + +Response Parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - X-Subject-Token: X-Subject-Token + + Validate and show information for token ======================================= diff --git a/api-ref/source/v3/parameters.yaml b/api-ref/source/v3/parameters.yaml index df04436959..4fc10ec0cf 100644 --- a/api-ref/source/v3/parameters.yaml +++ b/api-ref/source/v3/parameters.yaml @@ -824,6 +824,21 @@ expires_at: in: body required: true type: string +explicit_unscoped_string: + description: | + The authorization scope (Since v3.4). Specify + ``unscoped`` to make an explicit unscoped token request, which + returns an unscoped response without any authorization. This + request behaves the same as a token request with no scope where + the user has no default project defined. If an explicit, + ``unscoped`` token request is not made and the role has a default + project, then the response will return a project-scoped token. + If a default project is not defined, a token is issued without an + explicit scope of authorization, which is the same as asking for + an explicit unscoped token. + in: body + required: false + type: string extras: description: | A set of metadata key and value pairs, if any. @@ -1326,16 +1341,16 @@ roles: type: array scope_string: description: | - The authorization scope. (Since v3.4) Specify - ``unscoped`` to make an explicit unscoped token request, which - returns an unscoped response without any authorization. This - request behaves the same as a token request with no scope where - the user has no default project defined. If you do not make an - explicit ``unscoped`` token request and your role has a default - project, the response might return a project- scoped token. If a - default project is not defined, a token is issued without an - explicit scope of authorization, which is the same as asking for - an explicit unscoped token. + The authorization scope, including either 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. in: body required: false type: string diff --git a/api-ref/source/v3/samples/admin/auth-token-explicit-unscoped-request.json b/api-ref/source/v3/samples/admin/auth-token-explicit-unscoped-request.json new file mode 100644 index 0000000000..e3523e4c77 --- /dev/null +++ b/api-ref/source/v3/samples/admin/auth-token-explicit-unscoped-request.json @@ -0,0 +1,13 @@ +{ + "auth": { + "identity": { + "methods": [ + "token" + ], + "token": { + "id": "'$OS_TOKEN'" + } + }, + "scope": "unscoped" + } +} diff --git a/keystone/auth/schema.py b/keystone/auth/schema.py index 985722c365..c09afe2863 100644 --- a/keystone/auth/schema.py +++ b/keystone/auth/schema.py @@ -53,6 +53,12 @@ token_issue = { 'required': ['methods', ], }, 'scope': { + # For explicit unscoped authentication the type should not be + # strictly string. Although keystone server specifies the value + # to be 'unscoped', old versions of keystoneauth might still be + # using `"scope": {'unscoped': {}}` instead of + # `"scope": "unscoped"` + # https://bugs.launchpad.net/keystoneauth/+bug/1637682/ 'type': ['object', 'string'], 'properties': { 'project': {