Consolidate WebSSO guide into SP instructions
The WebSSO documentation does not have a good flow with the rest of the federation guide. It includes instructions about the remote_id_attribute which is not WebSSO specific, as well as instructions for configuring Apache which is partly redundant with the SP-specific instructions. This change consolidates the guide into the main guide so that it makes sense with the rest of the document. Partial-bug: #1793374 Change-Id: I0c8fa537a950090f85b3cb4a4aac6c896f02db89
This commit is contained in:
parent
708d3f4d59
commit
069392fe95
|
@ -313,7 +313,7 @@ However, if you have configured the keystone service to use a virtual path such
|
||||||
</Location>
|
</Location>
|
||||||
...
|
...
|
||||||
|
|
||||||
.. _horizon for WebSSO: websso.html
|
.. _horizon for WebSSO: `Configuring Horizon as a WebSSO Frontend`_
|
||||||
|
|
||||||
Configure the auth module
|
Configure the auth module
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~
|
~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
@ -360,13 +360,139 @@ method.
|
||||||
[auth]
|
[auth]
|
||||||
methods = password,token,saml2,openid
|
methods = password,token,saml2,openid
|
||||||
|
|
||||||
When finished configuring keystone, restart the keystone WSGI process or the web
|
Configure the Remote ID Attribute
|
||||||
server:
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
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
|
.. code-block:: console
|
||||||
|
|
||||||
# systemctl restart apache2
|
# 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
|
Authenticating
|
||||||
--------------
|
--------------
|
||||||
|
|
||||||
|
@ -493,8 +619,10 @@ Configuring Metadata
|
||||||
--------------------
|
--------------------
|
||||||
|
|
||||||
Since keystone is acting as a SAML Identity Provider, its metadata must be
|
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
|
configured in the ``[saml]`` section (not to be confused with an optional
|
||||||
by the `metadata API`_.
|
``[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
|
.. _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:: openidc.rst
|
||||||
.. include:: mellon.rst
|
.. include:: mellon.rst
|
||||||
.. include:: shibboleth.rst
|
.. include:: shibboleth.rst
|
||||||
.. include:: websso.rst
|
|
||||||
|
|
|
@ -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/<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:: apache
|
|
||||||
|
|
||||||
<VirtualHost *:5000>
|
|
||||||
|
|
||||||
...
|
|
||||||
|
|
||||||
<Location ~ "/v3/auth/OS-FEDERATION/websso/saml2">
|
|
||||||
AuthType shibboleth
|
|
||||||
Require valid-user
|
|
||||||
ShibRequestSetting requireSession 1
|
|
||||||
ShibRequireSession On
|
|
||||||
ShibExportAssertion Off
|
|
||||||
</Location>
|
|
||||||
<Location ~ "/v3/auth/OS-FEDERATION/identity_providers/samltest/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:: apache
|
|
||||||
|
|
||||||
<VirtualHost *:5000>
|
|
||||||
|
|
||||||
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
|
|
||||||
|
|
||||||
...
|
|
||||||
|
|
||||||
<Location ~ "/v3/auth/OS-FEDERATION/websso/openid">
|
|
||||||
AuthType openid-connect
|
|
||||||
Require valid-user
|
|
||||||
...
|
|
||||||
</Location>
|
|
||||||
<Location ~ "/v3/auth/OS-FEDERATION/identity_providers/samltest/protocols/openid/websso">
|
|
||||||
AuthType openid-connect
|
|
||||||
Require valid-user
|
|
||||||
...
|
|
||||||
</Location>
|
|
||||||
</VirtualHost>
|
|
||||||
|
|
||||||
If `mod_auth_kerb` is used, then use the following as an example:
|
|
||||||
|
|
||||||
.. code-block:: apache
|
|
||||||
|
|
||||||
<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/samltest/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:: apache
|
|
||||||
|
|
||||||
<VirtualHost *:5000>
|
|
||||||
|
|
||||||
...
|
|
||||||
|
|
||||||
<Location ~ "/v3/auth/OS-FEDERATION/websso/saml2">
|
|
||||||
AuthType Mellon
|
|
||||||
MellonEnable auth
|
|
||||||
Require valid-user
|
|
||||||
...
|
|
||||||
</Location>
|
|
||||||
<Location ~ "/v3/auth/OS-FEDERATION/identity_providers/samltest/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
|
|
||||||
[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
|
|
||||||
<https://git.openstack.org/cgit/openstack/keystone/plain/etc/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: (<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"
|
|
||||||
|
|
||||||
7. Restart your web server:
|
|
||||||
|
|
||||||
.. code-block:: console
|
|
||||||
|
|
||||||
# service apache2 restart
|
|
Loading…
Reference in New Issue