"Fossies" - the Fresh Open Source Software Archive  

Source code changes of the file "doc/source/admin/federation/configure_federation.rst" between
keystone-15.0.0.tar.gz and keystone-15.0.1.tar.gz

About: OpenStack Keystone (Core Service: Identity) provides an authentication and authorization service for other OpenStack services. Provides a catalog of endpoints for all OpenStack services.
The "Stein" series (maintained release).

configure_federation.rst  (keystone-15.0.0):configure_federation.rst  (keystone-15.0.1)
skipping to change at line 29 skipping to change at line 29
----------------------------------- -----------------------------------
Keystone as a Service Provider (SP) Keystone as a Service Provider (SP)
----------------------------------- -----------------------------------
.. _sp-prerequisites: .. _sp-prerequisites:
Prerequisites Prerequisites
------------- -------------
If you are not familiar with the idea of federated identity, see the If you are not familiar with the idea of federated identity, see the
`introduction`_ first. :ref:`federation_introduction` first.
In this section, we will configure keystone as a Service Provider, consuming In this section, we will configure keystone as a Service Provider, consuming
identity properties issued by an external Identity Provider, such as SAML identity properties issued by an external Identity Provider, such as SAML
assertions or OpenID Connect claims. For testing purposes, we recommend using assertions or OpenID Connect claims. For testing purposes, we recommend using
`samltest.id`_ as a SAML Identity Provider, or Google as an OpenID Connect `samltest.id`_ as a SAML Identity Provider, or Google as an OpenID Connect
Identity Provider, and the examples here will references those providers. If you Identity Provider, and the examples here will references those providers. If you
plan to set up `Keystone as an Identity Provider (IdP)`_, it is easiest to set plan to set up `Keystone as an Identity Provider (IdP)`_, it is easiest to set
up keystone with a dummy SAML provider first and then reconfigure it to point to up keystone with a dummy SAML provider first and then reconfigure it to point to
the keystone Identity Provider later. the keystone Identity Provider later.
The following configuration steps were performed on a machine running The following configuration steps were performed on a machine running
Ubuntu 16.04 and Apache 2.4.18. Ubuntu 16.04 and Apache 2.4.18.
To enable federation, you'll need to run keystone behind a web server such as To enable federation, you'll need to run keystone behind a web server such as
Apache rather than running the WSGI application directly with uWSGI or Gunicorn. Apache rather than running the WSGI application directly with uWSGI or Gunicorn.
See the installation guide for `SUSE`_, `RedHat`_ or `Ubuntu`_ to configure See the installation guide for :ref:`SUSE <suse_configure_apache>`,
the Apache web server for keystone. :ref:`RedHat <redhat_configure_apache>` or :ref:`Ubuntu
<ubuntu_configure_apache>` to configure the Apache web server for
keystone.
Throughout the rest of the guide, you will need to decide on three pieces of Throughout the rest of the guide, you will need to decide on three pieces of
information and use them consistently throughout your configuration: information and use them consistently throughout your configuration:
1. The protocol name. This must be a valid keystone auth method and must match 1. The protocol name. This must be a valid keystone auth method and must match
one of: ``saml2``, ``openid``, ``mapped`` or a `custom auth method`_ for whic one of: ``saml2``, ``openid``, ``mapped`` or a :ref:`custom auth
h method <auth_plugins>` for which
you must `register as an external driver`_. you must :ref:`register as an external driver <developing_drivers>`.
2. The identity provider name. This can be arbitrary. 2. The identity provider name. This can be arbitrary.
3. The entity ID of the service provider. This should be a URN but need not 3. The entity ID of the service provider. This should be a URN but need not
resolve to anything. resolve to anything.
You will also need to decide what HTTPD module to use as a Service Provider. You will also need to decide what HTTPD module to use as a Service Provider.
This guide provides examples for ``mod_shib`` and ``mod_auth_mellon`` as SAML This guide provides examples for ``mod_shib`` and ``mod_auth_mellon`` as SAML
service providers, and ``mod_auth_openidc`` as an OpenID Connect Service service providers, and ``mod_auth_openidc`` as an OpenID Connect Service
Provider. Provider.
.. note:: .. note::
In this guide, the keystone Service Provider is configured on a host called In this guide, the keystone Service Provider is configured on a host called
sp.keystone.example.org listening on the standard HTTPS port. All keystone sp.keystone.example.org listening on the standard HTTPS port. All keystone
paths will start with the keystone version prefix, ``/v3``. If you have paths will start with the keystone version prefix, ``/v3``. If you have
configured keystone to listen on port 5000, or to respond on the path configured keystone to listen on port 5000, or to respond on the path
``/identity`` (for example), take this into account in your own ``/identity`` (for example), take this into account in your own
configuration. configuration.
.. _introduction: introduction
.. _samltest.id: https://samltest.id .. _samltest.id: https://samltest.id
.. _SUSE: ../../install/keystone-install-obs.html#configure-the-apache-http-serv
er
.. _RedHat: ../../install/keystone-install-rdo.html#configure-the-apache-http-se
rver
.. _Ubuntu: ../../install/keystone-install-ubuntu.html#configure-the-apache-http
-server
.. _custom auth method: ../../contributor/auth-plugins
.. _register as an external driver: ../../contributor/developing-drivers
Creating federation resources in keystone Creating federation resources in keystone
----------------------------------------- -----------------------------------------
You need to create three resources via the keystone API to identify the Identity You need to create three resources via the keystone API to identify the Identity
Provider to keystone and align remote user attributes with keystone objects: Provider to keystone and align remote user attributes with keystone objects:
* `Create an Identity Provider`_ * `Create an Identity Provider`_
* `Create a Mapping`_ * `Create a Mapping`_
* `Create a Protocol`_ * `Create a Protocol`_
skipping to change at line 136 skipping to change at line 133
specified, this allows the same *keystone* identity provider resource to be specified, this allows the same *keystone* identity provider resource to be
used with multiple external identity providers. For example, an identity used with multiple external identity providers. For example, an identity
provider resource ``university-idp``, may have the following ``remote_ids``: provider resource ``university-idp``, may have the following ``remote_ids``:
``['university-x', 'university-y', 'university-z']``. ``['university-x', 'university-y', 'university-z']``.
This removes the need to configure N identity providers in keystone. This removes the need to configure N identity providers in keystone.
See also the `API reference on identity providers`_. See also the `API reference on identity providers`_.
.. _API reference on identity providers: https://developer.openstack.org/api-ref /identity/v3-ext/#identity-providers .. _API reference on identity providers: https://developer.openstack.org/api-ref /identity/v3-ext/#identity-providers
.. _create_a_mapping:
Create a Mapping Create a Mapping
~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~
Next, create a mapping. A mapping is a set of rules that link the attributes of Next, create a mapping. A mapping is a set of rules that link the attributes of
a remote user to user properties that keystone understands. It is especially a remote user to user properties that keystone understands. It is especially
useful for granting remote users authorization to keystone resources, either by useful for granting remote users authorization to keystone resources, either by
associating them with a local keystone group and inheriting its role associating them with a local keystone group and inheriting its role
assignments, or dynamically provisioning projects within keystone based on these assignments, or dynamically provisioning projects within keystone based on these
rules. rules.
skipping to change at line 239 skipping to change at line 238
See also the `API reference for federation protocols`_. See also the `API reference for federation protocols`_.
.. _API reference for federation protocols: https://developer.openstack.org/api- ref/identity/v3-ext/#protocols .. _API reference for federation protocols: https://developer.openstack.org/api- ref/identity/v3-ext/#protocols
Configuring an HTTPD auth module Configuring an HTTPD auth module
-------------------------------- --------------------------------
This guide currently only includes examples for the Apache web server, but it This guide currently only includes examples for the Apache web server, but it
possible to use SAML, OpenIDC, and other auth modules in other web servers. See possible to use SAML, OpenIDC, and other auth modules in other web servers. See
the installation guides for running keystone behind Apache for `SUSE`_, the installation guides for running keystone behind Apache for
`RedHat`_ or `Ubuntu`_. :ref:`SUSE <suse_configure_apache>`, :ref:`RedHat
<redhat_configure_apache>` or :ref:`Ubuntu <ubuntu_configure_apache>`.
.. _`SUSE`: ../../install/keystone-install-obs.html#configure-the-apache-http-se
rver
.. _`RedHat`: ../../install/keystone-install-rdo.html#configure-the-apache-http-
server
.. _`Ubuntu`: ../../install/keystone-install-ubuntu.html#configure-the-apache-ht
tp-server
Configure protected endpoints Configure protected endpoints
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
There is a minimum of one endpoint that must be protected in the VirtualHost There is a minimum of one endpoint that must be protected in the VirtualHost
configuration for the keystone service: configuration for the keystone service:
.. code-block:: apache .. code-block:: apache
<Location /v3/OS-FEDERATION/identity_providers/IDENTITYPROVIDER/protocols/PRO TOCOL/auth> <Location /v3/OS-FEDERATION/identity_providers/IDENTITYPROVIDER/protocols/PRO TOCOL/auth>
skipping to change at line 336 skipping to change at line 332
use other auth modules such as kerberos, X.509, or others. Check the use other auth modules such as kerberos, X.509, or others. Check the
documentation for the provider you choose for detailed installation and documentation for the provider you choose for detailed installation and
configuration guidance. configuration guidance.
Depending on the Service Provider module you've chosen, you will need to install Depending on the Service Provider module you've chosen, you will need to install
the applicable Apache module package and follow additional configuration steps. the applicable Apache module package and follow additional configuration steps.
This guide contains examples for two major federation protocols: This guide contains examples for two major federation protocols:
* SAML2.0 - see guides for the following implementations: * SAML2.0 - see guides for the following implementations:
* `Set up mod_shib`_. * :ref:`Set up mod_shib <shibboleth>`.
* `Set up mod_auth_mellon`_. * :ref:`Set up mod_auth_mellon <mellon>`.
* OpenID Connect: `Set up mod_auth_openidc`_. * OpenID Connect: :ref:`Set up mod_auth_openidc <federation_openidc>`.
.. _`Set up mod_shib`: shibboleth.html .. _federation_configuring_keystone:
.. _`Set up mod_auth_openidc`: openidc.html
.. _`Set up mod_auth_mellon`: mellon.html
Configuring Keystone Configuring Keystone
-------------------- --------------------
While the Apache module does the majority of the heavy lifting, minor changes While the Apache module does the majority of the heavy lifting, minor changes
are needed to allow keystone to allow and understand federated authentication. are needed to allow keystone to allow and understand federated authentication.
Add the Auth Method Add the Auth Method
~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~
skipping to change at line 586 skipping to change at line 580
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
When horizon is configured to enable WebSSO, a dropdown menu will appear on the When horizon is configured to enable WebSSO, a dropdown menu will appear on the
login screen before the user has authenticated. Select an authentication method login screen before the user has authenticated. Select an authentication method
from the menu to be redirected to your Identity Provider for authentication. from the menu to be redirected to your Identity Provider for authentication.
.. image:: ../../_static/horizon-login-sp.png .. image:: ../../_static/horizon-login-sp.png
:height: 400px :height: 400px
:alt: Horizon login screen using external authentication :alt: Horizon login screen using external authentication
.. _keystone_as_idp:
-------------------------------------- --------------------------------------
Keystone as an Identity Provider (IdP) Keystone as an Identity Provider (IdP)
-------------------------------------- --------------------------------------
Prerequisites Prerequisites
------------- -------------
When keystone is configured as an Identity Provider, it is often referred to as When keystone is configured as an Identity Provider, it is often referred to as
`Keystone to Keystone`, because it enables federation between multiple OpenStack `Keystone to Keystone`, because it enables federation between multiple OpenStack
clouds using the SAML2.0 protocol. clouds using the SAML2.0 protocol.
If you are not familiar with the idea of federated identity, see the If you are not familiar with the idea of federated identity, see the
`introduction`_ first. :ref:`introduction <federation_introduction>` first.
When setting up `Keystone to Keystone`, it is easiest to `configure a keystone When setting up `Keystone to Keystone`, it is easiest to `configure a keystone
Service Provider`_ first with a sandbox Identity Provider such as Service Provider`_ first with a sandbox Identity Provider such as
`samltest.id`_. `samltest.id`_.
.. _configure a keystone Service Provider: :ref:`Keystone as a Service Provider (SP)` .. _configure a keystone Service Provider: :ref:`Keystone as a Service Provider (SP)`
.. _samltest.id: https://samltest.id .. _samltest.id: https://samltest.id
This feature requires installation of the xmlsec1 tool via your distribution This feature requires installation of the xmlsec1 tool via your distribution
packaging system (for instance apt or yum) packaging system (for instance apt or yum)
skipping to change at line 760 skipping to change at line 756
No additional configuration is necessary to enable horizon for No additional configuration is necessary to enable horizon for
Keystone to Keystone. Log into the horizon instance for the Identity Provider Keystone to Keystone. Log into the horizon instance for the Identity Provider
using your regular local keystone credentials. Once logged in, you will see a using your regular local keystone credentials. Once logged in, you will see a
Service Provider dropdown menu which you can use to switch your dashboard view Service Provider dropdown menu which you can use to switch your dashboard view
to another cloud. to another cloud.
.. image:: ../../_static/horizon-login-idp.png .. image:: ../../_static/horizon-login-idp.png
:height: 175px :height: 175px
:alt: Horizon dropdown menu for switching between keystone providers :alt: Horizon dropdown menu for switching between keystone providers
.. include:: openidc.rst .. include:: openidc.inc
.. include:: mellon.rst .. include:: mellon.inc
.. include:: shibboleth.rst .. include:: shibboleth.inc
 End of changes. 13 change blocks. 
31 lines changed or deleted 20 lines changed or added

Home  |  About  |  Features  |  All  |  Newest  |  Dox  |  Diffs  |  RSS Feeds  |  Screenshots  |  Comments  |  Imprint  |  Privacy  |  HTTP(S)