diff --git a/doc/source/services.rst b/doc/source/services.rst index c51b618608..2c71e4504f 100644 --- a/doc/source/services.rst +++ b/doc/source/services.rst @@ -2,112 +2,161 @@ Keystone for other services =========================== -This document provides a summary of some things that other services -need to know about how keystone works. Specifically, we were requested -to describe what other services need to know about the v3 API. The v3 -API was introduced in the Grizzly release, and its use until recently -has been hidden from other services since the auth_token middleware -translated the token format so that both versions look the same. Once -the services need to make use of v3 features they need to know about -how it works. +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 and included +in the default pipeline ever since. Until recently, its use has been hidden +from other services because the ``auth_token`` middleware translated the token +format so that both versions look the same. Once the services need to make use +of v3 features they need to know about how it works. Glossary ======== Service - OpenStack servers like keystone, nova, glance, etc. + OpenStack services like identity, compute, image, etc. Project - A project is a namespace for a grouping 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 and the - term is still used in reference to the v2.0 API. - - -Token differences -================= - -The keystone service runs both v2 and v3, v2 requests go to /v2.0 and v3 -requests go to /v3. You don't need to "enable" the v3 API in keystone, it is -available by default via a separate pipeline from v2.0. If you get a token -using the v2 API you can use it to do v3 operations (like list users and -stuff). The reverse also works, get a v3 token and use it on v2 works fine. - -You can get a v2 token using POST /v2.0/tokens. You can get a v3 token -using POST /v3/auth/tokens. The response is different: the service -catalog is a different format, and the v3 token has more fields (user -domain, project domain). + 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 and the term is still used in reference to the v2.0 API. Domains ======= -A major change to v3 is domains. Every project, user, and group is in a domain. -This means they have a domain_id. You can have two users with the same name but -they must be in different domains, thus usernames are not globally unique -across the deployment. Unique identifiers assigned to users from keystone are -expected to be unique across the deployment. However, roles are not in domains. +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 both projects and user groups as well. Note that roles are *not* +namespaced by domains. -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). +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). -If you do v2 operations, there's no way to specify the domain, so v2 -operations all work against the default domain. So if you're stuck with -v2 and need to get a token you can only get tokens for users in the -default domain. If your default domain is SQL and you have a domain for -LDAP users called "ldap" you can't get to the users in LDAP using v2. -Also, if your default domain is read-only LDAP then you won't be able -to create the service users using v2 clients because any SQL-backed -domain is unreachable. +The "default" domain +==================== + +Conventionally the "default" domain has a domain ID of ``default`` and a domain +name of ``Default``. It is created by ``keystone-manage db_sync`` and thus +should always exist, although the domain ID is configurable in +``keystone.conf`` and the domain name is mutable through the v3 API. + +Because only the v3 API is domain-aware, we must work to avoid perceived +namespace conflicts to v2.0 clients. The solution to this is to have a single +domain serve as the implied namespace for all user and tenant references in +v2.0. Thus, v2.0 clients can continue to be domain-unaware and avoid the +security risk posed by potential namespace conflicts. *This is the only purpose +of the default domain.* + +For example, I could otherwise create a domain in v3, create a user in that +domain called "admin", authenticate using v2.0, and a domain-unaware v2.0 +client might assume I'm the same "admin" user it has seen before and grant me +escalated privileges. Instead, users outside of the default domain simply +cannot authenticate against v2.0, nor can such tokens with references to users +and projects outside the default domain be validated on the v2.0 API. + +From a v2.0 client's perspective, there's no way to specify the domain, so v2.0 +operations implicitly work against the default domain. So if your client is +only capable of using v2.0 and you need to get a token, then you can only get +tokens for users and tenants (projects) in the default domain. In the real +world, this means that if your default domain is backed by SQL and you have a +separate domain for LDAP users, then you can't authenticate as an LDAP user +using v2.0. Conversely, if your default domain is backed by a read-only LDAP +driver, then you won't be able to create the service users using v2.0 clients +because any SQL-backed domain is unreachable. + +From a v3 client's perspective, the default domain is not special, other than +the fact that such a domain can generally be assumed to exist (assuming the +deployment is also running the v2.0 API). It would be reasonable for a v3 +client to assume a default user domain ID of ``default`` and a default project +domain ID of ``default`` unless overridden by more specific configuration. + +To summarize, avoiding namespace conflicts in the v2.0 API is achieved by +limiting the v2.0 API and its clients to working with users and projects which +are namespaced by a single, arbitrary domain in v3. + +Token differences +================= + +The keystone service runs both v2.0 and v3, where v2.0 requests go to the +``/v2.0`` endpoint and v3 requests go to the ``/v3`` endpoint. If you're using +the default pipeline that ships with keystone, then you don't need "enable" the +v3 API in keystone, as it runs by default as a parallel pipeline to the v2.0 +API. + +If you get a token using the v2.0 API, then you can use it to do v3 operations +(such as list users). The reverse, using a v3 token against v2.0, is possible +only in certain circumstances. For example, if you're using a project-scoped +token wherein the user and project are both owned by the "default" domain, +everything will work. Otherwise, token validation against the v2.0 API will +fail. + +You can get a v2.0 token using ``POST /v2.0/tokens``. You can get a v3 token +using ``POST /v3/auth/tokens``. Note that the responses are significantly +different. For example, the service catalog is in a different format, and the +v3 token conveys additional context (such as the user's domain and the +project's domain). Domain-scoped tokens -------------------- -Domain-scoped tokens are scoped to a domain rather than a project. -These are useful for operating against keystone but are useless in -other services, so other services don't need to concern themselves with -domain-scoped tokens. +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. Auth Token middleware ===================== -The auth_token middleware handles token validation for the different services. -Conceptually, what happens is that auth_token pulls the token out of the -X-Auth-Token header, sends the token to keystone to validate the token and get -information about the token (the user, project, and roles), and sets a bunch of -environment variables with the user, project, and roles. The services typically -take the environment variables, put them in the service's "context", and use -the context for policy enforcement via oslo.policy. +The ``auth_token`` middleware handles token validation for the different +services. Conceptually, what happens is that ``auth_token`` pulls the token out +of the ``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 +``oslo.policy``. Service tokens -------------- -Service tokens are a new-ish 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 get stuck 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 the ``role`` rule except checks -the service roles, you could have a rule like ``service_role:service -and user_id:%(user_id)s`` so that a service token is required along -with the user owning the object. +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 +the ``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. -V2 / V3 -------- +v2.0 or v3? +----------- -The auth_token middleware can be configured to authenticate tokens -using v2, v3, or to use discovery (the default). When discovery is -used, auth_token will pick v3 if the server reports that v3 is -available. If auth_token is configured to use v2 then if it receives a -v3 token it will fail if the user is not in the default domain (e.g., -the domain that heat creates users in). So auth_token middleware needs -to use v3! +By default, the ``auth_token`` middleware will use discovery to determine the +best available API to use, or can be explicitly configured to use either v2.0 +or v3. When discovery is used, ``auth_token`` will use v3 if keystone reports +that v3 is available. If ``auth_token`` is configured to use v2.0, then it will +fail when it receives a v3 token wherein the user is not in the default domain +(for example, the domain that heat creates users in). So if at all possible, +the ``auth_token`` middleware should be allowed to use v3. +Additionally, as other services begin to utilize features which are only found +in the v3 API, you'll need to use the v3 API in order to utilize those +services. For example, heat creates users in an isolated domain, and thus +requires the v3 API. Do this, not that ================= @@ -115,39 +164,37 @@ Do this, not that Config options for authentication --------------------------------- -If you need to get a token, don't define options for username and -password and get a token using v2. We've got an interface for using -authentication plugins where there's an option for that supports v2 or -v3 and potentially other authentication mechanisms (X.509 client -certs!). +If you need to get a token, don't define options for username and password and +get a token using v2.0. We've got an interface for using authentication plugins +where there's an option for that supports v2.0 or v3 and potentially other +authentication mechanisms (X.509 client certs!). -If your config file doesn't have the domain for the user, it's not -going to be able to use v3 for authentication. +If your config file doesn't have the domain for the user, it's not going to be +able to use v3 for authentication. Picking the version ------------------- -Use version discovery to figure out what version the identity server -supports rather than configuring the version. +Use version discovery to figure out what version the identity server supports +rather than configuring the version. Use OpenStack CLI not keystone CLI ---------------------------------- The keystone CLI is deprecated and will be removed soon. The `OpenStack CLI -`_ -has all the keystone CLI commands and even supports v3. +`_ has all the +keystone CLI commands and even supports v3. Hierarchical Multitenancy ========================= -This feature allows maintenance of a hierarchy of projects with -"parent" projects operating as domains. +This feature allows maintenance of a hierarchy of projects with "parent" +projects operating as domains. -The token format is the same (the token doesn't contain any info about -the hierarchy). If the service needs to know the hierarchy it will have -to use the v3 API to fetch the hierarchy. +The token format is the same (the token doesn't contain any info about the +hierarchy). If the service needs to know the hierarchy it will have to use the +v3 API to fetch the hierarchy. -While you can't use v2 to set up the hierarchy, you can get a v2 token +While you can't use v2.0 to set up the hierarchy, you can get a v2.0 token scoped to a project that's part of a hierarchy. -