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
|
||||
-------------
|
||||
|
||||
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
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
@ -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 OpenID Connect, follow the steps outlined at: `Setup OpenID Connect`_.
|
||||
|
||||
.. _`Setup Shibboleth`: extensions/shibboleth.html
|
||||
.. _`Setup OpenID Connect`: extensions/openidc.html
|
||||
.. _`Setup Shibboleth`: federation/shibboleth.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,
|
||||
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
|
||||
configure the ``OS-FEDERATION`` extension.
|
||||
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``.
|
||||
.. code-block:: bash
|
||||
|
||||
1. Add local Keystone groups and roles
|
||||
2. Add Identity Provider(s), Mapping(s), and Protocol(s)
|
||||
[auth]
|
||||
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
|
||||
|
@ -117,14 +122,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
|
||||
|
@ -158,7 +163,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
|
||||
|
||||
|
@ -251,11 +256,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:
|
||||
|
@ -294,7 +310,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
|
||||
|
@ -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
|
||||
``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
|
||||
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.
|
||||
|
@ -329,8 +345,8 @@ Testing it all out
|
|||
------------------
|
||||
|
||||
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.
|
||||
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
|
||||
|
@ -349,7 +365,7 @@ specifically intended for the Service Provider Keystone.
|
|||
pure SAML Assertions.
|
||||
|
||||
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
|
||||
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>`__
|
||||
|
||||
----------
|
||||
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
|
||||
-------
|
||||
|
|
|
@ -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`_
|
||||
|
||||
.. _`Step 2`: federation.html
|
||||
.. _`Step 2`: federation/federation.html
|
Loading…
Reference in New Issue