Merge "Updated scope parameter description in v3 API-ref"

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