Merge "Consolidate WebSSO guide into SP instructions"
This commit is contained in:
Zuul
Gerrit Code Review
commit
c57ef4f9ee
|
|
@ -313,7 +313,7 @@ However, if you have configured the keystone service to use a virtual path such
|
|||
</Location>
|
||||
...
|
||||
|
||||
.. _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
|
||||
|
|
|
|||
|
|
@ -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