diff --git a/doc/admin-guide-cloud/source/keystone_tokens.rst b/doc/admin-guide-cloud/source/keystone_tokens.rst index 24edf38a4c..1a538c8bac 100644 --- a/doc/admin-guide-cloud/source/keystone_tokens.rst +++ b/doc/admin-guide-cloud/source/keystone_tokens.rst @@ -8,6 +8,61 @@ authorization scopes and sources of identity. There are also several different "token providers", each with their own user experience, performance, and 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. + +Each level of authorization scope is useful for certain types of operations in +certain OpenStack services, and are not interchangeable. + +Unscoped tokens +~~~~~~~~~~~~~~~ + +An unscoped token contains neither a service catalog, any roles, a project +scope, nor a domain scope. Their primary use case is simply to prove your +identity to keystone at a later time (usually to generate scoped tokens), +without repeatedly presenting your original credentials. + +The following conditions must be met to receive an unscoped token: + +* You must not specify an authorization scope in your authentication request + (for example, on the command line with arguments such as + ``--os-project-name`` or ``--os-domain-id``), + +* Your identity must not have a "default project" associated with it that you + also have role assignments, and thus authorization, upon. + +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. + +They contain a service catalog, a set of roles, and details of the project upon +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. + +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 +project upon which you have authorization. + +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. + Token providers ---------------