diff options
Diffstat (limited to 'keystone-moon/doc/source/federation')
| -rw-r--r-- | keystone-moon/doc/source/federation/mellon.rst | 122 | ||||
| -rw-r--r-- | keystone-moon/doc/source/federation/openidc.rst | 94 | ||||
| -rw-r--r-- | keystone-moon/doc/source/federation/shibboleth.rst | 282 | ||||
| -rw-r--r-- | keystone-moon/doc/source/federation/websso.rst | 300 |
4 files changed, 0 insertions, 798 deletions
diff --git a/keystone-moon/doc/source/federation/mellon.rst b/keystone-moon/doc/source/federation/mellon.rst deleted file mode 100644 index 9c4675b7..00000000 --- a/keystone-moon/doc/source/federation/mellon.rst +++ /dev/null @@ -1,122 +0,0 @@ -:orphan: - -.. - 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. - -============================== -Setup Mellon (mod_auth_mellon) -============================== - -Configure Apache HTTPD for mod_auth_mellon -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Follow the steps outlined at: `Running Keystone in HTTPD`_. - -.. _`Running Keystone in HTTPD`: ../apache-httpd.html - -You'll also need to install the Apache module `mod_auth_mellon -<https://github.com/UNINETT/mod_auth_mellon>`_. For example: - -.. code-block:: bash - - $ apt-get install libapache2-mod-auth-mellon - -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 the *wsgi-keystone.conf* contains a *<Location>* directive for the Mellon module and -a *<Location>* directive for each identity provider:: - - <Location /v3> - MellonEnable "info" - MellonSPPrivateKeyFile /etc/httpd/mellon/http_keystone.fqdn.key - MellonSPCertFile /etc/httpd/mellon/http_keystone.fqdn.cert - MellonSPMetadataFile /etc/httpd/mellon/http_keystone.fqdn.xml - MellonIdPMetadataFile /etc/httpd/mellon/idp-metadata.xml - MellonEndpointPath /v3/OS-FEDERATION/identity_providers/idp_1/protocols/saml2/auth/mellon - MellonIdP "IDP" - </Location> - - <Location /v3/OS-FEDERATION/identity_providers/idp_1/protocols/saml2/auth> - AuthType "Mellon" - MellonEnable "auth" - </Location> - -.. NOTE:: - * See below for information about how to generate the values for the - `MellonSPMetadataFile`, etc. directives. - * ``saml2`` may be different in your deployment, but do not use a wildcard value. - Otherwise *every* federated protocol will be handled by Mellon. - * ``idp_1`` has to be replaced with the name associated with the IdP in Keystone. - * You are advised to carefully examine `mod_auth_mellon Apache - configuration documentation - <https://github.com/UNINETT/mod_auth_mellon>`_ - -Enable the Keystone virtual host, for example: - -.. code-block:: bash - - $ a2ensite wsgi-keystone.conf - -Enable the ``ssl`` and ``auth_mellon`` modules, for example: - -.. code-block:: bash - - $ a2enmod ssl - $ a2enmod auth_mellon - -Restart the Apache instance that is serving Keystone, for example: - -.. code-block:: bash - - $ service apache2 restart - -Configuring the Mellon SP Metadata -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Mellon provides a script called ``mellon_create_metadata.sh`` which generates the -values for the config directives `MellonSPPrivateKeyFile`, `MellonSPCertFile`, -and `MellonSPMetadataFile`. It is run like this: - -.. code-block:: bash - - $ mellon_create_metadata.sh http://keystone.fqdn:5000 \ - http://keystone.fqdn:5000/v3/OS-FEDERATION/identity_providers/idp_1/protocols/saml2/auth/mellon - -The first parameter is used as the entity ID, a unique identifier for this -Keystone SP. You do not have to use the URL, but it is an easy way to uniquely -identify each Keystone SP. The second parameter is the full URL for the -endpoint path corresponding to the parameter `MellonEndpointPath`. - -Fetch your Service Provider's Metadata file. This corresponds to the value of -the `MellonIdPMetadataFile` directive above. For example: - -.. code-block:: bash - - $ wget --cacert /path/to/ca.crt -O /etc/httpd/mellon/idp-metadata.xml \ - https://idp.fqdn/idp/saml2/metadata - -Upload your Service Provider's Metadata file to your Identity Provider. This -is the file used as the value of the `MellonSPMetadataFile` in the config, -generated by the `mellon_create_metadata.sh` script. The IdP may provide a -webpage where you can upload the file, or you may be required to submit the -file using `wget` or `curl`. Please check your IdP documentation for details. - -Once you are done, restart the Apache instance that is serving Keystone, for example: - -.. code-block:: bash - - $ service apache2 restart diff --git a/keystone-moon/doc/source/federation/openidc.rst b/keystone-moon/doc/source/federation/openidc.rst deleted file mode 100644 index ece82d3a..00000000 --- a/keystone-moon/doc/source/federation/openidc.rst +++ /dev/null @@ -1,94 +0,0 @@ -:orphan: - -.. - 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. - -==================== -Setup OpenID Connect -==================== - -Configuring mod_auth_openidc -============================ - -Federate Keystone (SP) and an external IdP using OpenID Connect (`mod_auth_openidc`_) - -.. _`mod_auth_openidc`: https://github.com/pingidentity/mod_auth_openidc - -To install `mod_auth_openidc` on Ubuntu, perform the following: - -.. code-block:: bash - - sudo apt-get install libapache2-mod-auth-openidc - -This module is available for other distributions (Fedora/CentOS/Red Hat) from: -https://github.com/pingidentity/mod_auth_openidc/releases - -In the keystone Apache site file, add the following as a top level option, to -load the `mod_auth_openidc` module: - -.. code-block:: xml - - LoadModule auth_openidc_module /usr/lib/apache2/modules/mod_auth_openidc.so - -Also within the same file, locate the virtual host entry and add the following -entries for OpenID Connect: - -.. code-block:: xml - - <VirtualHost *:5000> - - ... - - OIDCClaimPrefix "OIDC-" - OIDCResponseType "id_token" - OIDCScope "openid email profile" - OIDCProviderMetadataURL <url_of_provider_metadata> - OIDCClientID <openid_client_id> - OIDCClientSecret <openid_client_secret> - OIDCCryptoPassphrase openstack - OIDCRedirectURI http://localhost:5000/v3/OS-FEDERATION/identity_providers/<idp_id>/protocols/oidc/auth/redirect - - <LocationMatch /v3/OS-FEDERATION/identity_providers/.*?/protocols/oidc/auth> - AuthType openid-connect - Require valid-user - LogLevel debug - </LocationMatch> - </VirtualHost> - -Note an example of an `OIDCProviderMetadataURL` instance is: https://accounts.google.com/.well-known/openid-configuration -If not using `OIDCProviderMetadataURL`, then the following attributes -must be specified: `OIDCProviderIssuer`, `OIDCProviderAuthorizationEndpoint`, -`OIDCProviderTokenEndpoint`, `OIDCProviderTokenEndpointAuth`, -`OIDCProviderUserInfoEndpoint`, and `OIDCProviderJwksUri` - -Note, if using a mod_wsgi version less than 4.3.0, then the `OIDCClaimPrefix` -must be specified to have only alphanumerics or a dash ("-"). This is because -mod_wsgi blocks headers that do not fit this criteria. See http://modwsgi.readthedocs.org/en/latest/release-notes/version-4.3.0.html#bugs-fixed -for more details - -Once you are done, restart your Apache daemon: - -.. code-block:: bash - - $ service apache2 restart - -Tips -==== - -1. When creating a mapping, note that the 'remote' attributes will be prefixed, - with `HTTP_`, so for instance, if you set OIDCClaimPrefix to `OIDC-`, then a - typical remote value to check for is: `HTTP_OIDC_ISS`. - -2. Don't forget to add oidc as an [auth] plugin in keystone.conf, see `Step 2`_ - -.. _`Step 2`: federation/federation.html diff --git a/keystone-moon/doc/source/federation/shibboleth.rst b/keystone-moon/doc/source/federation/shibboleth.rst deleted file mode 100644 index b82bd703..00000000 --- a/keystone-moon/doc/source/federation/shibboleth.rst +++ /dev/null @@ -1,282 +0,0 @@ -:orphan: - -.. - 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. - -================ -Setup Shibboleth -================ - -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 the *wsgi-keystone.conf* contains a *<Location>* directive for the Shibboleth module and -a *<Location>* directive for each identity provider:: - - <Location /Shibboleth.sso> - SetHandler shib - </Location> - - <Location /v3/OS-FEDERATION/identity_providers/idp_1/protocols/saml2/auth> - ShibRequestSetting requireSession 1 - ShibRequestSetting applicationId idp_1 - AuthType shibboleth - ShibExportAssertion Off - Require valid-user - - <IfVersion < 2.4> - ShibRequireSession On - ShibRequireAll On - </IfVersion> - </Location> - -.. 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. - * The ``ShibRequireSession`` and ``ShibRequireAll`` rules are invalid in - Apache 2.4+. - * You are advised to carefully examine `Shibboleth Apache configuration - documentation - <https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPApacheConfig>`_ - -Enable the Keystone virtual host, 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: - -.. code-block:: bash - - $ service apache2 restart - -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: - -.. code-block:: bash - - $ shib-keygen -y <number of years> - -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 <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`` -file. You are advised to examine `Shibboleth Service Provider Configuration documentation <https://wiki.shibboleth.net/confluence/display/SHIB2/Configuration>`_ - -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): - -.. code-block:: xml - - <!-- - File configuration courtesy of http://testshib.org - - More information: - https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPConfiguration - --> - - <SPConfig xmlns="urn:mace:shibboleth:2.0:native:sp:config" - xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" clockSkew="1800 "> - - <!-- The entityID is the name TestShib made for your SP. --> - <ApplicationDefaults entityID="https://<yourhosthere>/shibboleth"> - - <!-- - You should use secure cookies if at all possible. - See cookieProps in this Wiki article. - --> - <!-- https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPSessions --> - <Sessions lifetime="28800" timeout="3600" checkAddress="false" - relayState="ss:mem" handlerSSL="false"> - - <!-- Triggers a login request directly to the TestShib IdP. --> - <!-- https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPServiceSSO --> - <SSO entityID="https://<idp-url>/idp/shibboleth" ECP="true"> - SAML2 SAML1 - </SSO> - - <!-- SAML and local-only logout. --> - <!-- https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPServiceLogout --> - <Logout>SAML2 Local</Logout> - - <!-- - Handlers allow you to interact with the SP and gather - 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. --> - <Handler type="Status" Location="/Status" - acl="127.0.0.1"/> - - <!-- Session diagnostic service. --> - <Handler type="Session" Location="/Session" - showAttributeValues="true"/> - <!-- JSON feed of discovery information. --> - <Handler type="DiscoveryFeed" Location="/DiscoFeed"/> - </Sessions> - - <!-- - Error pages to display to yourself if - something goes horribly wrong. - --> - <Errors supportContact ="<admin_email_address>" - logoLocation="/shibboleth-sp/logo.jpg" - styleSheet="/shibboleth-sp/main.css"/> - - <!-- - Loads and trusts a metadata file that describes only one IdP - and how to communicate with it. - --> - <MetadataProvider type="XML" uri="<idp-metadata-file>" - backingFilePath="<local idp metadata>" - reloadInterval="180000" /> - - <!-- Attribute and trust options you shouldn't need to change. --> - <AttributeExtractor type="XML" validate="true" - path="attribute-map.xml"/> - <AttributeResolver type="Query" subjectMatch="true"/> - <AttributeFilter type="XML" validate="true" - path="attribute-policy.xml"/> - - <!-- - Your SP generated these credentials. - They're used to talk to IdP's. - --> - <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> - - <!-- - Security policies you shouldn't change unless you - know what you're doing. - --> - <SecurityPolicyProvider type="XML" validate="true" - path="security-policy.xml"/> - - <!-- - Low-level configuration about protocols and bindings - available for use. - --> - <ProtocolProvider type="XML" validate="true" reloadChanges="false" - path="protocols.xml"/> - - </SPConfig> - -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. - -Examine your attributes map file ``/etc/shibboleth/attribute-map.xml`` and adjust -your requirements if needed. For more information see -`attributes documentation <https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPAddAttribute>`_ - -Once you are done, restart your Shibboleth daemon: - -.. _`external authentication`: ../external-auth.html - -.. code-block:: bash - - $ service shibd restart - $ service apache2 restart diff --git a/keystone-moon/doc/source/federation/websso.rst b/keystone-moon/doc/source/federation/websso.rst deleted file mode 100644 index 682449ac..00000000 --- a/keystone-moon/doc/source/federation/websso.rst +++ /dev/null @@ -1,300 +0,0 @@ -:orphan: - -.. - 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. - -=============================== -Keystone Federation and Horizon -=============================== - -Keystone Changes -================ - -1. Update `trusted_dashboard` in keystone.conf. - -Specify URLs of trusted horizon servers. This value may be repeated -multiple times. This setting ensures that keystone only sends token data back -to trusted servers. This is performed as a precaution, specifically to -prevent man-in-the-middle (MITM) attacks. - -.. code-block:: ini - - [federation] - trusted_dashboard = http://acme.horizon.com/auth/websso/ - trusted_dashboard = http://beta.horizon.com/auth/websso/ - -2. Update httpd vhost file with websso information. - -The `/v3/auth/OS-FEDERATION/websso/<protocol>` and -`/v3/auth/OS-FEDERATION/identity_providers/{idp_id}/protocols/{protocol_id}/websso` -routes must be protected by the chosen httpd module. This is performed so the -request that originates from horizon will use the same identity provider that -is configured in keystone. - -.. WARNING:: - By using the IdP specific route, a user will no longer leverage the Remote - ID of a specific Identity Provider, and will be unable to verify that the - Identity Provider is trusted, the mapping will remain as the only means to - controlling authorization. - -If `mod_shib` is used, then use the following as an example: - -.. code-block:: xml - - <VirtualHost *:5000> - - ... - - <Location ~ "/v3/auth/OS-FEDERATION/websso/saml2"> - AuthType shibboleth - Require valid-user - ... - </Location> - <Location ~ "/v3/auth/OS-FEDERATION/identity_providers/idp_1/protocols/saml2/websso"> - AuthType shibboleth - Require valid-user - ... - </Location> - </VirtualHost> - -If `mod_auth_openidc` is used, then use the following as an example: - -.. code-block:: xml - - <VirtualHost *:5000> - - 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 - - ... - - <Location ~ "/v3/auth/OS-FEDERATION/websso/oidc"> - AuthType openid-connect - Require valid-user - ... - </Location> - <Location ~ "/v3/auth/OS-FEDERATION/identity_providers/idp_1/protocols/oidc/websso"> - AuthType openid-connect - Require valid-user - ... - </Location> - </VirtualHost> - -If `mod_auth_kerb` is used, then use the following as an example: - -.. code-block:: xml - - <VirtualHost *:5000> - - ... - - <Location ~ "/v3/auth/OS-FEDERATION/websso/kerberos"> - AuthType Kerberos - AuthName "Acme Corporation" - KrbMethodNegotiate on - KrbMethodK5Passwd off - Krb5Keytab /etc/apache2/http.keytab - ... - </Location> - <Location ~ "/v3/auth/OS-FEDERATION/identity_providers/idp_1/protocols/kerberos/websso"> - AuthType Kerberos - AuthName "Acme Corporation" - KrbMethodNegotiate on - KrbMethodK5Passwd off - Krb5Keytab /etc/apache2/http.keytab - ... - </Location> - </VirtualHost> - -If `mod_auth_mellon` is used, then use the following as an example: - -.. code-block:: xml - - <VirtualHost *:5000> - - ... - - <Location ~ "/v3/auth/OS-FEDERATION/websso/saml2"> - AuthType Mellon - MellonEnable auth - Require valid-user - ... - </Location> - <Location ~ "/v3/auth/OS-FEDERATION/identity_providers/idp_1/protocols/saml2/websso"> - AuthType Mellon - MellonEnable auth - Require valid-user - ... - </Location> - </VirtualHost> - -.. NOTE:: - If you are also using SSO via the API, don't forget to make the Location - settings match your configuration used for the keystone identity provider - location: - `/v3/OS-FEDERATION/identity_providers/<idp>/protocols/<protocol>/auth` - -3. Update `remote_id_attribute` in keystone.conf. - -A remote id attribute indicates the header to retrieve from the WSGI -environment. This header contains information about the identity -of the identity provider. For `mod_shib` this would be -``Shib-Identity-Provider``, for `mod_auth_openidc`, this could be -``HTTP_OIDC_ISS``. For `mod_auth_mellon`, this could be ``MELLON_IDP``. - -It is recommended that this option be set on a per-protocol basis. - -.. code-block:: ini - - [saml2] - remote_id_attribute = Shib-Identity-Provider - [oidc] - remote_id_attribute = HTTP_OIDC_ISS - -Alternatively, a generic option may be set at the `[federation]` level. - -.. code-block:: ini - - [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 <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 -=============== - -.. NOTE:: - - Django OpenStack Auth version 1.2.0 or higher is required for these steps. - - 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. - -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. - -.. code-block:: python - - WEBSSO_ENABLED = True - -4. (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 -specified. The list includes Keystone federation protocols such as OpenID Connect and -SAML, and also keys that map to specific identity provider and federation protocol -combinations (as defined in `WEBSSO_IDP_MAPPING`). With the exception of ``credentials`` -which is reserved by horizon, and maps to the user name and password used by keystone's -identity backend. - -.. code-block:: python - - 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") - ) - -5. (Optional) Create a dictionary of specific identity provider and federation - protocol combinations. - -A dictionary of specific identity provider and federation protocol combinations. -From the selected authentication mechanism, the value will be looked up as keys -in the dictionary. If a match is found, it will redirect the user to a identity -provider and federation protocol specific WebSSO endpoint in keystone, otherwise -it will use the value as the protocol_id when redirecting to the WebSSO by -protocol endpoint. - -.. code-block:: python - - WEBSSO_IDP_MAPPING = { - "idp_1_oidc": ("idp_1", "oidc"), - "idp_1_saml2": ("idp_1", "saml2") - } - -.. NOTE:: - - The value is expected to be a tuple formatted as: (<idp_id>, <protocol_id>). - -6. (Optional) Specify an initial choice with the `WEBSSO_INITIAL_CHOICE` - option. - -The list set by the `WEBSSO_CHOICES` option will be generated in a drop-down -menu in the login screen. The setting `WEBSSO_INITIAL_CHOICE` will -automatically set that choice to be highlighted by default. - -.. code-block:: python - - WEBSSO_INITIAL_CHOICE = "credentials" |