Remove references to v2.0 from external developer doc
The external developer document we have attempts to clarify various concepts in keystone and make it easier for other developers writing other services. Now that we've removed the v2.0 API, it makes sense to update this documentation to refer to v2.0 in the past tense. Some parts of the document seemed specific to operator documentation, which has been either removed or reworked to the intended operators, other service developers. Change-Id: I809150f8b77a813e2300760fdcb1d11cfa8ca732
This commit is contained in:
Lance Bragstad
parent
c402691371
commit
9bc92c563d
|
|
@ -36,7 +36,7 @@ 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.
|
||||
as tenants in the v2.0 API.
|
||||
|
||||
|
||||
Domains
|
||||
|
|
@ -58,67 +58,33 @@ 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.
|
||||
.. note::
|
||||
|
||||
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.*
|
||||
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 existance 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.
|
||||
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.
|
||||
|
||||
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.
|
||||
The *default* domain was a domain that was guaranteed to exist and was created
|
||||
during the ``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.
|
||||
|
||||
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.
|
||||
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
|
||||
=================
|
||||
|
||||
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
|
||||
--------------------
|
||||
|
||||
|
|
@ -155,59 +121,23 @@ 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
|
||||
<https://docs.openstack.org/python-openstackclient/latest>`_ has all the
|
||||
keystone CLI commands and even supports v3.
|
||||
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
|
||||
<https://docs.openstack.org/keystoneauth/latest/using-sessions.html#service-discovery>`_.
|
||||
|
||||
Hierarchical Multitenancy
|
||||
=========================
|
||||
|
||||
This feature allows maintenance of a hierarchy of projects with "parent"
|
||||
projects operating as domains.
|
||||
This feature is specific to v3 and allows projects to have parents, siblings,
|
||||
and children relationships with other projects.
|
||||
|
||||
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.
|
||||
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.
|
||||
|
|
|
|||
Loading…
Reference in New Issue