Merge "Add scope documentation for service developers"
This commit is contained in:
commit
5ff37f1028
|
@ -29,14 +29,57 @@ of v3 features they need to know about how it works.
|
|||
Glossary
|
||||
========
|
||||
|
||||
Authentication
|
||||
The process of determining if a user is who they claim to be (authN).
|
||||
|
||||
Authorization
|
||||
The process of determining if a user can do what they are requesting
|
||||
(authZ).
|
||||
|
||||
Scope
|
||||
A specific operating context. This is commonly used when describing the
|
||||
authorization a user may have. For example, a user with a role assignment
|
||||
on a project can get a token scoped to that project, ultimately operating
|
||||
within that project's scope.
|
||||
|
||||
System
|
||||
An assignment target that refers to a collection of API services as a
|
||||
whole. Users and groups can be granted authorization on the *deployment
|
||||
system*.
|
||||
|
||||
Service
|
||||
OpenStack services like identity, compute, image, etc.
|
||||
|
||||
Domain
|
||||
A container for users, projects, and groups. A domain is also an assignment
|
||||
target for users and groups. It's possible for users and groups to have
|
||||
authorization on domains outside of the domain associated to their
|
||||
reference.
|
||||
|
||||
Project
|
||||
A project provides namespace and resource isolation for groups of OpenStack
|
||||
entities. Users must be assigned a role on a project in order to interact
|
||||
with it. Prior to the introduction of the v3 API, projects were referred to
|
||||
as tenants in the v2.0 API.
|
||||
A container and a namespace for resources isolated within OpenStack. A
|
||||
user, or group of users, must have a role assignment on a project in order
|
||||
to interact with it.
|
||||
|
||||
Token
|
||||
A self-service resource that proves a user's identity and authentication.
|
||||
It can optionally carry a user's authorization, allowing them to interact
|
||||
with OpenStack services.
|
||||
|
||||
Role
|
||||
A string that represents one or more permissions or capabilities.
|
||||
|
||||
Role Assignment
|
||||
An association between an actor and a target that results in authorization.
|
||||
Actors can be users or groups of users. Targets can be projects, domains,
|
||||
or the deployment system itself.
|
||||
|
||||
User
|
||||
A entity modeling an end-user of the system.
|
||||
|
||||
Group
|
||||
A container for users. Users indirectly inherit any authorization the group
|
||||
has on projects, domains, or the system.
|
||||
|
||||
|
||||
Domains
|
||||
|
@ -82,18 +125,95 @@ experiment with domains, while isolating them from the v2.0 API.
|
|||
As far as the v3 API is concerned, the *default* domain is simply a domain and
|
||||
doesn't carry any special connotation like it did with v2.0.
|
||||
|
||||
Token differences
|
||||
=================
|
||||
Authorization Scopes
|
||||
====================
|
||||
|
||||
Domain-scoped tokens
|
||||
--------------------
|
||||
End users use the Identity API as a way to express their authoritative power to
|
||||
other OpenStack services. This is done using tokens, which can be scoped to one
|
||||
of several targets depending on the users' role assignments. This is typically
|
||||
referred to as a token's *scope*. This happens when a user presents
|
||||
credentials, in some form or fashion, to keystone in addition to a desired
|
||||
scope. If keystone can prove the user is who they say they are (authN), it will
|
||||
then validate that the user has access to the scope they are requesting
|
||||
(authZ). If successful, the token response will contain a token ID and data
|
||||
about the transaction, such as the scope target and role assignments. Users can
|
||||
use this token ID in requests to other OpenStack services, which consume the
|
||||
authorization information associated to that token to make decisions about what
|
||||
that user can or cannot do within that service.
|
||||
|
||||
Domain-scoped tokens are scoped to a domain rather than a project. These are
|
||||
useful for operating against keystone but are generally useless in other
|
||||
services that don't have use cases for domain-level operations. Unless a
|
||||
service has a real case for handling such authorization, they don't need to
|
||||
concern themselves with domain-scoped tokens.
|
||||
This section describes the various scopes available, and what they mean for
|
||||
services consuming tokens.
|
||||
|
||||
System Scope
|
||||
------------
|
||||
|
||||
A *system-scoped* token implies the user has authorization to act on the
|
||||
*deployment system*. These tokens are useful for interacting with resources
|
||||
that affect the deployment as a whole, or exposes resources that may otherwise
|
||||
violate project or domain isolation.
|
||||
|
||||
Good examples of system-scoped resources include:
|
||||
|
||||
* Services: Service entities within keystone that describe the services
|
||||
deployed in a cloud.
|
||||
* Endpoints: Endpoints that tell users where to find services deployed in a
|
||||
cloud.
|
||||
* Hypervisors: Hosts for servers that belong to various projects.
|
||||
|
||||
Domain Scope
|
||||
------------
|
||||
|
||||
A *domain-scoped* token carries a user's authorization on a specific domain.
|
||||
Ideally, these tokens would be useful for listing resources aggregated across
|
||||
all projects with that domain. They can also be useful for creating entities
|
||||
that must belong to a domain. Users and groups are good examples of this. The
|
||||
following is an example of how a domain-scoped token could be used against a
|
||||
service.
|
||||
|
||||
Assume a domain exists called `Foo`. and it contains projects call `bar` and
|
||||
`baz`. Let's also assume both projects contain compute servers running a
|
||||
workload. If Alice is a domain administrator for `Foo`, she should be able to
|
||||
pass her domain-scoped token to nova and ask for a list of instances. If nova
|
||||
supports domain-scoped token, the response would contain all instances in
|
||||
projects `bar` and `baz`.
|
||||
|
||||
Another example of using a domain-scoped token would be if Alice wanted to
|
||||
create a new project in domain `Foo`. When Alice sends a request for keystone
|
||||
to create a project, keystone should ensure the new project is created within
|
||||
the `Foo` domain, since that's the authorization associated to Alice's token.
|
||||
|
||||
.. WARNING::
|
||||
|
||||
This behavior isn't completely implemented, and is still in progress. This
|
||||
example describes the ideal behavior, specifically for developers looking
|
||||
to implement scope into their APIs.
|
||||
|
||||
Project Scope
|
||||
-------------
|
||||
|
||||
A *project-scoped* token carries the role assignments a user has on a project.
|
||||
This type of scope is great for managing resources that fit nicely within
|
||||
project boundaries. Good examples of project-level resources that can be
|
||||
managed with project-scoped tokens are:
|
||||
|
||||
* Instances: Virtual compute servers that require a project association in
|
||||
order to be created.
|
||||
* Volumes: Storage devices that can be attached to instances.
|
||||
|
||||
Unscoped
|
||||
--------
|
||||
|
||||
An *unscoped* token is a token that proves authentication, but doesn't carry
|
||||
any authorization. Users can obtain unscoped tokens by simply proving their
|
||||
identity with credentials. Unscoped tokens can be exchanged for any of the
|
||||
various scoped tokens if a user has authorization on the requested scope.
|
||||
|
||||
An example of where unscoped tokens are specifically useful is when users
|
||||
perform federated authentication. First, a user will receive an unscoped token
|
||||
pending successful federated authentication, which they can use to query
|
||||
keystone for a list of projects they're allowed to access. Then they can
|
||||
exchange their unscoped token for a project-scoped token allowing them to
|
||||
perform actions within a particular project.
|
||||
|
||||
Auth Token middleware
|
||||
=====================
|
||||
|
|
|
@ -0,0 +1,7 @@
|
|||
---
|
||||
fixes:
|
||||
- |
|
||||
[`bug 1757151 <https://bugs.launchpad.net/keystone/+bug/1757151>`_]
|
||||
More thorough documentation has been added for authorization and token
|
||||
scopes, which helps users and developers understand the purpose of scope
|
||||
and why it can be a useful tool for resource isolation and API protection.
|
Loading…
Reference in New Issue