diff --git a/doc/source/admin/federation/configure_federation.rst b/doc/source/admin/federation/configure_federation.rst index fd5bc7dd81..407d1df5a8 100644 --- a/doc/source/admin/federation/configure_federation.rst +++ b/doc/source/admin/federation/configure_federation.rst @@ -313,7 +313,7 @@ However, if you have configured the keystone service to use a virtual path such ... -.. _horizon for WebSSO: websso.html +.. _horizon for WebSSO: `Configuring Horizon as a WebSSO Frontend`_ Configure the auth module ~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -360,13 +360,139 @@ method. [auth] methods = password,token,saml2,openid -When finished configuring keystone, restart the keystone WSGI process or the web -server: +Configure the Remote ID Attribute +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Keystone is mostly apathetic about what HTTPD auth module you choose to +configure for your Service Provider, but must know what header key to look for +from the auth module to determine the Identity Provider's remote ID so it can +associate the incoming request with the Identity Provider resource. The key name +is decided by the auth module choice: + +* For ``mod_shib``: use ``Shib-Identity-Provider`` +* For ``mod_auth_mellon``: use ``MELLON_IDP`` +* For ``mod_auth_openidc``: use ``HTTP_OIDC_ISS`` + +It is recommended that this option be set on a per-protocol basis by creating a +new section named after the protocol: + +.. code-block:: ini + + [saml2] + remote_id_attribute = Shib-Identity-Provider + [openid] + 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 + +Add a Trusted Dashboard (WebSSO) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you intend to configure horizon as a WebSSO frontend, you must specify the +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. The value must exactly match the origin address sent by the +horizon server, including any trailing slashes. + +.. code-block:: ini + + [federation] + trusted_dashboard = https://horizon1.example.org/auth/websso/ + trusted_dashboard = https://horizon2.example.org/auth/websso/ + +Add the Callback Template (WebSSO) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you intend to configure horizon as a WebSSO frontend, and if not already +done for you by your distribution's keystone package, copy the +`sso_callback_template.html`_ template into the location specified by the +``[federation]/sso_callback_template`` option in ``keystone.conf``. You can also +use this template as an example to create your own custom HTML redirect page. + +Restart the keystone WSGI service or the Apache frontend service after making +changes to your keystone configuration. .. code-block:: console # systemctl restart apache2 +.. _sso_callback_template.html: https://git.openstack.org/cgit/openstack/keystone/plain/etc/sso_callback_template.html + +.. _horizon-websso: + +Configuring Horizon as a WebSSO Frontend +---------------------------------------- + +.. note:: + + Consult `horizon's official documentation`_ for details on configuring + horizon. + +.. _horizon's official documentation: https://docs.openstack.org/horizon/latest/configuration/settings.html + +Keystone on its own is not capable of supporting a browser-based Single Sign-on +authentication flow such as the SAML2.0 WebSSO profile, therefore we must enlist +horizon's assistance. Horizon can be configured to support SSO by enabling it in +horizon's ``local_settings.py`` configuration file and adding the possible +authentication choices that will be presented to the user on the login screen. + +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 + +Configure the options for authenticating that a user may choose from at the +login screen. The pairs configured in this list map a user-friendly string to an +authentication option, which may be one of: + +* The string ``credentials`` which forces horizon to present its own username + and password fields that the user will use to authenticate as a local keystone + user +* The name of a protocol that you created in `Create a Protocol`_, such as + ``saml2`` or ``openid``, which will cause horizon to call keystone's `WebSSO + API without an Identity Provider`_ to authenticate the user +* A string that maps to an Identity Provider and Protocol combination configured + in ``WEBSSO_IDP_MAPPING`` which will cause horizon to call keystone's `WebSSO + API specific to the given Identity Provider`_. + +.. code-block:: python + + WEBSSO_CHOICES = ( + ("credentials", _("Keystone Credentials")), + ("openid", _("OpenID Connect")), + ("saml2", _("Security Assertion Markup Language")), + ("myidp_openid", "Acme Corporation - OpenID Connect"), + ("myidp_saml2", "Acme Corporation - SAML2") + ) + + WEBSSO_IDP_MAPPING = { + "myidp_openid": ("myidp", "openid"), + "myidp_saml2": ("myidp", "saml2") + } + +The initial selection of the dropdown menu can also be configured: + +.. code-block:: python + + WEBSSO_INITIAL_CHOICE = "credentials" + +Remember to restart the web server when finished configuring horizon: + +.. code-block:: console + + # systemctl restart apache2 + +.. _WebSSO API without an Identity Provider: https://developer.openstack.org/api-ref/identity/v3-ext/index.html#web-single-sign-on-authentication-new-in-version-1-2 +.. _WebSSO API specific to the given Identity Provider: https://developer.openstack.org/api-ref/identity/v3-ext/index.html#web-single-sign-on-authentication-new-in-version-1-3 + Authenticating -------------- @@ -493,8 +619,10 @@ Configuring Metadata -------------------- Since keystone is acting as a SAML Identity Provider, its metadata must be -configured in the ``[saml]`` section of ``keystone.conf`` so that it can served -by the `metadata API`_. +configured in the ``[saml]`` section (not to be confused with an optional +``[saml2]`` section which you may have configured in `Configure the Remote Id +Attribute`_ while setting up keystone as Service Provider) of ``keystone.conf`` +so that it can served by the `metadata API`_. .. _metadata API: https://developer.openstack.org/api-ref/identity/v3-ext/index.html#retrieve-metadata-properties @@ -627,4 +755,3 @@ to another cloud. .. include:: openidc.rst .. include:: mellon.rst .. include:: shibboleth.rst -.. include:: websso.rst diff --git a/doc/source/admin/federation/websso.rst b/doc/source/admin/federation/websso.rst deleted file mode 100644 index 23305a26f8..0000000000 --- a/doc/source/admin/federation/websso.rst +++ /dev/null @@ -1,249 +0,0 @@ -.. - 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 Web Single Sign-On (SSO) ------------------------------- - -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/` 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:: apache - - - - ... - - - AuthType shibboleth - Require valid-user - ShibRequestSetting requireSession 1 - ShibRequireSession On - ShibExportAssertion Off - - - AuthType shibboleth - Require valid-user - - - -If `mod_auth_openidc` is used, then use the following as an example: - -.. code-block:: apache - - - - OIDCRedirectURI https://sp.keystone.example.org/v3/auth/OS-FEDERATION/websso - OIDCRedirectURI https://sp.keystone.example.org/v3/auth/OS-FEDERATION/identity_providers/samltest/protocols/openid/websso - - ... - - - AuthType openid-connect - Require valid-user - ... - - - AuthType openid-connect - Require valid-user - ... - - - -If `mod_auth_kerb` is used, then use the following as an example: - -.. code-block:: apache - - - - ... - - - AuthType Kerberos - AuthName "Acme Corporation" - KrbMethodNegotiate on - KrbMethodK5Passwd off - 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: - -.. code-block:: apache - - - - ... - - - AuthType Mellon - MellonEnable auth - Require valid-user - ... - - - AuthType Mellon - MellonEnable auth - Require valid-user - ... - - - -.. 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//protocols//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 - [openid] - 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. Copy the `sso_callback_template.html -`__ -template into the location specified by `[federation]/sso_callback_template`. - -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 `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 - -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 -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")), - ("openid", _("OpenID Connect")), - ("saml2", _("Security Assertion Markup Language")), - ("acme_openid", "Acme Corporation - OpenID Connect"), - ("acme_saml2", "Acme Corporation - SAML2") - ) - -3. (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 = { - "acme_openid": ("acme", "openid"), - "acme_saml2": ("acme", "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 -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" - -7. Restart your web server: - -.. code-block:: console - - # service apache2 restart