Merge "[config ref] Adding token and federation info"

doc/config-reference/source/identity.rst

@@ -5,6 +5,9 @@ Identity service
 .. toctree::
 
    identity/options.rst
+   identity/token-provider.rst
+   identity/federated-identity.rst
+   identity/sample-configuration-files.rst
    identity/samples/index.rst
    identity/caching.rst
    tables/conf-changes/keystone.rst

doc/config-reference/source/identity/federated-identity.rst

@@ -0,0 +1,499 @@
+==================
+Federated Identity
+==================
+
+You can use federation for the Identity service (keystone) in two ways:
+
+* Supporting keystone as a :abbr:`SP (Service Provider)`: consuming identity
+  assertions issued by an external Identity Provider, such as SAML
+  assertions or OpenID Connect claims.
+* Supporting keystone as an :abbr:`IdP (Identity Provider)`: fulfilling
+  authentication requests on behalf of Service Providers.
+
+  .. note::
+
+      It is also possible to have one keystone act as an SP that
+      consumes Identity from another keystone acting as an IdP.
+
+There is currently support for two major federation protocols:
+
+* `SAML <https://en.wikipedia.org/wiki/SAML_2.0>`_
+* `OpenID Connect <https://en.wikipedia.org/wiki/OpenID_Connect>`_
+
+.. figure:: figures/keystone-federation.png
+   :width: 100%
+
+   Keystone federation
+
+To enable federation:
+
+#. Run keystone under Apache. See `Configure the Apache HTTP server <http://docs.openstack.org/mitaka/install-guide-obs/keystone-install.html>`_
+   for more information.
+
+   .. note::
+
+      Other application servers, such as `nginx <https://www.nginx.com/resources/wiki>`_,
+      have support for federation extensions that may work but are not tested
+      by the community.
+
+#. Configure Apache to use a federation capable module.
+   We recommend Shibboleth, see `the Shibboleth documentation <http://docs.openstack.org/developer/keystone/federation/shibboleth.html>`_
+   for more information.
+
+   .. note::
+
+      Another option is ``mod_auth_melon``, see `the mod's github repo <https://github.com/UNINETT/mod_auth_mellon>`_
+      for more information.
+
+#. Configure federation in keystone.
+
+.. note::
+
+   The external IdP is responsible for authenticating users and communicates
+   the result of authentication to keystone using authentication assertions.
+   Keystone maps these values to keystone user groups and assignments
+   created in keystone.
+
+Supporting keystone as a SP
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To have keystone as an SP, you will need to configure
+keystone to accept assertions from external IdPs. Examples of external
+IdPs are:
+
+* :abbr:`ADFS (Active Directory Federation Services)`
+* FreeIPA
+* Tivoli Access Manager
+* Keystone
+
+Configuring federation in keystone
+----------------------------------
+
+#. Configure authentication drivers in ``keystone.conf`` by adding the
+   authentication methods to the ``[auth]`` section in ``keystone.conf``.
+   Ensure the names are the same as to the protocol names added via Identity
+   API v3.
+
+   For example:
+
+   .. code-block:: ini
+
+      [auth]
+      methods = external,password,token,mapped,openid
+
+   .. note::
+
+      ``mapped`` and ``openid`` are the federation specific drivers.
+      The other names in the example are not related to federation.
+
+#. Create local keystone groups and assign roles.
+
+   .. important::
+
+      The keystone requires group-based role assignments to authorize
+      federated users. The federation mapping engine maps federated users into
+      local user groups, which are the actors in keystone's role assignments.
+
+#. Create an IdP object in keystone. The object must represent the
+   IdP you will use to authenticate end users:
+
+   .. code:: ini
+
+      PUT /OS-FEDERATION/identity_providers/{idp_id}
+
+   More configuration information for IdPs can be found `<http://specs.openstack.org/openstack/keystone-specs/api/v3/identity-api-v3-os-federation-ext.html#register-an-identity-provider>`_.
+
+#. Add mapping rules:
+
+   .. code:: ini
+
+      PUT /OS-FEDERATION/mappings/{mapping_id}
+
+   More configuration information for mapping rules can be found `<http://specs.openstack.org/openstack/keystone-specs/api/v3/identity-api-v3-os-federation-ext.html#create-a-mapping>`_.
+
+   .. note::
+
+       The only keystone API objects that support mapping are groups and users.
+
+#. Add a protocol object and specify the mapping ID you want to use with the
+   combination of the IdP and protocol:
+
+   .. code:: ini
+
+      PUT /OS-FEDERATION/identity_providers/{idp_id}/protocols/{protocol_id}
+
+   More configuration information for protocols can be found `<http://specs.openstack.org/openstack/keystone-specs/api/v3/identity-api-v3-os-federation-ext.html#add-a-protocol-and-attribute-mapping-to-an-identity-provider>`_.
+
+Performing federated authentication
+-----------------------------------
+
+#. Authenticate externally and generate an unscoped token in keystone:
+
+   .. note::
+
+      Unlike other authentication methods in keystone, the user does
+      not issue an HTTP POST request with authentication data in the request body.
+      To start federated authentication a user must access the dedicated URL with
+      IdP's and orotocol’s identifiers stored within a protected URL.
+      The URL has a format of:
+      ``/v3/OS-FEDERATION/identity_providers/{idp_id}/protocols/{protocol_id}/auth``.
+
+   .. code:: ini
+
+      GET/POST /OS-FEDERATION/identity_providers/{identity_provider}/protocols/{protocol}/auth
+
+#. Determine accessible resources. By using the previously returned token, the
+   user can issue requests to the list projects and domains that are
+   accessible.
+
+   * List projects a federated user can access: GET /OS-FEDERATION/projects
+   * List domains a federated user can access: GET /OS-FEDERATION/domains
+
+   .. code:: ini
+
+      GET /OS-FEDERATION/projects
+
+#. Get a scoped token. A federated user can request a scoped token using
+   the unscoped token. A project or domain can be specified by either ID or
+   name. An ID is sufficient to uniquely identify a project or domain.
+
+   .. code:: ini
+
+      POST /auth/tokens
+
+Supporting keystone as an IdP
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When acting as an IdP, the primary role of keystone is
+to issue assertions about users owned by keystone. This is done using PySAML2.
+
+Configuring federation in keystone
+----------------------------------
+
+There are certain settings in ``keystone.conf`` that must be set up, prior
+to attempting to federate multiple keystone deployments.
+
+#. Within ``keystone.conf``, assign values to the ``[saml]``
+   related fields, for example:
+
+   .. code:: ini
+
+      [saml]
+      certfile=/etc/keystone/ssl/certs/ca.pem
+      keyfile=/etc/keystone/ssl/private/cakey.pem
+      idp_entity_id=https://keystone.example.com/v3/OS-FEDERATION/saml2/idp
+      idp_sso_endpoint=https://keystone.example.com/v3/OS-FEDERATION/saml2/sso
+      idp_metadata_path=/etc/keystone/saml2_idp_metadata.xml
+
+#. We recommend the following `Organization` configuration options.
+   Ensure these values contain not special characters that may cause
+   problems as part of a URL:
+
+   .. code:: ini
+
+      idp_organization_name=example_company
+      idp_organization_display_name=Example Corp.
+      idp_organization_url=example.com
+
+#. As with the `Organization` options, the `Contact` options are not
+   necessary, but it is advisable to set these values:
+
+   .. code:: ini
+
+      idp_contact_company=example_company
+      idp_contact_name=John
+      idp_contact_surname=Smith
+      idp_contact_email=jsmith@example.com
+      idp_contact_telephone=555-55-5555
+      idp_contact_type=technical
+
+Generate metadata
+-----------------
+
+Metadata must be exchanged to create a trust between the IdP and the SP.
+
+#. Create metadata for your keystone IdP, run the ``keystone-manage`` command
+   and pipe the output to a file. For example:
+
+   .. code:: console
+
+      $ keystone-manage saml_idp_metadata > /etc/keystone/saml2_idp_metadata.xml
+
+   .. note::
+
+      The file location must match the value of the ``idp_metadata_path``
+      configuration option assigned previously.
+
+Create a SP
+-----------
+
+To setup keystone-as-a-Service-Provider properly, you will need to
+understand what protocols are supported by external IdPs.
+For example, keystone as an SP can allow identities to federate in from a
+ADFS IdP but it must be configured to understand the SAML v2.0 protocol.
+ADFS issues assertions using SAML v2.0. Some examples
+of federated protocols include:
+
+* SAML v2.0
+* OpenID Connect
+
+The following instructions are an example of how you can configure
+keystone as an SP.
+
+#. Create a new SP with an ID of BETA.
+
+#. Create a ``sp_url`` of `<http://beta.example.com/Shibboleth.sso/SAML2/ECP>`_.
+
+#. Create a ``auth_url`` of `<http://beta.example.com:5000/v3/OS-FEDERATION/identity_providers/beta/protocols/saml2/auth>`_.
+
+   .. note::
+
+      Use the ``sp_url`` when creating a SAML assertion for BETA and signed by
+      the current keystone IdP. Use the ``auth_url`` when retrieving the token
+      for BETA once the SAML assertion is sent.
+
+#. Set the ``enabled`` field to ``true``. It is set to
+   ``false`` by default.
+
+#. Your output should reflect the following example:
+
+   .. code:: console
+
+      $ curl -s -X PUT \
+     -H "X-Auth-Token: $OS_TOKEN" \
+     -H "Content-Type: application/json" \
+     -d '{"service_provider": {"auth_url": "http://beta.example.com:5000/v3/OS-FEDERATION/identity_providers/beta/protocols/saml2/auth", "sp_url": "https://example.com:5000/Shibboleth.sso/SAML2/ECP", "enabled": true}}' \
+     http://localhost:5000/v3/OS-FEDERATION/service_providers/BETA | python -mjson.tool
+
+keystone-to-keystone
+~~~~~~~~~~~~~~~~~~~~
+
+Keystone acting as an IdP is known as :abbr:`k2k (keystone-2-keystone)`
+or k2k federation, where a keystone somewhere is acting as the SP
+and another keystone is acting as the IdP. All IdPs issue
+assertions about the identities it owns using a `Protocol`.
+
+Mapping rules
+~~~~~~~~~~~~~
+
+Mapping adds a set of rules to map federation attributes to keystone users
+or groups. An IdP has exactly one mapping specified per protocol.
+
+A mapping is a translation between assertions provided from an IdP and
+the permission and roles applied by an SP. Given an assertion from an IdP, an
+SP applies a mapping to translate attributes from the
+IdP to known roles. A mapping is typically
+owned by an SP.
+
+Mapping objects can be used multiple times by different combinations
+of IdP and protocol.
+
+A rule hierarchy is as follows:
+
+.. code:: ini
+
+   {
+        "rules": [
+           {
+               "local": [
+                  {
+                       "<user> or <group>"
+                   }
+               ],
+               "remote": [
+                   {
+                       "<condition>"
+                   }
+               ]
+           }
+       ]
+   }
+
+* ``rules``: top-level list of rules.
+* ``local``: a rule containing information on what local attributes
+  will be mapped.
+* ``remote``: a rule containing information on what remote attributes will
+  be mapped.
+* ``condition``: contains information on conditions that allow a rule, can
+  only be set in a remote rule.
+
+For more information on mapping rules, see `<http://docs.openstack.org/developer/keystone/federation/federated_identity.html#mapping-rules>`_.
+
+Mapping creation
+----------------
+
+Mapping creation starts with the communication between the IdP and SP.
+The IdP usually provides a set of assertions that their users
+have in their assertion document. The SP will have to map
+those assertions to known groups and roles.
+For example:
+
+.. code:: ini
+
+   Identity Provider 1:
+     name: jsmith
+     groups: hacker
+     other: <assertion information>
+   The Service Provider may have 3 groups:
+     Admin Group
+     Developer Group
+     User Group
+
+   The mapping created by the Service Provider might look like:
+     Local:
+     Group: Developer Group
+   Remote:
+     Groups: hackers
+
+The ``Developer Group`` may have a role assignment on the
+``Developer Project``. When `jsmith` authenticates against IdP 1, it
+presents that assertion to the SP.The SP maps the `jsmith` user to the
+``Developer Group`` because the assertion says `jsmith` is a member of
+the ``hacker`` group.
+
+Mapping examples
+----------------
+
+A bare bones mapping is sufficient if you would like all federated users to
+have the same authorization in the SP cloud. However, mapping is
+quite powerful and flexible. You can map different remote
+users into different user groups in keystone, limited only by the number of
+assertions your IdP makes about each user.
+
+A mapping is composed of a list of rules, and each rule is further composed of
+a list of remote attributes and a list of local attributes. If a rule is
+matched, all of the local attributes are applied in the SP. For a
+rule to match, all of the remote attributes it defines must match.
+
+In the base case, a federated user simply needs an assertion containing
+an email address to be identified in the SP cloud. To achieve that, only
+one rule is needed that requires the presence of one remote attribute:
+
+.. code:: javascript
+
+    {
+        "rules": [
+            {
+                "remote": [
+                    {
+                        "type": "Email"
+                    }
+                ],
+                "local": [
+                    {
+                        "user": {
+                            "name": "{0}"
+                        }
+                    }
+                ]
+            }
+        ]
+    }
+
+However, that is not particularly useful as the federated user would receive no
+authorization. To rectify it, you can map all federated users with email
+addresses into a ``federated-users`` group in the ``default`` domain. All
+federated users will then be able to consume whatever role assignments that
+user group has already received in keystone:
+
+.. note::
+
+   In this example, there is only one rule requiring one remote attribute.
+
+.. code:: javascript
+
+    {
+        "rules": [
+            {
+                "remote": [
+                    {
+                        "type": "Email"
+                    }
+                ],
+                "local": [
+                    {
+                        "user": {
+                            "name": "{0}"
+                        }
+                    },
+                    {
+                        "group": {
+                            "domain": {
+                                "id": "0cd5e9"
+                            },
+                            "name": "federated-users"
+                        }
+                    }
+                ]
+            }
+        ]
+    }
+
+This example can be expanded by adding a second rule that conveys
+additional authorization to only a subset of federated users. Federated users
+with a `title` attribute that matches either ``Manager`` or
+``Supervisor`` are granted the hypothetical ``observer`` role, which would
+allow them to perform any read-only API call in the cloud:
+
+.. code:: javascript
+
+    {
+        "rules": [
+            {
+                "remote": [
+                    {
+                        "type": "Email"
+                    },
+                ],
+                "local": [
+                    {
+                        "user": {
+                            "name": "{0}"
+                        }
+                    },
+                    {
+                        "group": {
+                            "domain": {
+                                "id": "default"
+                            },
+                            "name": "federated-users"
+                        }
+                    }
+                ]
+            },
+            {
+                "remote": [
+                    {
+                        "type": "Title",
+                        "any_one_of": [".*Manager$", "Supervisor"],
+                        "regex": "true"
+                    },
+                ],
+                "local": [
+                    {
+                        "group": {
+                            "domain": {
+                                "id": "default"
+                            },
+                            "name": "observers"
+                        }
+                    }
+                ]
+            }
+        ]
+    }
+
+.. note::
+
+   ``any_one_of`` and ``regex`` in the rule above map federated users into
+   the ``observers`` group when a user's ``Title`` assertion matches any of
+   the regular expressions specified in the ``any_one_of`` attribute.
+
+Keystone also supports the following:
+
+* ``not_any_of``, matches any assertion that does not include one of
+  the specified values
+* ``blacklist``, matches all assertions of the specified type except
+  those included in the specified value
+* ``whitelist`` does not match any assertion except those listed in the
+  specified value.

doc/config-reference/source/identity/sample-configuration-files.rst

@@ -0,0 +1,49 @@
+===========================================
+Identity service sample configuration files
+===========================================
+
+The files described in this section are in the ``/etc/keystone`` directory.
+
+keystone.conf
+~~~~~~~~~~~~~
+
+Use the ``keystone.conf`` file to configure most Identity service
+options:
+
+.. remote-code-block:: ini
+
+   https://git.openstack.org/cgit/openstack/keystone/plain/etc/keystone.conf.sample?h=stable/mitaka
+
+keystone-paste.ini
+~~~~~~~~~~~~~~~~~~
+
+Use the ``keystone-paste.ini`` file to configure the
+:abbr:`WSGI (Web Service Gateway Interface)` middleware pipeline for
+the Identity service:
+
+.. remote-code-block:: ini
+
+   https://git.openstack.org/cgit/openstack/keystone/plain/etc/keystone-paste.ini?h=stable/mitaka
+
+logging.conf
+~~~~~~~~~~~~
+
+You can specify a special logging configuration file in the ``keystone.conf``
+configuration file. For example, ``/etc/keystone/logging.conf``.
+
+For details, see the `Python logging module documentation
+<http://docs.python.org/2/howto/logging.html#configuring-logging>`__.
+
+.. remote-code-block:: ini
+
+   https://git.openstack.org/cgit/openstack/keystone/plain/etc/logging.conf.sample?h=stable/mitaka
+
+policy.json
+~~~~~~~~~~~
+
+Use the ``policy.json`` file to define access controls that apply to
+the Identity service:
+
+.. remote-code-block:: json
+
+   https://git.openstack.org/cgit/openstack/keystone/plain/etc/policy.json?h=stable/mitaka

doc/config-reference/source/identity/token-provider.rst

@@ -0,0 +1,49 @@
+==============
+Token provider
+==============
+
+OpenStack Identity supports customizable token providers. This is specified
+in the ``[token]`` section of the configuration file. The token provider
+controls the token construction, validation, and revocation operations.
+
+You can register your own token provider by configuring the following property:
+
+.. note::
+
+   More commonly, you can use this option to change the token provider to one
+   of the ones built in. Alternatively, you can use it to configure your own
+   token provider.
+
+* ``provider`` - token provider driver.
+  Defaults to ``uuid``.
+  Implemented by :class:`keystone.token.providers.uuid.Provider`. This is the
+  entry point for the token provider in the ``keystone.token.provider``
+  namespace.
+
+Each token format uses different technologies to achieve various performance,
+scaling, and architectural requirements. The Identity service includes
+``fernet``, ``pkiz``, ``pki``, and ``uuid`` token providers.
+
+Below is the detailed list of the token formats:
+
+UUID
+ ``uuid`` tokens must be persisted (using the back end specified in the
+ ``[token] driver`` option), but do not require any extra configuration
+ or setup.
+
+PKI and PKIZ
+ ``pki`` and ``pkiz`` tokens can be validated offline, without making HTTP
+ calls to keystone. However, this format requires that certificates be
+ installed and distributed to facilitate signing tokens and later validating
+ those signatures.
+
+Fernet
+ ``fernet`` tokens do not need to be persisted at all, but require that you run
+ ``keystone-manage fernet_setup`` (also see the
+ ``keystone-manage fernet_rotate`` command).
+
+.. warning::
+
+    UUID, PKI, PKIZ, and Fernet tokens are all bearer tokens. They
+    must be protected from unnecessary disclosure to prevent unauthorized
+    access.