Remove duplicate token docs

Now that the admin guide is within keystone, we can remove all the
operator specific information we were maintaining in tree. This will
make it easier to operators to find all the information they need
related to tokens.

Change-Id: Iac2bf86a7b06b54fe8edea6ddbc62fe576b8959c

doc/source/admin/identity-fernet-token-faq.rst

@@ -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?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

doc/source/admin/identity-tokens.rst

@@ -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
 ~~~~~~~~~~~
@@ -90,19 +90,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

doc/source/configuration.rst

@@ -582,116 +582,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
 =============