diff --git a/doc/source/admin/caching.rst b/doc/source/admin/caching.rst new file mode 100644 index 0000000000..3fd6cca3b1 --- /dev/null +++ b/doc/source/admin/caching.rst @@ -0,0 +1,35 @@ +============= +Caching layer +============= + +Identity supports a caching layer that is above the configurable subsystems, +such as token or assignment. The majority of the caching configuration options +are set in the ``[cache]`` section. However, each section that has the +capability to be cached usually has a ``caching`` option that will toggle +caching for that specific section. By default, caching is globally disabled. + +Current functional back ends are: + +``dogpile.cache.memcached`` + Memcached back end using the standard ``python-memcached`` library. + +``dogpile.cache.pylibmc`` + Memcached back end using the ``pylibmc`` library. + +``dogpile.cache.bmemcached`` + Memcached using the ``python-binary-memcached`` library. + +``dogpile.cache.redis`` + Redis back end. + +``dogpile.cache.dbm`` + Local DBM file back end. + +``dogpile.cache.memory`` + In-memory cache, not suitable for use outside of testing as it does not + cleanup its internal cache on cache expiration and does not share cache + between processes. This means that caching and cache invalidation will not + be consistent or reliable. + +``dogpile.cache.mongo`` + MongoDB as caching back end. diff --git a/doc/source/admin/federated-identity.rst b/doc/source/admin/federated-identity.rst new file mode 100644 index 0000000000..173a92ace4 --- /dev/null +++ b/doc/source/admin/federated-identity.rst @@ -0,0 +1,501 @@ +================== +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 `_ +* `OpenID Connect `_ + +.. figure:: figures/keystone-federation.png + :width: 100% + + Keystone federation + +To enable federation: + +#. Run keystone under Apache. See `Configure the Apache HTTP server + `_ + for more information. + + .. note:: + + Other application servers, such as `nginx `_, + 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 `_ + for more information. + + .. note:: + + Another option is ``mod_auth_melon``, see `the mod's github repo `_ + 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 `Register an Identity Provider `_. + +#. Add mapping rules: + + .. code:: ini + + PUT /OS-FEDERATION/mappings/{mapping_id} + + More configuration information for mapping rules can be found `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 `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 ``_. + +#. Create a ``auth_url`` of ``_. + + .. 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": [ + { + " or " + } + ], + "remote": [ + { + "" + } + ] + } + ] + } + +* ``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 `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: + 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. diff --git a/doc/source/admin/figures/keystone-federation.png b/doc/source/admin/figures/keystone-federation.png new file mode 100644 index 0000000000..b076e006d8 Binary files /dev/null and b/doc/source/admin/figures/keystone-federation.png differ diff --git a/doc/source/admin/figures/keystone-federation.svg b/doc/source/admin/figures/keystone-federation.svg new file mode 100644 index 0000000000..0400405013 --- /dev/null +++ b/doc/source/admin/figures/keystone-federation.svg @@ -0,0 +1,79 @@ + + + + + + + + + + + + + + +
+
+ Identity service +
(keystone)
+
+
+ + [Not supported by viewer] + + + + + + + + + +
+
+

Federation

+
+
+ + [Not supported by viewer] + + + + + +
+
+

Service Provider (SP)

+
+
    +
  • SAML v2
    • +
  • OpenID Connect
    • +
+
+
+
+ + [Not supported by viewer] + + + + + +
+
+

Identity Provider (IdP)

+
+
    +
  • Keystone 2 KeyStore
    • +
  • PySAML 2
    • +
  • SAML
    • +
+
+
+
+ + [Not supported by viewer] + + + + \ No newline at end of file diff --git a/doc/source/admin/identity-management.rst b/doc/source/admin/identity-management.rst index 7eb180e8b6..3d51b77aea 100644 --- a/doc/source/admin/identity-management.rst +++ b/doc/source/admin/identity-management.rst @@ -30,3 +30,6 @@ command-line client. identity-auth-token-middleware.rst identity-service-api-protection.rst identity-troubleshoot.rst + token-provider.rst + federated-identity.rst + caching.rst diff --git a/doc/source/admin/token-provider.rst b/doc/source/admin/token-provider.rst new file mode 100644 index 0000000000..8de2f09245 --- /dev/null +++ b/doc/source/admin/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. diff --git a/doc/source/configuration/samples/index.rst b/doc/source/configuration/samples/index.rst new file mode 100644 index 0000000000..1d9e65d9ef --- /dev/null +++ b/doc/source/configuration/samples/index.rst @@ -0,0 +1,13 @@ +========================== +Sample configuration files +========================== + +You can find the files described in this section in the +``/etc/keystone`` directory. + +.. toctree:: + + keystone-conf.rst + keystone-paste-ini.rst + logging-conf.rst + policy-json.rst diff --git a/doc/source/configuration/samples/keystone-conf.rst b/doc/source/configuration/samples/keystone-conf.rst new file mode 100644 index 0000000000..683216eb17 --- /dev/null +++ b/doc/source/configuration/samples/keystone-conf.rst @@ -0,0 +1,8 @@ +============= +keystone.conf +============= + +Use the ``keystone.conf`` file to configure most Identity service +options: + +.. literalinclude:: ../../_static/keystone.conf.sample diff --git a/doc/source/configuration/samples/keystone-paste-ini.rst b/doc/source/configuration/samples/keystone-paste-ini.rst new file mode 100644 index 0000000000..e3c844b15b --- /dev/null +++ b/doc/source/configuration/samples/keystone-paste-ini.rst @@ -0,0 +1,8 @@ +================== +keystone-paste.ini +================== + +Use the ``keystone-paste.ini`` file to configure the Web Service Gateway +Interface (WSGI) middleware pipeline for the Identity service: + +.. literalinclude:: ../../../../etc/keystone-paste.ini diff --git a/doc/source/configuration/samples/logging-conf.rst b/doc/source/configuration/samples/logging-conf.rst new file mode 100644 index 0000000000..4d4232b617 --- /dev/null +++ b/doc/source/configuration/samples/logging-conf.rst @@ -0,0 +1,11 @@ +============ +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 +`__. + +.. literalinclude:: ../../../../etc/logging.conf.sample diff --git a/doc/source/configuration/samples/policy-json.rst b/doc/source/configuration/samples/policy-json.rst new file mode 100644 index 0000000000..02b7bb371b --- /dev/null +++ b/doc/source/configuration/samples/policy-json.rst @@ -0,0 +1,8 @@ +=========== +policy.json +=========== + +Use the ``policy.json`` file to define additional access controls that apply to +the Identity service: + +.. literalinclude:: ../../_static/keystone.policy.yaml.sample diff --git a/doc/source/index.rst b/doc/source/index.rst index a2547adc65..a67bf8eab0 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -96,6 +96,14 @@ Administrator Guides admin/identity-management.rst +Configuration Options +~~~~~~~~~~~~~~~~~~~~~ + +.. toctree:: + :maxdepth: 2 + + configuration/samples/index.rst + API Documentation ~~~~~~~~~~~~~~~~~