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

@@ -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
 =======================================
 

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

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"
+    }
+}

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': {