diff --git a/doc/source/contributor/services.rst b/doc/source/contributor/services.rst index 8b62b56b1b..df0bd5ad33 100644 --- a/doc/source/contributor/services.rst +++ b/doc/source/contributor/services.rst @@ -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 ===================== diff --git a/releasenotes/notes/bug-1757151-43eb3baaa175f904.yaml b/releasenotes/notes/bug-1757151-43eb3baaa175f904.yaml new file mode 100644 index 0000000000..156d36bbd3 --- /dev/null +++ b/releasenotes/notes/bug-1757151-43eb3baaa175f904.yaml @@ -0,0 +1,7 @@ +--- +fixes: + - | + [`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.