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
This commit is contained in:
Lance Bragstad 2017-12-26 17:26:27 +00:00
parent c2b93dcb36
commit f5322a850e
6 changed files with 91 additions and 32 deletions

View File

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

View File

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

View File

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

View File

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

View File

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

View File

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