From 609518ff2b6bcec82df561858f63e31203603825 Mon Sep 17 00:00:00 2001 From: Lance Bragstad Date: Fri, 28 Aug 2015 15:25:31 +0000 Subject: [PATCH] Add documentation for configuring IdP WebSSO We recently added a new federation call to Keystone that will allow federated authentication flows for a specific Identity Provider. This commit adds documentation around configuring httpd modules for the newly added call and horizon configuration. Co-Authored-By: Lin Hua Cheng Change-Id: Id334e979c951387b1d70da70fc5d4939a6e7d6a6 related: bp federation-idp-websso Closes-Bug: 1491910 Related-Bug: 1491916 --- doc/source/federation/websso.rst | 79 ++++++++++++++++++++++++++++---- 1 file changed, 70 insertions(+), 9 deletions(-) diff --git a/doc/source/federation/websso.rst b/doc/source/federation/websso.rst index 4ada0a4cc2..682449ac8d 100644 --- a/doc/source/federation/websso.rst +++ b/doc/source/federation/websso.rst @@ -35,9 +35,17 @@ prevent man-in-the-middle (MITM) attacks. 2. Update httpd vhost file with websso information. -The `/v3/auth/OS-FEDERATION/websso/` route 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. +The `/v3/auth/OS-FEDERATION/websso/` 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: @@ -52,6 +60,11 @@ If `mod_shib` is used, then use the following as an example: Require valid-user ... + + AuthType shibboleth + Require valid-user + ... + If `mod_auth_openidc` is used, then use the following as an example: @@ -61,6 +74,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 ... @@ -69,6 +83,11 @@ If `mod_auth_openidc` is used, then use the following as an example: Require valid-user ... + + AuthType openid-connect + Require valid-user + ... + If `mod_auth_kerb` is used, then use the following as an example: @@ -87,6 +106,14 @@ 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 + KrbMethodK5Passwd off + Krb5Keytab /etc/apache2/http.keytab + ... + If `mod_auth_mellon` is used, then use the following as an example: @@ -103,6 +130,12 @@ If `mod_auth_mellon` is used, then use the following as an example: Require valid-user ... + + AuthType Mellon + MellonEnable auth + Require valid-user + ... + .. NOTE:: @@ -182,6 +215,9 @@ Horizon Changes 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 @@ -214,20 +250,45 @@ this will provide users with an updated login screen for horizon. 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 entries in the list map to keystone federation protocols, -with the exception of ``credentials`` which is reserved by horizon, and maps to -the user name and password used by keystone's identity backend. +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")) + ("saml2", _("Security Assertion Markup Language")), + ("idp_1_oidc", "Acme Corporation - OpenID Connect"), + ("idp_1_saml2", "Acme Corporation - SAML2") ) -5. (Optional) Specify an initial choice with the `WEBSSO_INITIAL_CHOICE` +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: (, ). + +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