Keystone for Other Services¶
This document provides a summary of some things that other services need to know about how keystone works, and specifically about how they can take advantage of the v3 API. The v3 API was introduced as a stable API in the Grizzly release.
The process of determining if a user is who they claim to be (authN).
The process of determining if a user can do what they are requesting (authZ).
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.
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.
OpenStack services like identity, compute, image, etc.
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.
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.
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.
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.
A entity modeling an end-user of the system.
A container for users. Users indirectly inherit any authorization the group has on projects, domains, or the system.
A major new feature in v3 is domains. Every project, user, and user group is
owned by a domain (reflected by their
domain_id value) which provides them
their own namespace. For example, unlike in v2.0, usernames are no longer
unique across the deployment. You can have two users with the same name, but
they must be in different domains. However, user IDs are assigned to users by
keystone and are expected to be unique across the deployment. All of this logic
applies to projects, user groups and roles.
One of the great things about domains is that you can have one domain backed by SQL (for service users) and another backed by LDAP (the cloud is deployed into existing infrastructure).
The “default” domain¶
The v2.0 API has been removed as of the Queens release. While this section references the v2.0 API, it is purely for historical reasons that clarify the existence of the default domain.
Domains were introduced as a v3-only feature. As a result, the v2.0 API didn’t understand the concept of domains. To allow for both versions of the Identity API to run side-by-side, the idea of a default domain was established.
The default domain was a domain that was guaranteed to exist and was created
keystone-manage db_sync process. By default, the domain ID is
default and the name is
Default, but it is possible to change
these values through keystone’s configuration file. The v2.0 API would consider
users and projects existing within that domain as valid, but it would never
expose domain information through the API. This allowed the v2.0 API to operate
under the assumption that everything within the default domain was
accessible. This was crucial in avoiding namespace conflicts between v2.0 and
v3 where multiple domains existed. Using v3 allowed deployers the ability to
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.
Auth Token middleware¶
auth_token middleware handles token validation for the different
services. Conceptually, what happens is that
auth_token pulls the token out
X-Auth-Token request header, validates the token using keystone,
produces information about the identity (the API user) and authorization
context (the project, roles, etc) of the token, and sets environment variables
with that data. The services typically take the environment variables, put them
in the service’s “context”, and use the context for policy enforcement via
Service tokens are a feature where the
auth_token middleware will also
accept a service token in the
X-Service-Token header. It does the same
thing with the service token as the user token, but the results of the token
are passed separately in environment variables for the service token (the
service user, project, and roles). If the service knows about these then it can
put this info in its “context” and use it for policy checks. For example,
assuming there’s a special policy rule called
service_role that works like
role rule except checks the service roles, you could have an
oslo.policy rule like
service_role:service and user_id:%(user_id)s such
that a service token is required along with the user owning the object.
Picking the version¶
Use version discovery to figure out what version the identity server supports rather than configuring the version. This will make it easier to adopt new API versions as they are implemented.
For information about how to accomplish service discovery with the keystoneauth library, please see the documentation.
This feature is specific to v3 and allows projects to have parents, siblings, and children relationships with other projects.
Tokens scoped to projects in a hierarchical structure won’t contain information about the hierarchy in the token response. If the service needs to know the hierarchy it should use the v3 API to fetch the hierarchy.