openstack/keystone
Code Issues Proposed changes

Merge "Remove duplicate token docs"

Browse Source
This commit is contained in:
Jenkins 2017-07-05 20:22:39 +00:00 committed by Gerrit Code Review
commit b9b3b5c389
4 changed files with 29 additions and 134 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

32
doc/source/admin/identity-fernet-token-faq.rst
View File

@ -5,6 +5,25 @@ Fernet - Frequently Asked Questions
The following questions have been asked periodically since the initial release
of the fernet token format in Kilo.
What is a fernet token?
~~~~~~~~~~~~~~~~~~~~~~~
A fernet token is a bearer token that represents user authentication. Fernet
tokens contain a limited amount of identity and authorization data in a
`MessagePacked <http://msgpack.org/>`_ payload. The payload is then wrapped as
a `Fernet <https://github.com/fernet/spec>`_ message for transport, where
Fernet provides the required web safe characteristics for use in URLs and
headers. The data inside a fernet token is protected using symmetric encryption
keys, or fernet keys.
What is a fernet key?
~~~~~~~~~~~~~~~~~~~~~
A fernet key is used to encrypt and decrypt fernet tokens. Each key is actually
composed of two smaller keys: a 128-bit AES encryption key and a 128-bit SHA256
HMAC signing key. The keys are held in a key repository that keystone passes to
a library that handles the encryption and decryption of tokens.
What are the different types of keys?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -80,12 +99,13 @@ Why should I choose fernet tokens over UUID tokens?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Even though fernet tokens operate very similarly to UUID tokens, they do not
require persistence. The keystone token database no longer suffers bloat as a
side effect of authentication. Pruning expired tokens from the token database
is no longer required when using fernet tokens. Because fernet tokens do not
require persistence, they do not have to be replicated. As long as each
keystone node shares the same key repository, fernet tokens can be created and
validated instantly across nodes.
require persistence or leverage the configured token persistence driver in any
way. The keystone token database no longer suffers bloat as a side effect of
authentication. Pruning expired tokens from the token database is no longer
required when using fernet tokens. Because fernet tokens do not require
persistence, they do not have to be replicated. As long as each keystone node
shares the same key repository, fernet tokens can be created and validated
instantly across nodes.
Why should I choose fernet tokens over PKI or PKIZ tokens?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

21
doc/source/admin/identity-tokens.rst
View File

@ -67,8 +67,8 @@ Token providers
---------------
The token type issued by keystone is configurable through the
``/etc/keystone/keystone.conf`` file. Currently, there are four supported
token types and they include ``UUID``, ``fernet``, ``PKI``, and ``PKIZ``.
``/etc/keystone/keystone.conf`` file. Currently, there are two supported
token types, ``UUID`` and ``fernet``.
UUID tokens
~~~~~~~~~~~
@ -107,19 +107,4 @@ to encrypt and decrypt fernet tokens. Like UUID tokens, fernet tokens must be
passed back to the Identity service in order to validate them. For more
information on the fernet token type, see the :doc:`identity-fernet-token-faq`.
PKI and PKIZ tokens
~~~~~~~~~~~~~~~~~~~
PKI tokens are signed documents that contain the authentication context, as
well as the service catalog. Depending on the size of the OpenStack deployment,
these tokens can be very long. The Identity service uses public/private key
pairs and certificates in order to create and validate PKI tokens.
The same concepts from PKI tokens apply to PKIZ tokens. The only difference
between the two is PKIZ tokens are compressed to help mitigate the size issues
of PKI. For more information on the certificate setup for PKI and PKIZ tokens,
see the :doc:`identity-certificates-for-pki`.
.. note::
PKI and PKIZ tokens are deprecated and not supported in Ocata.
.. support_matrix:: token-support-matrix.ini

0
doc/source/token-support-matrix.ini → doc/source/admin/token-support-matrix.ini
View File

110
doc/source/configuration.rst
View File

@ -584,116 +584,6 @@ plugins specified in ``methods``. This effectively disables external
authentication. For more details, refer to :doc:`External Authentication
<advanced-topics/external-auth>`.
Token Drivers and Providers
===========================
Token Persistence Driver
------------------------
Keystone supports customizable token persistence drivers. These can be
specified in the ``[token]`` section of the configuration file. Keystone
provides two non-test persistence backends. These can be set with the
``[token] driver`` configuration option.
The drivers keystone provides are:
* ``sql`` - The SQL-based (default) token persistence engine. Implemented by
:class:`keystone.token.persistence.backends.sql.Token`
Token Provider
--------------
Keystone supports customizable token providers and it is specified in the
``[token]`` section of the configuration file. Keystone provides two token
provider options (``fernet`` and ``uuid``, with ``fernet`` being the default).
Users may register their own token provider by configuring the
``[token] provider`` property.
* ``fernet`` - A Fernet based token provider. Implemented by
:class:`keystone.token.providers.fernet.Provider`
* ``uuid`` - A UUID based token provider. Implemented by
:class:`keystone.token.providers.uuid.Provider`
UUID or Fernet?
^^^^^^^^^^^^^^^
Each token format uses different technologies to achieve various performance,
scaling and architectural requirements.
UUID tokens contain randomly generated UUID4 IDs that are issued and
validated by the identity service. They are encoded using their hex digest for
transport and are thus URL-friendly. They must be persisted by the identity
service in order to be later validated. Revoking them is simply a matter of
deleting them from the token persistence backend.
Fernet tokens contain a limited amount of identity and authorization data in a
`MessagePacked <http://msgpack.org/>`_ payload. The payload is then wrapped as
a `Fernet <https://github.com/fernet/spec>`_ message for transport, where
Fernet provides the required web safe characteristics for use in URLs and
headers. Fernet tokens require symmetric encryption keys which can be
established using ``keystone-manage fernet_setup`` and periodically rotated
using ``keystone-manage fernet_rotate``.
.. WARNING::
UUID and Fernet tokens are both bearer tokens, meaning that they
must be protected from unnecessary disclosure to prevent unauthorized
access.
.. support_matrix:: token-support-matrix.ini
Encryption Keys for Fernet Tokens
=================================
``keystone-manage fernet_setup`` will attempt to create a key repository as
configured in the ``[fernet_tokens]`` section of ``keystone.conf`` and
bootstrap it with encryption keys.
A single 256-bit key is actually composed of two smaller keys: a 128-bit key
used for SHA256 HMAC signing and a 128-bit key used for AES encryption. See the
`Fernet token <https://github.com/fernet/spec>`_ specification for more detail.
``keystone-manage fernet_rotate`` will rotate encryption keys through the
following states:
* **Staged key**: In a key rotation, a new key is introduced into the rotation
in this state. Only one key is considered to be the *staged* key at any given
time. This key will become the *primary* during the *next* key rotation. This
key is only used to validate tokens and serves to avoid race conditions in
multi-node deployments (all nodes should recognize all *primary* keys in the
deployment at all times). In a multi-node keystone deployment this would
allow for the *staged* key to be replicated to all keystone nodes before
being promoted to *primary* on a single node. This prevents the case where a
*primary* key is created on one keystone node and tokens encrypted/signed with
that new *primary* are rejected on another keystone node because the new
*primary* doesn't exist there yet.
* **Primary key**: In a key rotation, the old *staged* key is promoted to be
the *primary*. Only one key is considered to be the *primary* key at any
given time. This is the key used to generate new tokens. This key is also
used to validate previously generated tokens.
* **Secondary keys**: In a key rotation, the old *primary* key is demoted to be
a *secondary* key. *Secondary* keys are only used to validate previously
generated tokens. You can maintain any number of *secondary* keys, up to
``[fernet_tokens] max_active_keys`` (where "active" refers to the sum of all
recognized keys in any state: *staged*, *primary* or *secondary*). When
``max_active_keys`` is exceeded during a key rotation, the oldest keys are
discarded.
When a new primary key is created, all new tokens will be encrypted using the
new primary key. The old primary key is demoted to a secondary key, which can
still be used for validating tokens. Excess secondary keys (beyond
``[fernet_tokens] max_active_keys``) are revoked. Revoked keys are permanently
deleted.
Rotating keys too frequently, or with ``[fernet_tokens] max_active_keys`` set
too low, will cause tokens to become invalid prior to their expiration. As
tokens may be fetched beyond there initial expiration period keys should not be
fully rotated within the period of ``[token] expiration`` + ``[token]
allow_expired_window`` seconds to prevent the tokens becoming unavailable.
Caching Layer
=============