openstack
/
keystone
Code Issues Proposed changes

Merge "Update, correct, and enhance federation docs"

This commit is contained in:
Jenkins 2016-10-15 12:36:54 +00:00 committed by Gerrit Code Review
parent 63f5ad373c 38f79a8edf
commit 8e07232006
3 changed files with 398 additions and 277 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

279
doc/source/federation/configure_federation.rst
View File

@ -35,7 +35,8 @@ 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, or by using
`Keystone as an Identity Provider (IdP)`_.
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
@ -44,13 +45,15 @@ 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 14.04 and Apache 2.4.7.
To enable federation, you'll need to: To enable federation, you'll need to:
1. Run keystone under Apache, rather than using uwsgi command. 1. `Run keystone under Apache`_, rather than using uwsgi command.
2. Configure Apache to use a federation capable authentication method. 2. `Configure Apache to use a federation capable authentication method`_.
3. Configure ``federation`` in keystone. 3. `Configure Federation in Keystone`_.
.. _`Run keystone under Apache`: ../apache-httpd.html
Configure Apache to use a federation capable authentication method Configure Apache to use a federation capable authentication method
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -76,18 +79,18 @@ Configure keystone and Horizon for Single Sign-On
.. _`Keystone Federation and Horizon`: websso.html .. _`Keystone Federation and Horizon`: websso.html
Configuring Federation in Keystone Configure Federation in Keystone
---------------------------------- --------------------------------
Now that the Identity Provider and keystone are communicating we can start to Now that the Identity Provider and keystone are communicating we can start to
configure ``federation``. configure ``federation``.
1. Configure authentication drivers in ``keystone.conf`` 1. `Configure authentication drivers in keystone.conf`_
2. Add local keystone groups and roles 2. `Create keystone groups and assign roles`_
3. Add Identity Provider(s), Mapping(s), and Protocol(s) 3. `Add Identity Provider(s), Mapping(s), and Protocol(s)`_
Configure authentication drivers in ``keystone.conf`` Configure authentication drivers in keystone.conf
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. NOTE:: .. NOTE::
``saml2`` has been deprecated as of the Mitaka release. Support for the ``saml2`` has been deprecated as of the Mitaka release. Support for the
@ -122,14 +125,37 @@ and `role assignments
both of which are exposed to the CLI via `python-openstackclient both of which are exposed to the CLI via `python-openstackclient
<https://pypi.python.org/pypi/python-openstackclient/>`_. <https://pypi.python.org/pypi/python-openstackclient/>`_.
For example, create a new domain and project like this:
.. code-block:: bash
$ openstack domain create federated_domain
$ openstack project create federated_project --domain federated_domain
And a new group like this:
.. code-block:: bash
$ openstack group create federated_users
Add the group to the domain and project:
.. code-block:: bash
$ openstack role add --group federated_users --domain federated_domain Member
$ openstack role add --group federated_users --project federated_project Member
We'll later add a mapping that makes all federated users a part of this group
and therefore members of the new domain.
Add Identity Provider(s), Mapping(s), and Protocol(s) Add Identity Provider(s), Mapping(s), and Protocol(s)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To utilize federation the following must be created in the Identity Service: To utilize federation the following must be created in the Identity Service:
* Identity Provider * `Identity Provider`_
* Mapping * `Mapping`_
* Protocol * `Protocol`_
Read more about `federation in keystone Read more about `federation in keystone
<http://developer.openstack.org/api-ref/identity/v3-ext/#os-federation-api>`__. <http://developer.openstack.org/api-ref/identity/v3-ext/#os-federation-api>`__.
@ -139,7 +165,46 @@ 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:
.. code-block:: bash
$ openstack identity provider create --remote-id https://myidp.example.com/v3/OS-FEDERATION/saml2/idp myidp
The value for the ``remote-id`` option is the Entity ID provided by the IdP. It
is the same value that you set for the SSO entityID in /etc/shibboleth/shibboleth2.xml.
If the IdP is a Keystone IdP, it is the value set in that Keystone's
``[saml]/idp_entity_id`` option. It will usually appear as a URI but there
is no requirement for it to resolve to anything and may be arbitrarily decided
by the administrator of the IdP. The local name, here called 'myidp', is
decided by you and will be used by the mapping and protocol, and later for
authentication.
A keystone identity provider may have multiple `remote_ids` specified, this
allows the same *keystone* identity provider resource to be used with multiple
external identity providers. For example, an identity provider resource
``university-idp``, may have the following `remote_ids`:
``['university-x', 'university-y', 'university-z']``.
This removes the need to configure N identity providers in keystone.
.. NOTE::
Remote IDs are globally unique. Two identity providers cannot be
associated with the same remote ID. Once authenticated with the external
identity provider, keystone will determine which identity provider
and mapping to use based on the protocol and the value returned from the
`remote_id_attribute` key.
For example, if our identity provider is ``google``, the mapping used is
``google_mapping`` and the protocol is ``oidc``. The identity provider's
remote IDs would be: [``accounts.google.com``].
The `remote_id_attribute` value may be set to ``HTTP_OIDC_ISS``, since
this value will always be ``accounts.google.com``.
The motivation for this approach is that there will always be some data
sent by the identity provider (in the assertion or claim) that uniquely
identifies the identity provider. This removes the requirement for horizon
to list all the identity providers that are trusted by keystone.
Read more about `identity providers Read more about `identity providers
<http://developer.openstack.org/api-ref/identity/v3-ext/#identity-providers>`__. <http://developer.openstack.org/api-ref/identity/v3-ext/#identity-providers>`__.
@ -157,6 +222,71 @@ rules can be found on the :doc:`mapping_combinations` page.
An Identity Provider has exactly one mapping specified per protocol. 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. Mapping objects can be used multiple times by different combinations of Identity Provider and Protocol.
As a simple example, if keystone is your IdP, you can map a few known remote
users to the group you already created:
.. code-block:: bash
$ cat > rules.json <<EOF
[
{
"local": [
{
"user": {
"name": "{0}"
},
"group": {
"domain": {
"name": "Default"
},
"name": "federated_users"
}
}
],
"remote": [
{
"type": "openstack_user",
"any_one_of": [
"demo",
"alt_demo"
]
}
]
}
]
EOF
$ openstack mapping create --rules rules.json myidp_mapping
As another example, if Shibboleth is your IdP, the remote section should use REMOTE_USER as the remote type:
.. code-block:: bash
$ cat > rules.json <<EOF
[
{
"local": [
{
"user": {
"name": "{0}"
},
"group": {
"domain": {
"name": "Default"
},
"name": "federated_users"
}
}
],
"remote": [
{
"type": "REMOTE_USER"
}
]
}
]
EOF
$ openstack mapping create --rules rules.json myidp_mapping
Read more about `mapping Read more about `mapping
<http://developer.openstack.org/api-ref/identity/v3-ext/#mappings>`__. <http://developer.openstack.org/api-ref/identity/v3-ext/#mappings>`__.
@ -167,13 +297,27 @@ Protocol
A protocol contains information that dictates which Mapping rules to use for an incoming A protocol contains information that dictates which Mapping rules to use for an incoming
request made by an IdP. An IdP may have multiple supported protocols. request made by an IdP. An IdP may have multiple supported protocols.
Add `Protocol object You can create a protocol like this:
<http://developer.openstack.org/api-ref/identity/v3-ext/#protocols>`__ and specify the mapping id
you want to use with the combination of the IdP and Protocol. .. code-block:: bash
$ openstack federation protocol create mapped --mapping myidp_mapping --identity-provider myidp
The name you give the protocol is not arbitrary. It must match the method name
you gave in the ``[auth]/methods`` config option. When authenticating it will be
referred to as the ``protocol_id``.
Read more about `federation protocols
<http://developer.openstack.org/api-ref/identity/v3-ext/#protocols>`__
Performing federated authentication Performing federated authentication
----------------------------------- -----------------------------------
.. NOTE::
Authentication with keystone-to-keystone federation does not follow these steps.
See `Testing it all out`_ to authenticate with keystone-to-keystone.
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
@ -192,7 +336,8 @@ In this instance we follow a standard SAML2 authentication procedure, that is,
the user will be redirected to the Identity Provider's authentication webpage the user will be redirected to the Identity Provider's authentication webpage
and be prompted for credentials. After successfully authenticating the user and be prompted for credentials. After successfully authenticating the user
will be redirected to the Service Provider's endpoint. If using a web browser, will be redirected to the Service Provider's endpoint. If using a web browser,
a token will be returned in XML format. a token will be returned in JSON format, with the ID in the X-Subject-Token
header.
In the returned unscoped token, a list of Identity Service groups the user In the returned unscoped token, a list of Identity Service groups the user
belongs to will be included. belongs to will be included.
@ -255,7 +400,7 @@ Example cURL
.. code-block:: bash .. code-block:: bash
$ curl -X POST -H "Content-Type: application/json" -d '{"auth":{"identity":{"methods":["mapped"],"saml2":{"id":"<unscoped_token_id>"}},"scope":{"project":{"domain": {"name": "Default"},"name":"service"}}}}' -D - http://localhost:5000/v3/auth/tokens $ curl -X POST -H "Content-Type: application/json" -d '{"auth":{"identity":{"methods":["mapped"],"mapped":{"id":"<unscoped_token_id>"}},"scope":{"project":{"domain": {"name": "federated_domain"},"name":"federated_project"}}}}' -D - http://localhost:5000/v3/auth/tokens
-------------------------------------- --------------------------------------
Keystone as an Identity Provider (IdP) Keystone as an Identity Provider (IdP)
@ -290,10 +435,21 @@ example:
.. code-block:: ini .. code-block:: ini
[saml] [saml]
certfile=/etc/keystone/ssl/certs/ca.pem idp_entity_id=https://myidp.example.com/v3/OS-FEDERATION/saml2/idp
keyfile=/etc/keystone/ssl/private/cakey.pem idp_sso_endpoint=https://myidp.example.com/v3/OS-FEDERATION/saml2/sso
idp_entity_id=https://keystone.example.com/v3/OS-FEDERATION/saml2/idp
idp_sso_endpoint=https://keystone.example.com/v3/OS-FEDERATION/saml2/sso ``idp_entity_id`` is the unique identifier for the Identity Provider. It
usually takes the form of a URI but it does not have to resolve to anything.
``idp_sso_endpoint`` is required to generate valid metadata but its value is
not important, though it may be in the future.
Note the ``certfile``, ``keyfile``, and ``idp_metadata_path`` settings and adjust them if
necessary:
.. code-block:: ini
certfile=/etc/keystone/ssl/certs/signing_cert.pem
keyfile=/etc/keystone/ssl/private/signing_key.pem
idp_metadata_path=/etc/keystone/saml2_idp_metadata.xml idp_metadata_path=/etc/keystone/saml2_idp_metadata.xml
Though not necessary, the follow Organization configuration options should Though not necessary, the follow Organization configuration options should
@ -314,15 +470,26 @@ it's advisable to set these values too.
idp_contact_name=John idp_contact_name=John
idp_contact_surname=Smith idp_contact_surname=Smith
idp_contact_email=jsmith@example.com idp_contact_email=jsmith@example.com
idp_contact_telephone=555-55-5555 idp_contact_telephone=555-555-5555
idp_contact_type=technical idp_contact_type=technical
Generate Metadata 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.
First, if you haven't already generated a PKI key pair, you need to do so and
copy those files the locations designated by ``certfile`` and ``keyfile``
options that were assigned in the previous section. Ensure that your apache
vhost has SSL enabled and is using that keypair by adding the following to the
vhost::
SSLEngine on
SSLCertificateFile /etc/keystone/ssl/certs/signing_cert.pem
SSLCertificateKeyFile /etc/keystone/ssl/private/signing_key.pem
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 redirect the output to a file. For example:
.. code-block:: bash .. code-block:: bash
@ -332,50 +499,50 @@ and pipe the output to a file. For example:
The file location should match the value of the configuration option The file location should match the value of the configuration option
``idp_metadata_path`` that was assigned in the previous section. ``idp_metadata_path`` that was assigned in the previous section.
Finally, restart apache.
Create a Service Provider (SP) Create a Service Provider (SP)
------------------------------ ------------------------------
In this example we are creating a new Service Provider with an ID of ``BETA``, In this example we are creating a new Service Provider with an ID of ``mysp``,
a ``sp_url`` of ``http://beta.example.com/Shibboleth.sso/SAML2/ECP`` and a a ``sp_url`` of ``http://mysp.example.com/Shibboleth.sso/SAML2/ECP`` and a
``auth_url`` of ``http://beta.example.com:5000/v3/OS-FEDERATION/identity_providers/beta/protocols/saml2/auth`` ``auth_url`` of ``http://mysp.example.com:5000/v3/OS-FEDERATION/identity_providers/myidp/protocols/mapped/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 ``mysp`` 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 ``mysp`` once the SAML assertion is sent. The auth_url has the format
field is optional we are passing it set to ``true`` otherwise it will be set to described in `Get an unscoped token`_.
``false`` by default.
.. code-block:: bash .. code-block:: bash
$ curl -s -X PUT \ $ openstack service provider create --service-provider-url 'http://mysp.example.com/Shibboleth.sso/SAML2/ECP' --auth-url http://mysp.example.com:5000/v3/OS-FEDERATION/identity_providers/myidp/protocols/mapped/auth mysp
-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", "enabled": true}}' \
http://localhost:5000/v3/OS-FEDERATION/service_providers/BETA | python -mjson.tool
Testing it all out Testing it all out
------------------ ------------------
Lastly, if a scoped token and a Service Provider scope are presented to the Use keystoneauth to create a password session with the IdP, then use the
local keystone, the result will be a full ECP wrapped SAML Assertion, session to authenticate with the SP, and get a scoped token from the SP.
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
protocol used in non-browser interfaces, like in the following example protocol used in non-browser interfaces, like in the following example.
with cURL.
.. code-block:: bash .. code-block:: python
$ curl -s -X POST \ import os
-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/ecp
.. NOTE:: from keystoneauth1 import session
Use URL http://localhost:5000/v3/auth/OS-FEDERATION/saml2 to request for from keystoneauth1.identity import v3
pure SAML Assertions. from keystoneauth1.identity.v3 import k2k
At this point the ECP wrapped SAML Assertion can be sent to the Service auth = v3.Password(auth_url=os.environ.get('OS_AUTH_URL'),
Provider keystone using the provided ``auth_url`` in the ``X-Auth-Url`` header username=os.environ.get('OS_USERNAME'),
present in the response containing the Assertion, and a valid OpenStack password=os.environ.get('OS_PASSWORD'),
token, issued by a Service Provider keystone, will be returned. user_domain_name=os.environ.get('OS_USER_DOMAIN_NAME'),
project_name=os.environ.get('OS_PROJECT_NAME'),
project_domain_name=os.environ.get('OS_PROJECT_DOMAIN_NAME'))
password_session = session.Session(auth=auth)
k2ksession = k2k.Keystone2Keystone(password_session.auth, 'mysp',
domain_name='federated_domain')
auth_ref = k2ksession.get_auth_ref(password_session)
scoped_token_id = auth_ref.auth_token
print('Scoped token id: %s' % scoped_token_id)

297
doc/source/federation/shibboleth.rst
View File

@ -35,16 +35,15 @@ Add *WSGIScriptAlias* directive to your vhost configuration::
WSGIScriptAliasMatch ^(/v3/OS-FEDERATION/identity_providers/.*?/protocols/.*?/auth)$ /var/www/keystone/main/$1 WSGIScriptAliasMatch ^(/v3/OS-FEDERATION/identity_providers/.*?/protocols/.*?/auth)$ /var/www/keystone/main/$1
Make sure the *wsgi-keystone.conf* contains a *<Location>* directive for the Shibboleth module and Make sure the *keystone.conf* vhost file contains a *<Location>* directive for the Shibboleth module and
a *<Location>* directive for each identity provider:: a *<Location>* directive for each identity provider::
<Location /Shibboleth.sso> <Location /Shibboleth.sso>
SetHandler shib SetHandler shib
</Location> </Location>
<Location /v3/OS-FEDERATION/identity_providers/idp_1/protocols/saml2/auth> <Location /v3/OS-FEDERATION/identity_providers/myidp/protocols/mapped/auth>
ShibRequestSetting requireSession 1 ShibRequestSetting requireSession 1
ShibRequestSetting applicationId idp_1
AuthType shibboleth AuthType shibboleth
ShibExportAssertion Off ShibExportAssertion Off
Require valid-user Require valid-user
@ -56,28 +55,18 @@ a *<Location>* directive for each identity provider::
</Location> </Location>
.. NOTE:: .. NOTE::
* ``saml2`` may be different in your deployment, but do not use a wildcard value. * ``mapped`` is the name of the `protocol that you will configure <configure_federation.html#protocol>`_
Otherwise *every* federated protocol will be handled by Shibboleth. * ``myidp`` is the name associated with the `IdP in Keystone <configure_federation.html#identity_provider>`_
* ``idp_1`` has to be replaced with the name associated with the idp in Keystone.
The same name is used inside the shibboleth2.xml configuration file but they could
be different.
* The ``ShibRequireSession`` and ``ShibRequireAll`` rules are invalid in * The ``ShibRequireSession`` and ``ShibRequireAll`` rules are invalid in
Apache 2.4+. Apache 2.4+.
* You are advised to carefully examine `Shibboleth Apache configuration * You are advised to carefully examine `Shibboleth Apache configuration
documentation documentation
<https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPApacheConfig>`_ <https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPApacheConfig>`_
Enable the Keystone virtual host, for example: Enable the ``shib2`` module, for example:
.. code-block:: bash .. code-block:: bash
$ a2ensite wsgi-keystone.conf
Enable the ``ssl`` and ``shib2`` modules, for example:
.. code-block:: bash
$ a2enmod ssl
$ a2enmod shib2 $ a2enmod shib2
Restart Apache, for example: Restart Apache, for example:
@ -93,185 +82,192 @@ Configuring shibboleth2.xml
Once you have your Keystone vhost (virtual host) ready, it's then time to Once you have your Keystone vhost (virtual host) ready, it's then time to
configure Shibboleth and upload your Metadata to the Identity Provider. configure Shibboleth and upload your Metadata to the Identity Provider.
If new certificates are required, they can be easily created by executing: Create a new keypair for Shibboleth with:
.. code-block:: bash .. code-block:: bash
$ shib-keygen -y <number of years> $ shib-keygen -y <number of years>
The newly created file will be stored under ``/etc/shibboleth/sp-key.pem`` The newly created key file will be stored under ``/etc/shibboleth/sp-key.pem``.
You should fetch your Service Provider's Metadata file. Typically this can be
achieved by simply fetching a Metadata file, for example:
.. code-block:: bash
$ wget --no-check-certificate -O <name of the file> https://service.example.org/Shibboleth.sso/Metadata
Upload your Service Provider's Metadata file to your Identity Provider.
This step depends on your Identity Provider choice and is not covered here.
Configure your Service Provider by editing ``/etc/shibboleth/shibboleth2.xml`` Configure your Service Provider by editing ``/etc/shibboleth/shibboleth2.xml``
file. You are advised to examine `Shibboleth Service Provider Configuration documentation <https://wiki.shibboleth.net/confluence/display/SHIB2/Configuration>`_ file. You will want to change five settings:
An example of your ``/etc/shibboleth/shibboleth2.xml`` may look like * Set the SP entity ID. This value usually has the form of a URI but it does not
(The example shown below is for reference only, not to be used in a production have to resolve to anything. It must uniquely identify your Service Provider
environment): to your Identity Provider.
.. code-block:: xml .. code-block:: xml
<!-- <ApplicationDefaults entityID="http://mysp.example.com/shibboleth">
File configuration courtesy of http://testshib.org
More information: * Set the IdP entity ID. This value is determined by the IdP. For example, if
https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPConfiguration Keystone is the IdP:
-->
.. code-block:: xml
<SSO entityID="https://myidp.example.com/v3/OS-FEDERATION/saml2/idp">
Example if testshib.org is the IdP:
.. code-block:: xml
<SSO entityID="https://idp.testshib.org/idp/shibboleth">
* Remove the discoveryURL lines unless you want to enable advanced IdP discovery.
* Add a MetadataProvider block. The URI given here is a real URL that Shibboleth
will use to fetch metadata from the IdP. For example, if Keystone is the IdP:
.. code-block:: xml
<MetadataProvider type="XML" uri="https://myidp.example.com:5000/v3/OS-FEDERATION/saml2/metadata"/>
Example if testshib.org is the IdP:
.. code-block:: xml
<MetadataProvider type="XML" uri="http://www.testshib.org/metadata/testshib-providers.xml" />
You are advised to examine `Shibboleth Service Provider Configuration documentation <https://wiki.shibboleth.net/confluence/display/SHIB2/Configuration>`_
The result should look like (The example shown below is for reference only, not
to be used in a production environment):
.. code-block:: xml
<SPConfig xmlns="urn:mace:shibboleth:2.0:native:sp:config" <SPConfig xmlns="urn:mace:shibboleth:2.0:native:sp:config"
xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" clockSkew="1800 "> xmlns:conf="urn:mace:shibboleth:2.0:native:sp:config"
xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"
clockSkew="180">
<!-- The entityID is the name TestShib made for your SP. --> <!--
<ApplicationDefaults entityID="https://<yourhosthere>/shibboleth"> By default, in-memory StorageService, ReplayCache, ArtifactMap, and SessionCache
are used. See example-shibboleth2.xml for samples of explicitly configuring them.
-->
<!--
To customize behavior for specific resources on Apache, and to link vhosts or
resources to ApplicationOverride settings below, use web server options/commands.
See https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPConfigurationElements for help.
For examples with the RequestMap XML syntax instead, see the example-shibboleth2.xml
file, and the https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPRequestMapHowTo topic.
-->
<!-- The ApplicationDefaults element is where most of Shibboleth's SAML bits are defined. -->
<ApplicationDefaults entityID="https://mysp.example.com/shibboleth">
<!-- <!--
You should use secure cookies if at all possible. Controls session lifetimes, address checks, cookie handling, and the protocol handlers.
See cookieProps in this Wiki article. You MUST supply an effectively unique handlerURL value for each of your applications.
The value defaults to /Shibboleth.sso, and should be a relative path, with the SP computing
a relative value based on the virtual host. Using handlerSSL="true", the default, will force
the protocol to be https. You should also set cookieProps to "https" for SSL-only sites.
Note that while we default checkAddress to "false", this has a negative impact on the
security of your site. Stealing sessions via cookie theft is much easier with this disabled.
--> -->
<!-- https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPSessions --> <Sessions lifetime="28800" timeout="3600" relayState="ss:mem"
<Sessions lifetime="28800" timeout="3600" checkAddress="false" checkAddress="false" handlerSSL="false" cookieProps="http">
relayState="ss:mem" handlerSSL="false">
<!-- Triggers a login request directly to the TestShib IdP. --> <!--
<!-- https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPServiceSSO --> Configures SSO for a default IdP. To allow for >1 IdP, remove
<SSO entityID="https://<idp-url>/idp/shibboleth" ECP="true"> entityID property and adjust discoveryURL to point to discovery service.
SAML2 SAML1 (Set discoveryProtocol to "WAYF" for legacy Shibboleth WAYF support.)
You can also override entityID on /Login query string, or in RequestMap/htaccess.
-->
<SSO entityID="https://myidp.example.com/v3/OS-FEDERATION/saml2/idp">
SAML2 SAML1
</SSO> </SSO>
<!-- SAML and local-only logout. --> <!-- SAML and local-only logout. -->
<!-- https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPServiceLogout -->
<Logout>SAML2 Local</Logout> <Logout>SAML2 Local</Logout>
<!-- <!-- Extension service that generates "approximate" metadata based on SP configuration. -->
Handlers allow you to interact with the SP and gather <Handler type="MetadataGenerator" Location="/Metadata" signing="false"/>
more information. Try them out!
Attribute value s received by the SP through SAML
will be visible at:
http://<yourhosthere>/Shibboleth.sso/Session
-->
<!--
Extension service that generates "approximate" metadata
based on SP configuration.
-->
<Handler type="MetadataGenerator" Location="/Metadata"
signing="false"/>
<!-- Status reporting service. --> <!-- Status reporting service. -->
<Handler type="Status" Location="/Status" <Handler type="Status" Location="/Status" acl="127.0.0.1 ::1"/>
acl="127.0.0.1"/>
<!-- Session diagnostic service. --> <!-- Session diagnostic service. -->
<Handler type="Session" Location="/Session" <Handler type="Session" Location="/Session" showAttributeValues="false"/>
showAttributeValues="true"/>
<!-- JSON feed of discovery information. --> <!-- JSON feed of discovery information. -->
<Handler type="DiscoveryFeed" Location="/DiscoFeed"/> <Handler type="DiscoveryFeed" Location="/DiscoFeed"/>
</Sessions> </Sessions>
<!-- <!--
Error pages to display to yourself if Allows overriding of error template information/filenames. You can
something goes horribly wrong. also add attributes with values that can be plugged into the templates.
--> -->
<Errors supportContact ="<admin_email_address>" <Errors supportContact="root@localhost"
logoLocation="/shibboleth-sp/logo.jpg" helpLocation="/about.html"
styleSheet="/shibboleth-sp/main.css"/> styleSheet="/shibboleth-sp/main.css"/>
<!-- Example of remotely supplied batch of signed metadata. -->
<!-- <!--
Loads and trusts a metadata file that describes only one IdP <MetadataProvider type="XML" uri="http://federation.org/federation-metadata.xml"
and how to communicate with it. backingFilePath="federation-metadata.xml" reloadInterval="7200">
<MetadataFilter type="RequireValidUntil" maxValidityInterval="2419200"/>
<MetadataFilter type="Signature" certificate="fedsigner.pem"/>
</MetadataProvider>
--> -->
<MetadataProvider type="XML" uri="<idp-metadata-file>"
backingFilePath="<local idp metadata>"
reloadInterval="180000" />
<!-- Attribute and trust options you shouldn't need to change. --> <!-- Example of locally maintained metadata. -->
<AttributeExtractor type="XML" validate="true" <!--
path="attribute-map.xml"/> <MetadataProvider type="XML" file="partner-metadata.xml"/>
-->
<MetadataProvider type="XML" uri="https://myidp.example.com:5000/v3/OS-FEDERATION/saml2/metadata"/>
<!-- Map to extract attributes from SAML assertions. -->
<AttributeExtractor type="XML" validate="true" reloadChanges="false" path="attribute-map.xml"/>
<!-- Use a SAML query if no attributes are supplied during SSO. -->
<AttributeResolver type="Query" subjectMatch="true"/> <AttributeResolver type="Query" subjectMatch="true"/>
<AttributeFilter type="XML" validate="true"
path="attribute-policy.xml"/> <!-- Default filtering policy for recognized attributes, lets other data pass. -->
<AttributeFilter type="XML" validate="true" path="attribute-policy.xml"/>
<!-- Simple file-based resolver for using a single keypair. -->
<CredentialResolver type="File" key="sp-key.pem" certificate="sp-cert.pem"/>
<!-- <!--
Your SP generated these credentials. The default settings can be overridden by creating ApplicationOverride elements (see
They're used to talk to IdP's. the https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPApplicationOverride topic).
Resource requests are mapped by web server commands, or the RequestMapper, to an
applicationId setting.
Example of a second application (for a second vhost) that has a different entityID.
Resources on the vhost would map to an applicationId of "admin":
-->
<!--
<ApplicationOverride id="admin" entityID="https://admin.example.org/shibboleth"/>
--> -->
<CredentialResolver type="File" key="sp-key.pem"
certificate="sp-cert.pem"/>
<ApplicationOverride id="idp_1" entityID="https://<yourhosthere>/shibboleth">
<Sessions lifetime="28800" timeout="3600" checkAddress="false"
relayState="ss:mem" handlerSSL="false">
<!-- Triggers a login request directly to the TestShib IdP. -->
<SSO entityID="https://<idp_1-url>/idp/shibboleth" ECP="true">
SAML2 SAML1
</SSO>
<Logout>SAML2 Local</Logout>
</Sessions>
<MetadataProvider type="XML" uri="<idp_1-metadata-file>"
backingFilePath="<local idp_1 metadata>"
reloadInterval="180000" />
</ApplicationOverride>
<ApplicationOverride id="idp_2" entityID="https://<yourhosthere>/shibboleth">
<Sessions lifetime="28800" timeout="3600" checkAddress="false"
relayState="ss:mem" handlerSSL="false">
<!-- Triggers a login request directly to the TestShib IdP. -->
<SSO entityID="https://<idp_2-url>/idp/shibboleth" ECP="true">
SAML2 SAML1
</SSO>
<Logout>SAML2 Local</Logout>
</Sessions>
<MetadataProvider type="XML" uri="<idp_2-metadata-file>"
backingFilePath="<local idp_2 metadata>"
reloadInterval="180000" />
</ApplicationOverride>
</ApplicationDefaults> </ApplicationDefaults>
<!-- <!-- Policies that determine how to process and authenticate runtime messages. -->
Security policies you shouldn't change unless you <SecurityPolicyProvider type="XML" validate="true" path="security-policy.xml"/>
know what you're doing.
-->
<SecurityPolicyProvider type="XML" validate="true"
path="security-policy.xml"/>
<!-- <!-- Low-level configuration about protocols and bindings available for use. -->
Low-level configuration about protocols and bindings <ProtocolProvider type="XML" validate="true" reloadChanges="false" path="protocols.xml"/>
available for use.
-->
<ProtocolProvider type="XML" validate="true" reloadChanges="false"
path="protocols.xml"/>
</SPConfig> </SPConfig>
Keystone enforces `external authentication`_ when the ``REMOTE_USER`` If keystone is your IdP, you will need to examine your attributes map file
environment variable is present so make sure Shibboleth doesn't set the ``/etc/shibboleth/attribute-map.xml`` and add the following attributes:
``REMOTE_USER`` environment variable. To do so, scan through the
``/etc/shibboleth/shibboleth2.xml`` configuration file and remove the
``REMOTE_USER`` directives.
Examine your attributes map file ``/etc/shibboleth/attribute-map.xml`` and adjust .. code-block:: xml
your requirements if needed. For more information see
<Attribute name="openstack_user" id="openstack_user"/>
<Attribute name="openstack_roles" id="openstack_roles"/>
<Attribute name="openstack_project" id="openstack_project"/>
<Attribute name="openstack_user_domain" id="openstack_user_domain"/>
<Attribute name="openstack_project_domain" id="openstack_project_domain"/>
For more information see the
`attributes documentation <https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPAddAttribute>`_ `attributes documentation <https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPAddAttribute>`_
Once you are done, restart your Shibboleth daemon: Once you are done, restart your Shibboleth daemon and apache:
.. _`external authentication`: ../external-auth.html .. _`external authentication`: ../external-auth.html
@ -279,3 +275,16 @@ Once you are done, restart your Shibboleth daemon:
$ service shibd restart $ service shibd restart
$ service apache2 restart $ service apache2 restart
Check ``/var/log/shibboleth/shibd_warn.log`` for any ERROR or CRIT notices and
correct them.
Upload your Service Provider's metadata file to your Identity Provider. You can
fetch it with:
.. code-block:: bash
$ wget http://mysp.example.com/Shibboleth.sso/Metadata
This step depends on your Identity Provider choice and is not covered here.
If keystone is your Identity Provider you do not need to upload this file.

99
doc/source/federation/websso.rst
View File

@ -53,15 +53,16 @@ If `mod_shib` is used, then use the following as an example:
... ...
<Location ~ "/v3/auth/OS-FEDERATION/websso/saml2"> <Location ~ "/v3/auth/OS-FEDERATION/websso/mapped">
AuthType shibboleth AuthType shibboleth
Require valid-user Require valid-user
... ShibRequestSetting requireSession 1
ShibRequireSession On
ShibExportAssertion Off
</Location> </Location>
<Location ~ "/v3/auth/OS-FEDERATION/identity_providers/idp_1/protocols/saml2/websso"> <Location ~ "/v3/auth/OS-FEDERATION/identity_providers/myidp/protocols/mapped/websso">
AuthType shibboleth AuthType shibboleth
Require valid-user Require valid-user
...
</Location> </Location>
</VirtualHost> </VirtualHost>
@ -72,7 +73,7 @@ If `mod_auth_openidc` is used, then use the following as an example:
<VirtualHost *:5000> <VirtualHost *:5000>
OIDCRedirectURI http://localhost:5000/v3/auth/OS-FEDERATION/websso/redirect OIDCRedirectURI http://localhost:5000/v3/auth/OS-FEDERATION/websso/redirect
OIDCRedirectURI http://localhost:5000/v3/auth/OS-FEDERATION/identity_providers/idp_1/protocol/oidc/websso/redirect OIDCRedirectURI http://localhost:5000/v3/auth/OS-FEDERATION/identity_providers/myidp/protocol/oidc/websso/redirect
... ...
@ -81,7 +82,7 @@ If `mod_auth_openidc` is used, then use the following as an example:
Require valid-user Require valid-user
... ...
</Location> </Location>
<Location ~ "/v3/auth/OS-FEDERATION/identity_providers/idp_1/protocols/oidc/websso"> <Location ~ "/v3/auth/OS-FEDERATION/identity_providers/myidp/protocols/oidc/websso">
AuthType openid-connect AuthType openid-connect
Require valid-user Require valid-user
... ...
@ -104,7 +105,7 @@ If `mod_auth_kerb` is used, then use the following as an example:
Krb5Keytab /etc/apache2/http.keytab Krb5Keytab /etc/apache2/http.keytab
... ...
</Location> </Location>
<Location ~ "/v3/auth/OS-FEDERATION/identity_providers/idp_1/protocols/kerberos/websso"> <Location ~ "/v3/auth/OS-FEDERATION/identity_providers/myidp/protocols/kerberos/websso">
AuthType Kerberos AuthType Kerberos
AuthName "Acme Corporation" AuthName "Acme Corporation"
KrbMethodNegotiate on KrbMethodNegotiate on
@ -122,13 +123,13 @@ If `mod_auth_mellon` is used, then use the following as an example:
... ...
<Location ~ "/v3/auth/OS-FEDERATION/websso/saml2"> <Location ~ "/v3/auth/OS-FEDERATION/websso/mapped">
AuthType Mellon AuthType Mellon
MellonEnable auth MellonEnable auth
Require valid-user Require valid-user
... ...
</Location> </Location>
<Location ~ "/v3/auth/OS-FEDERATION/identity_providers/idp_1/protocols/saml2/websso"> <Location ~ "/v3/auth/OS-FEDERATION/identity_providers/myidp/protocols/mapped/websso">
AuthType Mellon AuthType Mellon
MellonEnable auth MellonEnable auth
Require valid-user Require valid-user
@ -154,7 +155,7 @@ It is recommended that this option be set on a per-protocol basis.
.. code-block:: ini .. code-block:: ini
[saml2] [mapped]
remote_id_attribute = Shib-Identity-Provider remote_id_attribute = Shib-Identity-Provider
[oidc] [oidc]
remote_id_attribute = HTTP_OIDC_ISS remote_id_attribute = HTTP_OIDC_ISS
@ -166,45 +167,9 @@ Alternatively, a generic option may be set at the `[federation]` level.
[federation] [federation]
remote_id_attribute = HTTP_OIDC_ISS remote_id_attribute = HTTP_OIDC_ISS
4. Set `remote_ids` for a keystone identity provider using the API or CLI. 4. Copy the `sso_callback_template.html
<http://git.openstack.org/cgit/openstack/keystone/plain/etc/sso_callback_template.html>`__
A keystone identity provider may have multiple `remote_ids` specified, this template into the location specified by `[federation]/sso_callback_template`.
allows the same *keystone* identity provider resource to be used with multiple
external identity providers. For example, an identity provider resource
``university-idp``, may have the following `remote_ids`:
``['university-x', 'university-y', 'university-z']``.
This removes the need to configure N identity providers in keystone.
This can be performed using the `OS-FEDERATION API`_:
``PATCH /OS-FEDERATION/identity_providers/{idp_id}``
Or by using the `OpenStackClient CLI`_:
.. code-block:: bash
$ openstack identity provider set --remote-id <remote-id> <idp-id>
.. NOTE::
Remote IDs are globally unique. Two identity providers cannot be
associated with the same remote ID. Once authenticated with the external
identity provider, keystone will determine which identity provider
and mapping to use based on the protocol and the value returned from the
`remote_id_attribute` key.
For example, if our identity provider is ``google``, the mapping used is
``google_mapping`` and the protocol is ``oidc``. The identity provider's
remote IDs would be: [``accounts.google.com``].
The `remote_id_attribute` value may be set to ``HTTP_OIDC_ISS``, since
this value will always be ``accounts.google.com``.
The motivation for this approach is that there will always be some data
sent by the identity provider (in the assertion or claim) that uniquely
identifies the identity provider. This removes the requirement for horizon
to list all the identity providers that are trusted by keystone.
.. _`OpenStackClient CLI`: http://docs.openstack.org/developer/python-openstackclient/command-objects/identity-provider.html#identity-provider-set
.. _`OS-FEDERATION API`: http://specs.openstack.org/openstack/keystone-specs/api/v3/identity-api-v3-os-federation-ext.html#update-identity-provider
--------------- ---------------
Horizon Changes Horizon Changes
@ -217,27 +182,7 @@ Horizon Changes
Identity provider and federation protocol specific webSSO is only available Identity provider and federation protocol specific webSSO is only available
in Django OpenStack Auth version 2.0.0 or higher. in Django OpenStack Auth version 2.0.0 or higher.
1. Set the Identity Service version to 3 1. Set the `WEBSSO_ENABLED` option.
Ensure the `OPENSTACK_API_VERSIONS` option in horizon's local_settings.py has
been updated to indicate that the `identity` version to use is `3`.
.. code-block:: python
OPENSTACK_API_VERSIONS = {
"identity": 3,
}
2. Authenticate against Identity Server v3.
Ensure the `OPENSTACK_KEYSTONE_URL` option in horizon's local_settings.py has
been updated to point to a v3 URL.
.. code-block:: python
OPENSTACK_KEYSTONE_URL = "http://localhost:5000/v3"
3. Set the `WEBSSO_ENABLED` option.
Ensure the `WEBSSO_ENABLED` option is set to True in horizon's local_settings.py file, Ensure the `WEBSSO_ENABLED` option is set to True in horizon's local_settings.py file,
this will provide users with an updated login screen for horizon. this will provide users with an updated login screen for horizon.
@ -246,7 +191,7 @@ this will provide users with an updated login screen for horizon.
WEBSSO_ENABLED = True WEBSSO_ENABLED = True
4. (Optional) Create a list of authentication methods with the 2. (Optional) Create a list of authentication methods with the
`WEBSSO_CHOICES` option. `WEBSSO_CHOICES` option.
Within horizon's settings.py file, a list of supported authentication methods can be Within horizon's settings.py file, a list of supported authentication methods can be
@ -261,12 +206,12 @@ identity backend.
WEBSSO_CHOICES = ( WEBSSO_CHOICES = (
("credentials", _("Keystone Credentials")), ("credentials", _("Keystone Credentials")),
("oidc", _("OpenID Connect")), ("oidc", _("OpenID Connect")),
("saml2", _("Security Assertion Markup Language")), ("mapped", _("Security Assertion Markup Language")),
("idp_1_oidc", "Acme Corporation - OpenID Connect"), ("myidp_oidc", "Acme Corporation - OpenID Connect"),
("idp_1_saml2", "Acme Corporation - SAML2") ("myidp_mapped", "Acme Corporation - SAML2")
) )
5. (Optional) Create a dictionary of specific identity provider and federation 3. (Optional) Create a dictionary of specific identity provider and federation
protocol combinations. protocol combinations.
A dictionary of specific identity provider and federation protocol combinations. A dictionary of specific identity provider and federation protocol combinations.
@ -279,8 +224,8 @@ protocol endpoint.
.. code-block:: python .. code-block:: python
WEBSSO_IDP_MAPPING = { WEBSSO_IDP_MAPPING = {
"idp_1_oidc": ("idp_1", "oidc"), "myidp_oidc": ("myidp", "oidc"),
"idp_1_saml2": ("idp_1", "saml2") "myidp_mapped": ("myidp", "mapped")
} }
.. NOTE:: .. NOTE::