OS-FEDERATION no longer extension in docs
Until now all the docs assumed the OS-FEDERATION is still an extension. Since this is not true since Kilo release, we should also update our documentation. We also moved some of the files from the ``extension`` directory to the ``federation`` one. Change-Id: I7f71fea55accaaaf38b2ee069fab9726c1045b4c Closes-Bug: #1466092
This commit is contained in:
parent
a70b514ed9
commit
8cb9548ad0
|
@ -34,24 +34,24 @@ Keystone as a Service Provider (SP)
|
||||||
Prerequisites
|
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
|
identity properties issued by an external Identity Provider, such as SAML
|
||||||
assertions or OpenID Connect claims.
|
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
|
(for example, using the SQL driver). The external Identity Provider is
|
||||||
responsible for authenticating users, and communicates the result of
|
responsible for authenticating users, and communicates the result of
|
||||||
authentication to Keystone using identity properties. Keystone maps these
|
authentication to keystone using identity properties. Keystone maps these
|
||||||
values to Keystone user groups and assignments created in Keystone.
|
values to keystone user groups and assignments created in keystone.
|
||||||
|
|
||||||
The following configuration steps were performed on a machine running
|
The following configuration steps were performed on a machine running
|
||||||
Ubuntu 12.04 and Apache 2.2.22.
|
Ubuntu 12.04 and Apache 2.2.22.
|
||||||
|
|
||||||
To enable federation, you'll need to:
|
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.
|
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
|
Configure Apache to use a federation capable authentication method
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
@ -62,34 +62,39 @@ Using Shibboleth and OpenID Connect are documented so far.
|
||||||
* To use Shibboleth, follow the steps outlined at: `Setup Shibboleth`_.
|
* To use Shibboleth, follow the steps outlined at: `Setup Shibboleth`_.
|
||||||
* To use OpenID Connect, follow the steps outlined at: `Setup OpenID Connect`_.
|
* To use OpenID Connect, follow the steps outlined at: `Setup OpenID Connect`_.
|
||||||
|
|
||||||
.. _`Setup Shibboleth`: extensions/shibboleth.html
|
.. _`Setup Shibboleth`: federation/shibboleth.html
|
||||||
.. _`Setup OpenID Connect`: extensions/openidc.html
|
.. _`Setup OpenID Connect`: federation/openidc.html
|
||||||
|
|
||||||
Configure Keystone and Horizon for Single Sign-On
|
Configure keystone and Horizon for Single Sign-On
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
* To configure horizon to access a federated keystone,
|
* To configure horizon to access a federated keystone,
|
||||||
follow the steps outlined at: `Keystone Federation and Horizon`_.
|
follow the steps outlined at: `Keystone Federation and Horizon`_.
|
||||||
|
|
||||||
.. _`Keystone Federation and Horizon`: extensions/websso.html
|
.. _`Keystone Federation and Horizon`: federation/websso.html
|
||||||
|
|
||||||
Enable the ``OS-FEDERATION`` extension
|
Configuring Federation in Keystone
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
-----------------------------------
|
||||||
|
|
||||||
Follow the steps outlined at: `Enabling Federation Extension`_.
|
Now that the Identity Provider and keystone are communicating we can start to
|
||||||
|
configure ``federation``.
|
||||||
|
|
||||||
.. _`Enabling Federation Extension`: extensions/federation.html
|
1. Configure authentication drivers in ``keystone.conf``
|
||||||
|
2. Add local keystone groups and roles
|
||||||
|
3. Add Identity Provider(s), Mapping(s), and Protocol(s)
|
||||||
|
|
||||||
Configuring Federation
|
Configure authentication drivers in ``keystone.conf``
|
||||||
----------------------
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
Now that the Identity Provider and Keystone are communicating we can start to
|
Add the authentication methods to the ``[auth]`` section in ``keystone.conf``.
|
||||||
configure the ``OS-FEDERATION`` extension.
|
Names should be equal to protocol names added via Identity API v3. Here we use
|
||||||
|
examples ``saml2`` and ``openid``.
|
||||||
|
.. code-block:: bash
|
||||||
|
|
||||||
1. Add local Keystone groups and roles
|
[auth]
|
||||||
2. Add Identity Provider(s), Mapping(s), and Protocol(s)
|
methods = external,password,token,saml2,openid
|
||||||
|
|
||||||
Create Keystone groups and assign roles
|
Create keystone groups and assign roles
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
As mentioned earlier, no new users will be added to the Identity backend, but
|
As mentioned earlier, no new users will be added to the Identity backend, but
|
||||||
|
@ -117,14 +122,14 @@ To utilize federation the following must be created in the Identity Service:
|
||||||
* Mapping
|
* Mapping
|
||||||
* Protocol
|
* 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>`__.
|
<http://specs.openstack.org/openstack/keystone-specs/api/v3/identity-api-v3-os-federation-ext.html>`__.
|
||||||
|
|
||||||
~~~~~~~~~~~~~~~~~
|
~~~~~~~~~~~~~~~~~
|
||||||
Identity Provider
|
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.
|
Provider we will use to authenticate end users.
|
||||||
|
|
||||||
More information on identity providers can be found `here
|
More information on identity providers can be found `here
|
||||||
|
@ -158,7 +163,7 @@ you want to use with the combination of the IdP and Protocol.
|
||||||
Performing federated authentication
|
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
|
2. Determine accessible resources
|
||||||
3. Get a scoped token
|
3. Get a scoped token
|
||||||
|
|
||||||
|
@ -251,11 +256,22 @@ Keystone as an Identity Provider (IdP)
|
||||||
that will not be backported). These issues have been fixed and this feature
|
that will not be backported). These issues have been fixed and this feature
|
||||||
is considered stable and supported as of the Kilo release.
|
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
|
Configuration Options
|
||||||
---------------------
|
---------------------
|
||||||
|
|
||||||
There are certain settings in ``keystone.conf`` that must be setup, prior to
|
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
|
Within ``keystone.conf``, assign values to the ``[saml]`` related fields, for
|
||||||
example:
|
example:
|
||||||
|
@ -294,7 +310,7 @@ Generate Metadata
|
||||||
-----------------
|
-----------------
|
||||||
|
|
||||||
In order to create a trust between the IdP and SP, metadata must be exchanged.
|
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:
|
and pipe the output to a file. For example:
|
||||||
|
|
||||||
.. code-block:: bash
|
.. code-block:: bash
|
||||||
|
@ -312,7 +328,7 @@ 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
|
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``
|
``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
|
. 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
|
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``
|
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
|
field is optional we are passing it set to ``true`` otherwise it will be set to
|
||||||
``false`` by default.
|
``false`` by default.
|
||||||
|
@ -329,8 +345,8 @@ Testing it all out
|
||||||
------------------
|
------------------
|
||||||
|
|
||||||
Lastly, if a scoped token and a Service Provider scope are presented to the
|
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,
|
local keystone, the result will be a full ECP wrapped SAML Assertion,
|
||||||
specifically intended for the Service Provider Keystone.
|
specifically intended for the Service Provider keystone.
|
||||||
|
|
||||||
.. NOTE::
|
.. NOTE::
|
||||||
ECP stands for Enhanced Client or Proxy, an extension from the SAML2
|
ECP stands for Enhanced Client or Proxy, an extension from the SAML2
|
||||||
|
@ -349,7 +365,7 @@ specifically intended for the Service Provider Keystone.
|
||||||
pure SAML Assertions.
|
pure SAML Assertions.
|
||||||
|
|
||||||
At this point the ECP wrapped SAML Assertion can be sent to the Service
|
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
|
Provider keystone using the provided ``auth_url`` in the ``X-Auth-Url`` header
|
||||||
present in the response containing the Assertion, and a valid OpenStack
|
present in the response containing the Assertion, and a valid OpenStack
|
||||||
token, issued by a Service Provider Keystone, will be returned.
|
token, issued by a Service Provider keystone, will be returned.
|
||||||
|
|
||||||
|
|
|
@ -86,26 +86,6 @@ a policy ID.
|
||||||
|
|
||||||
* `API Specification for Endpoint Policy <http://specs.openstack.org/openstack/keystone-specs/api/v3/identity-api-v3-os-endpoint-policy.html>`__
|
* `API Specification for Endpoint Policy <http://specs.openstack.org/openstack/keystone-specs/api/v3/identity-api-v3-os-endpoint-policy.html>`__
|
||||||
|
|
||||||
----------
|
|
||||||
Federation
|
|
||||||
----------
|
|
||||||
|
|
||||||
The Federation extension provides the ability for users to manage Identity
|
|
||||||
Providers (IdPs) and establish a set of rules to map federation protocol
|
|
||||||
attributes to Identity API attributes.
|
|
||||||
|
|
||||||
.. NOTE:: Support status for Federation
|
|
||||||
|
|
||||||
*Experimental* (Icehouse, Juno)
|
|
||||||
*Stable* (Kilo)
|
|
||||||
|
|
||||||
.. toctree::
|
|
||||||
:maxdepth: 1
|
|
||||||
|
|
||||||
extensions/federation.rst
|
|
||||||
|
|
||||||
* `API Specification for Federation <http://specs.openstack.org/openstack/keystone-specs/api/v3/identity-api-v3-os-federation-ext.html>`__
|
|
||||||
|
|
||||||
-------
|
-------
|
||||||
Inherit
|
Inherit
|
||||||
-------
|
-------
|
||||||
|
|
|
@ -1,64 +0,0 @@
|
||||||
..
|
|
||||||
Copyright 2014 OpenStack, Foundation
|
|
||||||
All Rights Reserved.
|
|
||||||
|
|
||||||
Licensed under the Apache License, Version 2.0 (the "License"); you may
|
|
||||||
not use this file except in compliance with the License. You may obtain
|
|
||||||
a copy of the License at
|
|
||||||
|
|
||||||
http://www.apache.org/licenses/LICENSE-2.0
|
|
||||||
|
|
||||||
Unless required by applicable law or agreed to in writing, software
|
|
||||||
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
|
|
||||||
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
|
|
||||||
License for the specific language governing permissions and limitations
|
|
||||||
under the License.
|
|
||||||
|
|
||||||
==================================
|
|
||||||
Enabling the Federation Extension
|
|
||||||
==================================
|
|
||||||
|
|
||||||
To enable the federation extension:
|
|
||||||
|
|
||||||
1. Add the federation extension driver to the ``[federation]`` section in
|
|
||||||
``keystone.conf``. For example::
|
|
||||||
|
|
||||||
[federation]
|
|
||||||
driver = keystone.contrib.federation.backends.sql.Federation
|
|
||||||
|
|
||||||
2. Add the ``saml2`` and/or ``oidc`` authentication methods to the ``[auth]``
|
|
||||||
section in ``keystone.conf``::
|
|
||||||
|
|
||||||
[auth]
|
|
||||||
methods = external,password,token,saml2,oidc
|
|
||||||
|
|
||||||
.. NOTE::
|
|
||||||
The ``external`` method should be dropped to avoid any interference with
|
|
||||||
some Apache + Shibboleth SP setups, where a ``REMOTE_USER`` env variable is
|
|
||||||
always set, even as an empty value.
|
|
||||||
|
|
||||||
3. Add the ``federation_extension`` middleware to the ``api_v3`` pipeline in
|
|
||||||
``keystone-paste.ini``. This must be added after ``json_body`` and before
|
|
||||||
the last entry in the pipeline. For example::
|
|
||||||
|
|
||||||
[pipeline:api_v3]
|
|
||||||
pipeline = sizelimit url_normalize build_auth_context token_auth admin_token_auth json_body ec2_extension_v3 s3_extension simple_cert_extension revoke_extension federation_extension service_v3
|
|
||||||
|
|
||||||
4. Create the federation extension tables if using the provided SQL backend.
|
|
||||||
For example::
|
|
||||||
|
|
||||||
./bin/keystone-manage db_sync --extension federation
|
|
||||||
|
|
||||||
5. As of the Juno release, multiple Keystone deployments can now be federated.
|
|
||||||
To do so, the `pysaml2 <https://pypi.python.org/pypi/pysaml2>`_ library is
|
|
||||||
required. Since OS-FEDERATION is an extension, ``pysaml2`` is not installed
|
|
||||||
by default, it must be installed manually. For example::
|
|
||||||
|
|
||||||
pip install --upgrade $(grep pysaml2 test-requirements.txt)
|
|
||||||
|
|
||||||
Also, the `xmlsec1` command line tool is needed to sign the SAML assertions
|
|
||||||
generated by the Keystone Identity Provider:
|
|
||||||
|
|
||||||
.. code-block:: bash
|
|
||||||
|
|
||||||
$ apt-get install xmlsec1
|
|
|
@ -91,4 +91,4 @@ Tips
|
||||||
|
|
||||||
2. Don't forget to add oidc as an [auth] plugin in keystone.conf, see `Step 2`_
|
2. Don't forget to add oidc as an [auth] plugin in keystone.conf, see `Step 2`_
|
||||||
|
|
||||||
.. _`Step 2`: federation.html
|
.. _`Step 2`: federation/federation.html
|
Loading…
Reference in New Issue