<commit_before>..
    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.

===================================
Configuring Keystone for Federation
===================================

Definitions
-----------

* `Service Provider (SP)`: provides a service to an end-user.
* `Identity Provider (IdP)`: service that stores information about users and
  groups.
* `SAML assertion`: contains information about a user as provided by an IdP.

Prerequisites
-------------

This approach to federation supports Keystone as a Service Provider, consuming
SAML assertions issued by an external Identity Provider.

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 SAML assertions. Keystone maps the SAML
assertions 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``.
2. Configure Apache to use a federation capable authentication method.
3. Enable ``OS-FEDERATION`` extension.

Configure Apache HTTPD for mod_shibboleth
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Follow the steps outlined at: `Running Keystone in HTTPD`_.

.. _`Running Keystone in HTTPD`: apache-httpd.html

You'll also need to install `Shibboleth <https://wiki.shibboleth.net/confluence/display/SHIB2/Home>`_, for
example:

.. code-block:: bash

    $ apt-get libapache2-mod-shib2

Configure your Keystone virtual host and adjust the config to properly handle SAML2 workflow:

Add *WSGIScriptAlias* directive to your vhost configuration::

    WSGIScriptAliasMatch ^(/v3/OS-FEDERATION/identity_providers/.*?/protocols/.*?/auth)$ /var/www/keystone/main/$1

Make sure you add two *<Location>* directives to the *wsgi-keystone.conf*::

    <Location /Shibboleth.sso>
        SetHandler shib
    </Location>

    <LocationMatch /v3/OS-FEDERATION/identity_providers/.*?/protocols/.*?/auth>
        ShibRequestSetting requireSession 1
        AuthType shibboleth
        ShibRequireSession On
        ShibRequireAll On
        ShibExportAssertion Off
        Require valid-user
    </LocationMatch>

Enable the Keystone virtual host, for example:

.. code-block:: bash

    $ a2ensite wsgi-keystone.conf

Enable the ``ssl`` and ``shib2`` modules, for example:<commit_msg>Invalid command referenced in federation documentation<commit_after>..
    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.

===================================
Configuring Keystone for Federation
===================================

Definitions
-----------

* `Service Provider (SP)`: provides a service to an end-user.
* `Identity Provider (IdP)`: service that stores information about users and
  groups.
* `SAML assertion`: contains information about a user as provided by an IdP.

Prerequisites
-------------

This approach to federation supports Keystone as a Service Provider, consuming
SAML assertions issued by an external Identity Provider.

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 SAML assertions. Keystone maps the SAML
assertions 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``.
2. Configure Apache to use a federation capable authentication method.
3. Enable ``OS-FEDERATION`` extension.

Configure Apache HTTPD for mod_shibboleth
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Follow the steps outlined at: `Running Keystone in HTTPD`_.

.. _`Running Keystone in HTTPD`: apache-httpd.html

You'll also need to install `Shibboleth <https://wiki.shibboleth.net/confluence/display/SHIB2/Home>`_, for
example:

.. code-block:: bash

    $ apt-get install libapache2-mod-shib2

Configure your Keystone virtual host and adjust the config to properly handle SAML2 workflow:

Add *WSGIScriptAlias* directive to your vhost configuration::

    WSGIScriptAliasMatch ^(/v3/OS-FEDERATION/identity_providers/.*?/protocols/.*?/auth)$ /var/www/keystone/main/$1

Make sure you add two *<Location>* directives to the *wsgi-keystone.conf*::

    <Location /Shibboleth.sso>
        SetHandler shib
    </Location>

    <LocationMatch /v3/OS-FEDERATION/identity_providers/.*?/protocols/.*?/auth>
        ShibRequestSetting requireSession 1
        AuthType shibboleth
        ShibRequireSession On
        ShibRequireAll On
        ShibExportAssertion Off
        Require valid-user
    </LocationMatch>

Enable the Keystone virtual host, for example:

.. code-block:: bash

    $ a2ensite wsgi-keystone.conf

Enable the ``ssl`` and ``shib2`` modules, for example:
{'fraction_non_alphanumeric': 0.11087489779231398, 'fraction_numerical': 0.008176614881439084, 'mean_word_length': 3.944219886822959, 'pattern_counts': {'":': 0, '<': 15, '<?xml version=': 0, '>': 15, 'https://': 2, 'lorem ipsum': 0, 'www.': 4, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2996953', 'n_tokens_mistral': 1751, 'n_tokens_neox': 1613, 'n_words': 677}