diff options
Diffstat (limited to 'keystone-moon/doc/source/configure_federation.rst')
| -rw-r--r-- | keystone-moon/doc/source/configure_federation.rst | 124 |
1 files changed, 83 insertions, 41 deletions
diff --git a/keystone-moon/doc/source/configure_federation.rst b/keystone-moon/doc/source/configure_federation.rst index 2da5f822..09d0984d 100644 --- a/keystone-moon/doc/source/configure_federation.rst +++ b/keystone-moon/doc/source/configure_federation.rst @@ -34,54 +34,72 @@ Keystone as a Service Provider (SP) Prerequisites ------------- -This approach to federation supports Keystone as a Service Provider, consuming +This approach to federation supports keystone as a Service Provider, consuming identity properties issued by an external Identity Provider, such as SAML assertions or OpenID Connect claims. -Federated users are not mirrored in the Keystone identity backend +Federated users are not mirrored in the keystone identity backend (for example, using the SQL driver). The external Identity Provider is responsible for authenticating users, and communicates the result of -authentication to Keystone using identity properties. Keystone maps these -values to Keystone user groups and assignments created in Keystone. +authentication to keystone using identity properties. Keystone maps these +values to keystone user groups and assignments created in keystone. The following configuration steps were performed on a machine running Ubuntu 12.04 and Apache 2.2.22. To enable federation, you'll need to: -1. Run Keystone under Apache, rather than using ``keystone-all``. +1. Run keystone under Apache, rather than using ``keystone-all``. 2. Configure Apache to use a federation capable authentication method. -3. Enable ``OS-FEDERATION`` extension. +3. Configure ``federation`` in keystone. Configure Apache to use a federation capable authentication method ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -There are many ways to configure Federation in the Apache HTTPD server. -Using Shibboleth and OpenID Connect are documented so far. +There is currently support for two major federation protocols: -* To use Shibboleth, follow the steps outlined at: `Setup Shibboleth`_. -* To use OpenID Connect, follow the steps outlined at: `Setup OpenID Connect`_. +* SAML - Keystone supports the following implementations: -.. _`Setup Shibboleth`: extensions/shibboleth.html -.. _`Setup OpenID Connect`: extensions/openidc.html + * Shibboleth - see `Setup Shibboleth`_. + * Mellon - see `Setup Mellon`_. -Enable the ``OS-FEDERATION`` extension -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +* OpenID Connect - see `Setup OpenID Connect`_. -Follow the steps outlined at: `Enabling Federation Extension`_. +.. _`Setup Shibboleth`: federation/shibboleth.html +.. _`Setup OpenID Connect`: federation/openidc.html +.. _`Setup Mellon`: federation/mellon.html -.. _`Enabling Federation Extension`: extensions/federation.html +Configure keystone and Horizon for Single Sign-On +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Configuring Federation ----------------------- +* To configure horizon to access a federated keystone, + follow the steps outlined at: `Keystone Federation and Horizon`_. -Now that the Identity Provider and Keystone are communicating we can start to -configure the ``OS-FEDERATION`` extension. +.. _`Keystone Federation and Horizon`: federation/websso.html -1. Add local Keystone groups and roles -2. Add Identity Provider(s), Mapping(s), and Protocol(s) +Configuring Federation in Keystone +----------------------------------- + +Now that the Identity Provider and keystone are communicating we can start to +configure ``federation``. + +1. Configure authentication drivers in ``keystone.conf`` +2. Add local keystone groups and roles +3. Add Identity Provider(s), Mapping(s), and Protocol(s) + +Configure authentication drivers in ``keystone.conf`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Add the authentication methods to the ``[auth]`` section in ``keystone.conf``. +Names should be equal to protocol names added via Identity API v3. Here we use +examples ``saml2`` and ``openid``. -Create Keystone groups and assign roles +.. code-block:: bash + + [auth] + methods = external,password,token,saml2,openid + +Create keystone groups and assign roles ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ As mentioned earlier, no new users will be added to the Identity backend, but @@ -109,14 +127,14 @@ To utilize federation the following must be created in the Identity Service: * Mapping * Protocol -More information on ``OS-FEDERATION`` can be found `here +More information on ``federation in keystone`` can be found `here <http://specs.openstack.org/openstack/keystone-specs/api/v3/identity-api-v3-os-federation-ext.html>`__. ~~~~~~~~~~~~~~~~~ Identity Provider ~~~~~~~~~~~~~~~~~ -Create an Identity Provider object in Keystone, which represents the Identity +Create an Identity Provider object in keystone, which represents the Identity Provider we will use to authenticate end users. More information on identity providers can be found `here @@ -129,8 +147,10 @@ A mapping is a list of rules. The only Identity API objects that will support ma and users. Mapping adds a set of rules to map federation protocol attributes to Identity API objects. -An Identity Provider has exactly one mapping specified per protocol. +There are many different ways to setup as well as combine these rules. More information on +rules can be found on the :doc:`mapping_combinations` page. +An Identity Provider has exactly one mapping specified per protocol. Mapping objects can be used multiple times by different combinations of Identity Provider and Protocol. More information on mapping can be found `here @@ -150,7 +170,7 @@ you want to use with the combination of the IdP and Protocol. Performing federated authentication ----------------------------------- -1. Authenticate externally and generate an unscoped token in Keystone +1. Authenticate externally and generate an unscoped token in keystone 2. Determine accessible resources 3. Get a scoped token @@ -243,11 +263,22 @@ Keystone as an Identity Provider (IdP) that will not be backported). These issues have been fixed and this feature is considered stable and supported as of the Kilo release. +.. NOTE:: + + This feature requires installation of the xmlsec1 tool via your + distribution packaging system (for instance apt or yum) + + Example for apt: + + .. code-block:: bash + + $ apt-get install xmlsec1 + Configuration Options --------------------- There are certain settings in ``keystone.conf`` that must be setup, prior to -attempting to federate multiple Keystone deployments. +attempting to federate multiple keystone deployments. Within ``keystone.conf``, assign values to the ``[saml]`` related fields, for example: @@ -270,7 +301,7 @@ also be setup. It is recommended that these values be URL safe. idp_organization_display_name=Example Corp. idp_organization_url=example.com -As with the Organizaion options, the Contact options, are not necessary, but +As with the Organization options, the Contact options, are not necessary, but it's advisable to set these values too. .. code-block:: ini @@ -286,7 +317,7 @@ Generate Metadata ----------------- In order to create a trust between the IdP and SP, metadata must be exchanged. -To create metadata for your Keystone IdP, run the ``keystone-manage`` command +To create metadata for your keystone IdP, run the ``keystone-manage`` command and pipe the output to a file. For example: .. code-block:: bash @@ -304,33 +335,44 @@ In this example we are creating a new Service Provider with an ID of ``BETA``, a ``sp_url`` of ``http://beta.example.com/Shibboleth.sso/POST/ECP`` and a ``auth_url`` of ``http://beta.example.com:5000/v3/OS-FEDERATION/identity_providers/beta/protocols/saml2/auth`` . The ``sp_url`` will be used when creating a SAML assertion for ``BETA`` and -signed by the current Keystone IdP. The ``auth_url`` is used to retrieve the -token for ``BETA`` once the SAML assertion is sent. +signed by the current keystone IdP. The ``auth_url`` is used to retrieve the +token for ``BETA`` once the SAML assertion is sent. Although the ``enabled`` +field is optional we are passing it set to ``true`` otherwise it will be set to +``false`` by default. .. code-block:: bash $ 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"}' \ + -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/service_providers/BETA | python -mjson.tool Testing it all out ------------------ -Lastly, if a scoped token and a Service Provider region are presented to -Keystone, the result will be a full SAML Assertion, signed by the IdP -Keystone, specifically intended for the Service Provider Keystone. +Lastly, if a scoped token and a Service Provider scope are presented to the +local keystone, the result will be a full ECP wrapped SAML Assertion, +specifically intended for the Service Provider keystone. + +.. NOTE:: + ECP stands for Enhanced Client or Proxy, an extension from the SAML2 + protocol used in non-browser interfaces, like in the following example + with cURL. .. code-block:: bash $ curl -s -X POST \ -H "Content-Type: application/json" \ -d '{"auth": {"scope": {"service_provider": {"id": "BETA"}}, "identity": {"token": {"id": "d793d935b9c343f783955cf39ee7dc3c"}, "methods": ["token"]}}}' \ - http://localhost:5000/v3/auth/OS-FEDERATION/saml2 + http://localhost:5000/v3/auth/OS-FEDERATION/saml2/ecp + +.. NOTE:: + Use URL http://localhost:5000/v3/auth/OS-FEDERATION/saml2 to request for + pure SAML Assertions. -At this point the SAML Assertion can be sent to the Service Provider Keystone -using the provided ``auth_url`` in the ``X-Auth-Url`` header present in the -response containing the SAML Assertion, and a valid OpenStack token, issued by -a Service Provider Keystone, will be returned. +At this point the ECP wrapped SAML Assertion can be sent to the Service +Provider keystone using the provided ``auth_url`` in the ``X-Auth-Url`` header +present in the response containing the Assertion, and a valid OpenStack +token, issued by a Service Provider keystone, will be returned. |