openstack/keystone
Code Issues Proposed changes

Add scope documentation for service developers

Browse Source 
We have a document that attempts to help describe keystone concepts
to other OpenStack developers. Now that we've added system scope to
keystone, it makes sense to refresh this document and make it more
helpful for services.

This should help services consume various scopes to protect APIs at
various levels (project, domain, system, et cetera).

Change-Id: I1a92ed0b6bbba44d1050a857c3609d918bb25b86
Closes-Bug: 1757151
This commit is contained in:
Lance Bragstad 2018-03-20 22:52:27 +00:00
parent 488ecef329
commit a383867cdb
2 changed files with 140 additions and 13 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

146
doc/source/contributor/services.rst
View File

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

7
releasenotes/notes/bug-1757151-43eb3baaa175f904.yaml Normal file
View File

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