From 38f79a8edf624a12c06558d97602f54f8e4bd83a Mon Sep 17 00:00:00 2001 From: Colleen Murphy Date: Thu, 15 Sep 2016 15:53:56 -0700 Subject: [PATCH] Update, correct, and enhance federation docs This patch updates and adds examples and clarifies some instructions that were unclear or needed additional explanation for the Federation configuration overview, the Shibboleth setup instructions, and the horizon WebSSO documentation. These changes include: - Change instances of 'saml2' to 'mapped' where appropriate, since the documentation currently notes that using 'saml2' is deprecated - Make note of differences when using keystone-to-keystone federation and keystone as an Identity Provider where appropriate - Linkify section contents listings - Add examples using openstackclient - The examples include adding both a domain and a project for federated users, since there seems to be a horizon bug that cause federated users to not be able to log in if their group is only authorized on a domain and no projects[1] (not yet filed) - Move discussion of remote IDs from the websso section to the main configuration section, since the instructions to add identity providers are already in the main section and this is really more about keystone configuration than horizon configuration - Add example mapping rules for both a keystone-to-keystone configuration and a Shibboleth (using testshib.org) configuration - Correct description of token response format in "Performing federated authentication" section - Enhance description of configuration options for keystone as an IdP - Make the names and domain names of Service Providers and Identity Providers consistent throughout the documentation (beta and BETA were especially confusing) - Change references to wsgi-keystone.conf to keystone.conf since that's what devstack calls it now - Change keystone-to-keystone authentication demo to use keystoneauth instead of cURL (inspired by rodrigods's blog post on keystone-to-keystone[2]) - Move the note about fetching the SP's metadata to after shibboleth2.xml configuration is done, since the entityID needs to be set in the metadata for the IdP to recognize it - Enhance the description of what needs to be changed in shibboleth2.xml and use the package-generated example - Remove the section on removing REMOTE_USER from shibboleth2.xml, as this is needed to allow keystone to look up the remote user in the SAML assertion - Remove sections about keystone v3 from the WebSSO, that's old news and it's the default now - Add a step to ensure the SSO redirect template is copied into place, since devstack does not do that by default [1] http://git.openstack.org/cgit/openstack/django_openstack_auth/tree/openstack_auth/backend.py?h=2.4.1#n174 [2] http://blog.rodrigods.com/it-is-time-to-play-with-keystone-to-keystone-federation-in-kilo/ Change-Id: Id3ad18c43ace9e43d05b0acf966e577c909fa3e8 --- .../federation/configure_federation.rst | 279 ++++++++++++---- doc/source/federation/shibboleth.rst | 297 +++++++++--------- doc/source/federation/websso.rst | 99 ++---- 3 files changed, 398 insertions(+), 277 deletions(-) diff --git a/doc/source/federation/configure_federation.rst b/doc/source/federation/configure_federation.rst index 8dc1f6017b..ab9a5e025c 100644 --- a/doc/source/federation/configure_federation.rst +++ b/doc/source/federation/configure_federation.rst @@ -35,7 +35,8 @@ Prerequisites 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. +assertions or OpenID Connect claims, or by using +`Keystone as an Identity Provider (IdP)`_. Federated users are not mirrored in the keystone identity backend (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. 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: -1. Run keystone under Apache, rather than using uwsgi command. -2. Configure Apache to use a federation capable authentication method. -3. Configure ``federation`` in keystone. +1. `Run keystone under Apache`_, rather than using uwsgi command. +2. `Configure Apache to use a federation capable authentication method`_. +3. `Configure Federation in Keystone`_. + +.. _`Run keystone under Apache`: ../apache-httpd.html 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 -Configuring Federation in Keystone ----------------------------------- +Configure Federation in Keystone +-------------------------------- Now that the Identity Provider and keystone are communicating we can start to configure ``federation``. -1. Configure authentication drivers in ``keystone.conf`` -2. Add local keystone groups and roles -3. Add Identity Provider(s), Mapping(s), and Protocol(s) +1. `Configure authentication drivers in keystone.conf`_ +2. `Create keystone groups and assign roles`_ +3. `Add Identity Provider(s), Mapping(s), and Protocol(s)`_ -Configure authentication drivers in ``keystone.conf`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Configure authentication drivers in keystone.conf +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. NOTE:: ``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 `_. +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) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ To utilize federation the following must be created in the Identity Service: -* Identity Provider -* Mapping -* Protocol +* `Identity Provider`_ +* `Mapping`_ +* `Protocol`_ Read more about `federation in keystone `__. @@ -139,7 +165,46 @@ Identity Provider ~~~~~~~~~~~~~~~~~ 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 `__. @@ -157,6 +222,71 @@ rules can be found on the :doc:`mapping_combinations` page. 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. +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 < rules.json <`__. @@ -167,13 +297,27 @@ Protocol 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. -Add `Protocol object -`__ and specify the mapping id -you want to use with the combination of the IdP and Protocol. +You can create a protocol like this: + +.. 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 +`__ 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 2. Determine accessible resources 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 and be prompted for credentials. After successfully authenticating the user 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 belongs to will be included. @@ -255,7 +400,7 @@ Example cURL .. code-block:: bash - $ curl -X POST -H "Content-Type: application/json" -d '{"auth":{"identity":{"methods":["mapped"],"saml2":{"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":""}},"scope":{"project":{"domain": {"name": "federated_domain"},"name":"federated_project"}}}}' -D - http://localhost:5000/v3/auth/tokens -------------------------------------- Keystone as an Identity Provider (IdP) @@ -290,10 +435,21 @@ example: .. code-block:: ini [saml] - certfile=/etc/keystone/ssl/certs/ca.pem - keyfile=/etc/keystone/ssl/private/cakey.pem - 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=https://myidp.example.com/v3/OS-FEDERATION/saml2/idp + idp_sso_endpoint=https://myidp.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 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_surname=Smith idp_contact_email=jsmith@example.com - idp_contact_telephone=555-55-5555 + idp_contact_telephone=555-555-5555 idp_contact_type=technical Generate Metadata ----------------- 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 -and pipe the output to a file. For example: +and redirect the output to a file. For example: .. 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 ``idp_metadata_path`` that was assigned in the previous section. +Finally, restart apache. + Create a Service Provider (SP) ------------------------------ -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/SAML2/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 +In this example we are creating a new Service Provider with an ID of ``mysp``, +a ``sp_url`` of ``http://mysp.example.com/Shibboleth.sso/SAML2/ECP`` and a +``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 ``mysp`` and 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. +token for ``mysp`` once the SAML assertion is sent. The auth_url has the format +described in `Get an unscoped token`_. .. code-block:: bash - $ curl -s -X PUT \ - -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 + $ 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 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. +Use keystoneauth to create a password session with the IdP, then use the +session to authenticate with the SP, and get a scoped token from the SP. .. NOTE:: ECP stands for Enhanced Client or Proxy, an extension from the SAML2 - protocol used in non-browser interfaces, like in the following example - with cURL. + protocol used in non-browser interfaces, like in the following example. -.. code-block:: bash +.. code-block:: python - $ curl -s -X POST \ - -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 + import os -.. NOTE:: - Use URL http://localhost:5000/v3/auth/OS-FEDERATION/saml2 to request for - pure SAML Assertions. + from keystoneauth1 import session + from keystoneauth1.identity import v3 + from keystoneauth1.identity.v3 import k2k -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 -present in the response containing the Assertion, and a valid OpenStack -token, issued by a Service Provider keystone, will be returned. + auth = v3.Password(auth_url=os.environ.get('OS_AUTH_URL'), + username=os.environ.get('OS_USERNAME'), + password=os.environ.get('OS_PASSWORD'), + 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) diff --git a/doc/source/federation/shibboleth.rst b/doc/source/federation/shibboleth.rst index a9fd9e6c9a..045e12ecd0 100644 --- a/doc/source/federation/shibboleth.rst +++ b/doc/source/federation/shibboleth.rst @@ -35,16 +35,15 @@ Add *WSGIScriptAlias* directive to your vhost configuration:: WSGIScriptAliasMatch ^(/v3/OS-FEDERATION/identity_providers/.*?/protocols/.*?/auth)$ /var/www/keystone/main/$1 -Make sure the *wsgi-keystone.conf* contains a ** directive for the Shibboleth module and +Make sure the *keystone.conf* vhost file contains a ** directive for the Shibboleth module and a ** directive for each identity provider:: SetHandler shib - + ShibRequestSetting requireSession 1 - ShibRequestSetting applicationId idp_1 AuthType shibboleth ShibExportAssertion Off Require valid-user @@ -56,28 +55,18 @@ a ** directive for each identity provider:: .. NOTE:: - * ``saml2`` may be different in your deployment, but do not use a wildcard value. - Otherwise *every* federated protocol will be handled by Shibboleth. - * ``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. + * ``mapped`` is the name of the `protocol that you will configure `_ + * ``myidp`` is the name associated with the `IdP in Keystone `_ * The ``ShibRequireSession`` and ``ShibRequireAll`` rules are invalid in Apache 2.4+. * You are advised to carefully examine `Shibboleth Apache configuration documentation `_ -Enable the Keystone virtual host, for example: +Enable the ``shib2`` module, for example: .. code-block:: bash - $ a2ensite wsgi-keystone.conf - -Enable the ``ssl`` and ``shib2`` modules, for example: - -.. code-block:: bash - - $ a2enmod ssl $ a2enmod shib2 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 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 $ shib-keygen -y -The newly created 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 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. +The newly created key file will be stored under ``/etc/shibboleth/sp-key.pem``. Configure your Service Provider by editing ``/etc/shibboleth/shibboleth2.xml`` -file. You are advised to examine `Shibboleth Service Provider Configuration documentation `_ +file. You will want to change five settings: -An example of your ``/etc/shibboleth/shibboleth2.xml`` may look like -(The example shown below is for reference only, not to be used in a production -environment): +* Set the SP entity ID. This value usually has the form of a URI but it does not + have to resolve to anything. It must uniquely identify your Service Provider + to your Identity Provider. .. code-block:: xml - +* Set the IdP entity ID. This value is determined by the IdP. For example, if +Keystone is the IdP: + +.. code-block:: xml + + + +Example if testshib.org is the IdP: + +.. code-block:: xml + + + +* 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 + + + +Example if testshib.org is the IdP: + +.. code-block:: xml + + + +You are advised to examine `Shibboleth Service Provider Configuration documentation `_ + +The result should look like (The example shown below is for reference only, not +to be used in a production environment): + +.. code-block:: xml + 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"> - - + + + + + + - - + - - - - SAML2 SAML1 + + + SAML2 SAML1 - SAML2 Local - - - - + + - + - + + - - + - - - + + + + + + + + - + + + + + + + - - - - - - - - SAML2 SAML1 - - - SAML2 Local - - - - - - - - - - - - SAML2 SAML1 - - - SAML2 Local - - - - - - - - + + - - + + -Keystone enforces `external authentication`_ when the ``REMOTE_USER`` -environment variable is present so make sure Shibboleth doesn't set the -``REMOTE_USER`` environment variable. To do so, scan through the -``/etc/shibboleth/shibboleth2.xml`` configuration file and remove the -``REMOTE_USER`` directives. +If keystone is your IdP, you will need to examine your attributes map file +``/etc/shibboleth/attribute-map.xml`` and add the following attributes: -Examine your attributes map file ``/etc/shibboleth/attribute-map.xml`` and adjust -your requirements if needed. For more information see +.. code-block:: xml + + + + + + + +For more information see the `attributes documentation `_ -Once you are done, restart your Shibboleth daemon: +Once you are done, restart your Shibboleth daemon and apache: .. _`external authentication`: ../external-auth.html @@ -279,3 +275,16 @@ Once you are done, restart your Shibboleth daemon: $ service shibd 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. diff --git a/doc/source/federation/websso.rst b/doc/source/federation/websso.rst index 4e3c6658da..0a44e2871f 100644 --- a/doc/source/federation/websso.rst +++ b/doc/source/federation/websso.rst @@ -53,15 +53,16 @@ If `mod_shib` is used, then use the following as an example: ... - + AuthType shibboleth Require valid-user - ... + ShibRequestSetting requireSession 1 + ShibRequireSession On + ShibExportAssertion Off - + AuthType shibboleth Require valid-user - ... @@ -72,7 +73,7 @@ If `mod_auth_openidc` is used, then use the following as an example: 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 ... - + AuthType openid-connect 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 ... - + AuthType Kerberos AuthName "Acme Corporation" KrbMethodNegotiate on @@ -122,13 +123,13 @@ If `mod_auth_mellon` is used, then use the following as an example: ... - + AuthType Mellon MellonEnable auth Require valid-user ... - + AuthType Mellon MellonEnable auth Require valid-user @@ -154,7 +155,7 @@ It is recommended that this option be set on a per-protocol basis. .. code-block:: ini - [saml2] + [mapped] remote_id_attribute = Shib-Identity-Provider [oidc] remote_id_attribute = HTTP_OIDC_ISS @@ -166,45 +167,9 @@ Alternatively, a generic option may be set at the `[federation]` level. [federation] remote_id_attribute = HTTP_OIDC_ISS -4. Set `remote_ids` for a keystone identity provider using the API or CLI. - -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. - -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 - -.. 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 +4. Copy the `sso_callback_template.html +`__ +template into the location specified by `[federation]/sso_callback_template`. --------------- Horizon Changes @@ -217,27 +182,7 @@ Horizon Changes Identity provider and federation protocol specific webSSO is only available in Django OpenStack Auth version 2.0.0 or higher. -1. Set the Identity Service version to 3 - -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. +1. Set the `WEBSSO_ENABLED` option. 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. @@ -246,7 +191,7 @@ this will provide users with an updated login screen for horizon. 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. Within horizon's settings.py file, a list of supported authentication methods can be @@ -261,12 +206,12 @@ identity backend. WEBSSO_CHOICES = ( ("credentials", _("Keystone Credentials")), ("oidc", _("OpenID Connect")), - ("saml2", _("Security Assertion Markup Language")), - ("idp_1_oidc", "Acme Corporation - OpenID Connect"), - ("idp_1_saml2", "Acme Corporation - SAML2") + ("mapped", _("Security Assertion Markup Language")), + ("myidp_oidc", "Acme Corporation - OpenID Connect"), + ("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. A dictionary of specific identity provider and federation protocol combinations. @@ -279,8 +224,8 @@ protocol endpoint. .. code-block:: python WEBSSO_IDP_MAPPING = { - "idp_1_oidc": ("idp_1", "oidc"), - "idp_1_saml2": ("idp_1", "saml2") + "myidp_oidc": ("myidp", "oidc"), + "myidp_mapped": ("myidp", "mapped") } .. NOTE::