diff options
Diffstat (limited to 'keystone-moon/doc/source/services.rst')
| -rw-r--r-- | keystone-moon/doc/source/services.rst | 200 |
1 files changed, 200 insertions, 0 deletions
diff --git a/keystone-moon/doc/source/services.rst b/keystone-moon/doc/source/services.rst new file mode 100644 index 00000000..2c71e450 --- /dev/null +++ b/keystone-moon/doc/source/services.rst @@ -0,0 +1,200 @@ +=========================== +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 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 services like identity, compute, image, etc. + +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 and the term is still used in reference to the v2.0 API. + + +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). + +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 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`` 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 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.0 or 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 +================= + +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.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. + +Picking 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 +<http://docs.openstack.org/developer/python-openstackclient/>`_ 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. + +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.0 to set up the hierarchy, you can get a v2.0 token +scoped to a project that's part of a hierarchy. |