250 lines
7.9 KiB
ReStructuredText
250 lines
7.9 KiB
ReStructuredText
..
|
|
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
|