Update documentation to reflect system-scope

This patch takes a first pass at including system-scope token in
the authentication/authorization documentation.

bp system-scope

Change-Id: I3f334bfe8286d3863610582e4c3d5942b755987d

api-ref/source/v3/authenticate-v3.inc

@@ -4,25 +4,20 @@
  Authentication and token management
 =====================================
 
-In exchange for a set of authentication credentials, the Identity
-service generates tokens. A token represents the authenticated
-identity of a user and, optionally, grants authorization on a
-specific project or domain.
+The Identity service generates tokens in exchange for authentication
+credentials. A token represents the authenticated identity of a user and,
+optionally, grants authorization on a specific project, domain, or the
+deployment system.
 
 The body of an authentication request must include a payload that
 specifies the authentication method, which is ``password`` or
 ``token``, the credentials, and, optionally, the authorization
-scope. You can scope a token to a project or domain, or the token
-can be unscoped. You cannot scope a token to both a project and
-domain.
+scope. You can scope a token to a project, domain, the deployment system, or
+the token can be unscoped. You cannot scope a token to multiple scope targets.
 
 Tokens have IDs, which the Identity API returns in the
 ``X-Subject-Token`` response header.
 
-Also, validates an authentication token and lists the domains,
-projects, roles, and endpoints to which the token gives access.
-Forces the immediate revocation of a token.
-
 After you obtain an authentication token, you can:
 
 - Make REST API requests to other OpenStack services. You supply the
@@ -48,8 +43,12 @@ is processed, it will have an additional field in the token
 ``{is_admin_project: True}``. The additional field can be used when
 writing policy rules that evaluate access control to APIs.
 
-The Identity API treats expired tokens as no longer valid tokens.
-The deployment determines how long expired tokens are stored.
+Alternatively, in v3.10 the Identity API service introduced the concept of
+system role assignments and system-scoped tokens. APIs that affect the
+deployment system require system-scoped tokens.
+
+The Identity API considers expired tokens as invalid, which is determined by
+the deployment's configuration.
 
 These authentication errors can occur:
 
@@ -231,6 +230,7 @@ Parameters
    - token: token
    - expires_at: expires_at
    - project: project
+   - system: system
    - issued_at: issued_at
    - catalog: catalog
    - user: user

api-ref/source/v3/parameters.yaml

@@ -1469,9 +1469,9 @@ roles:
   type: array
 scope_string:
   description: |
-    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
+    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
@@ -1572,6 +1572,12 @@ signed:
   in: body
   required: true
   type: string
+system:
+  description: |
+    A ``system`` object.
+  in: body
+  required: false
+  type: object
 system_roles_response_body:
   description: |
     A list of ``role`` objects containing ``domain_id``, ``id``, ``links``,
@@ -1579,6 +1585,14 @@ system_roles_response_body:
   in: body
   required: true
   type: array
+system_scope_string:
+  description: |
+    Authorization scope specific to the deployment system (Since v3.10).
+    Specifying a project or domain scope in addition to system scope results
+    in an HTTP ``400 Bad Request``.
+  in: body
+  required: false
+  type: string
 token:
   description: |
     A ``token`` object.

api-ref/source/v3/samples/admin/auth-password-system-scoped-request-with-domain.json

@@ -0,0 +1,23 @@
+{
+    "auth": {
+        "identity": {
+            "methods": [
+                "password"
+            ],
+            "password": {
+                "user": {
+                    "name": "admin",
+                    "domain": {
+                        "name": "Default"
+                    },
+                    "password": "devstacker"
+                }
+            }
+        },
+        "scope": {
+            "system": {
+                "all": true
+            }
+        }
+    }
+}

doc/source/admin/identity-tokens.rst

@@ -11,10 +11,12 @@ deployment characteristics.
 Authorization scopes
 --------------------
 
-Tokens can express your authorization in different scopes. You likely have
-different sets of roles, in different projects, and in different domains.
-While tokens always express your identity, they may only ever express one set
-of roles in one authorization scope at a time.
+Tokens are used to relay information about your user's role assignments. It's
+not uncommon for a user to have multiple role assignments, sometimes spanning
+projects, domains, or the entire system. These are referred to as authorization
+scopes, where a token has a single scope of operation. For example, a token
+scoped to a project can't be reused to do something else in a different
+project.
 
 Each level of authorization scope is useful for certain types of operations in
 certain OpenStack services, and are not interchangeable.
@@ -39,9 +41,9 @@ The following conditions must be met to receive an unscoped token:
 Project-scoped tokens
 ~~~~~~~~~~~~~~~~~~~~~
 
-Project-scoped tokens are the bread and butter of OpenStack. They express your
-authorization to operate in a specific tenancy of the cloud and are useful to
-authenticate yourself when working with most other services.
+Project-scoped tokens express your authorization to operate in a specific
+tenancy of the cloud and are useful to authenticate yourself when working with
+most other services.
 
 They contain a service catalog, a set of roles, and details of the project upon
 which you have authorization.
@@ -49,11 +51,11 @@ which you have authorization.
 Domain-scoped tokens
 ~~~~~~~~~~~~~~~~~~~~
 
-Domain-scoped tokens also have limited use cases in OpenStack. They express
-your authorization to operate a domain-level, above that of the user and
-projects contained therein (typically as a domain-level administrator).
-Depending on Keystone's configuration, they are useful for working with a
-single domain in Keystone.
+Domain-scoped tokens have limited use cases in OpenStack. They express your
+authorization to operate a domain-level, above that of the user and projects
+contained therein (typically as a domain-level administrator).  Depending on
+Keystone's configuration, they are useful for working with a single domain in
+Keystone.
 
 They contain a limited service catalog (only those services which do not
 explicitly require per-project endpoints), a set of roles, and details of the
@@ -63,6 +65,16 @@ They can also be used to work with domain-level concerns in other services,
 such as to configure domain-wide quotas that apply to all users or projects in
 a specific domain.
 
+System-scoped tokens
+~~~~~~~~~~~~~~~~~~~~
+
+There are APIs across OpenStack that fit nicely within the concept of a project
+or domain, but there are also APIs that affect the entire deployment system
+(e.g. modifying endpoints, service management, or listing information about
+hypervisors). These operations require the use of a system-scoped token, which
+represents the role assignments a user has to operate on the deployment as a
+whole.
+
 Token providers
 ---------------
 

doc/source/admin/token-support-matrix.ini

@@ -68,6 +68,15 @@ cli=openstack --os-username=<username> --os-user-domain-name=<domain>
 driver-impl-uuid=complete
 driver-impl-fernet=complete
 
+[operation.create_system_token]
+title=Create system-scoped token
+status=mandatory
+notes=All token providers must be capable of issuing system-scoped tokens.
+cli=openstack --os-username=<username> --os-user-domain-name=<domain>
+  --os-system token issue
+driver-impl-uuid=complete
+driver-impl-fernet=complete
+
 [operation.create_project_scoped_token]
 title=Create project-scoped token
 status=mandatory

doc/source/getting-started/architecture.rst

@@ -481,14 +481,15 @@ What is Scope?
 
 Scope is an overloaded term.
 
-In reference to authenticating, as seen above, scope refers to the portion
-of the POST data that dictates what ``Resource`` (project or domain) the user
-wants to access.
+In reference to authenticating, as seen above, scope refers to the portion of
+the POST data that dictates what ``Resource`` (project, domain, or system) the
+user wants to access.
 
 In reference to tokens, scope refers to the effectiveness of a token,
 i.e.: a `project-scoped` token is only useful on the project it was initially
 granted for. A `domain-scoped` token may be used to perform domain-related
-function.
+function. A `system-scoped` token is only useful for interacting with APIs that
+affect the entire deployment.
 
 In reference to users, groups, and projects, scope often refers to the domain
 that the entity is owned by. i.e.: a user in domain X is scoped to domain X.