Browse Source

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
tags/15.0.0.0rc1
Colleen Murphy 5 months ago
parent
commit
069392fe95

+ 133
- 6
doc/source/admin/federation/configure_federation.rst View File

@@ -313,7 +313,7 @@ However, if you have configured the keystone service to use a virtual path such
313 313
    </Location>
314 314
    ...
315 315
 
316
-.. _horizon for WebSSO: websso.html
316
+.. _horizon for WebSSO: `Configuring Horizon as a WebSSO Frontend`_
317 317
 
318 318
 Configure the auth module
319 319
 ~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -360,13 +360,139 @@ method.
360 360
    [auth]
361 361
    methods = password,token,saml2,openid
362 362
 
363
-When finished configuring keystone, restart the keystone WSGI process or the web
364
-server:
363
+Configure the Remote ID Attribute
364
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
365
+
366
+Keystone is mostly apathetic about what HTTPD auth module you choose to
367
+configure for your Service Provider, but must know what header key to look for
368
+from the auth module to determine the Identity Provider's remote ID so it can
369
+associate the incoming request with the Identity Provider resource. The key name
370
+is decided by the auth module choice:
371
+
372
+* For ``mod_shib``: use ``Shib-Identity-Provider``
373
+* For ``mod_auth_mellon``: use ``MELLON_IDP``
374
+* For ``mod_auth_openidc``: use ``HTTP_OIDC_ISS``
375
+
376
+It is recommended that this option be set on a per-protocol basis by creating a
377
+new section named after the protocol:
378
+
379
+.. code-block:: ini
380
+
381
+   [saml2]
382
+   remote_id_attribute = Shib-Identity-Provider
383
+   [openid]
384
+   remote_id_attribute = HTTP_OIDC_ISS
385
+
386
+Alternatively, a generic option may be set at the ``[federation]`` level.
387
+
388
+.. code-block:: ini
389
+
390
+  [federation]
391
+  remote_id_attribute = HTTP_OIDC_ISS
392
+
393
+Add a Trusted Dashboard (WebSSO)
394
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
395
+
396
+If you intend to configure horizon as a WebSSO frontend, you must specify the
397
+URLs of trusted horizon servers. This value may be repeated multiple times. This
398
+setting ensures that keystone only sends token data back to trusted servers.
399
+This is performed as a precaution, specifically to prevent man-in-the-middle
400
+(MITM) attacks. The value must exactly match the origin address sent by the
401
+horizon server, including any trailing slashes.
402
+
403
+.. code-block:: ini
404
+
405
+  [federation]
406
+  trusted_dashboard = https://horizon1.example.org/auth/websso/
407
+  trusted_dashboard = https://horizon2.example.org/auth/websso/
408
+
409
+Add the Callback Template (WebSSO)
410
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
411
+
412
+If you intend to configure horizon as a WebSSO frontend,  and if not already
413
+done for you by your distribution's keystone package, copy the
414
+`sso_callback_template.html`_ template into the location specified by the
415
+``[federation]/sso_callback_template`` option in ``keystone.conf``. You can also
416
+use this template as an example to create your own custom HTML redirect page.
417
+
418
+Restart the keystone WSGI service or the Apache frontend service after making
419
+changes to your keystone configuration.
365 420
 
366 421
 .. code-block:: console
367 422
 
368 423
    # systemctl restart apache2
369 424
 
425
+.. _sso_callback_template.html: https://git.openstack.org/cgit/openstack/keystone/plain/etc/sso_callback_template.html
426
+
427
+.. _horizon-websso:
428
+
429
+Configuring Horizon as a WebSSO Frontend
430
+----------------------------------------
431
+
432
+.. note::
433
+
434
+   Consult `horizon's official documentation`_ for details on configuring
435
+   horizon.
436
+
437
+.. _horizon's official documentation: https://docs.openstack.org/horizon/latest/configuration/settings.html
438
+
439
+Keystone on its own is not capable of supporting a browser-based Single Sign-on
440
+authentication flow such as the SAML2.0 WebSSO profile, therefore we must enlist
441
+horizon's assistance. Horizon can be configured to support SSO by enabling it in
442
+horizon's ``local_settings.py`` configuration file and adding the possible
443
+authentication choices that will be presented to the user on the login screen.
444
+
445
+Ensure the `WEBSSO_ENABLED` option is set to `True` in horizon's local_settings.py file,
446
+this will provide users with an updated login screen for horizon.
447
+
448
+.. code-block:: python
449
+
450
+   WEBSSO_ENABLED = True
451
+
452
+Configure the options for authenticating that a user may choose from at the
453
+login screen. The pairs configured in this list map a user-friendly string to an
454
+authentication option, which may be one of:
455
+
456
+* The string ``credentials`` which forces horizon to present its own username
457
+  and password fields that the user will use to authenticate as a local keystone
458
+  user
459
+* The name of a protocol that you created in `Create a Protocol`_, such as
460
+  ``saml2`` or ``openid``, which will cause horizon to call keystone's `WebSSO
461
+  API without an Identity Provider`_ to authenticate the user
462
+* A string that maps to an Identity Provider and Protocol combination configured
463
+  in ``WEBSSO_IDP_MAPPING`` which will cause horizon to call keystone's `WebSSO
464
+  API specific to the given Identity Provider`_.
465
+
466
+.. code-block:: python
467
+
468
+   WEBSSO_CHOICES = (
469
+       ("credentials", _("Keystone Credentials")),
470
+       ("openid", _("OpenID Connect")),
471
+       ("saml2", _("Security Assertion Markup Language")),
472
+       ("myidp_openid", "Acme Corporation - OpenID Connect"),
473
+       ("myidp_saml2", "Acme Corporation - SAML2")
474
+   )
475
+
476
+   WEBSSO_IDP_MAPPING = {
477
+       "myidp_openid": ("myidp", "openid"),
478
+       "myidp_saml2": ("myidp", "saml2")
479
+   }
480
+
481
+The initial selection of the dropdown menu can also be configured:
482
+
483
+.. code-block:: python
484
+
485
+   WEBSSO_INITIAL_CHOICE = "credentials"
486
+
487
+Remember to restart the web server when finished configuring horizon:
488
+
489
+.. code-block:: console
490
+
491
+   # systemctl restart apache2
492
+
493
+.. _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
494
+.. _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
495
+
370 496
 Authenticating
371 497
 --------------
372 498
 
@@ -493,8 +619,10 @@ Configuring Metadata
493 619
 --------------------
494 620
 
495 621
 Since keystone is acting as a SAML Identity Provider, its metadata must be
496
-configured in the ``[saml]`` section of ``keystone.conf`` so that it can served
497
-by the `metadata API`_.
622
+configured in the ``[saml]`` section (not to be confused with an optional
623
+``[saml2]`` section which you may have configured in `Configure the Remote Id
624
+Attribute`_ while setting up keystone as Service Provider) of ``keystone.conf``
625
+so that it can served by the `metadata API`_.
498 626
 
499 627
 .. _metadata API: https://developer.openstack.org/api-ref/identity/v3-ext/index.html#retrieve-metadata-properties
500 628
 
@@ -627,4 +755,3 @@ to another cloud.
627 755
 .. include:: openidc.rst
628 756
 .. include:: mellon.rst
629 757
 .. include:: shibboleth.rst
630
-.. include:: websso.rst

+ 0
- 249
doc/source/admin/federation/websso.rst View File

@@ -1,249 +0,0 @@
1
-..
2
-      Licensed under the Apache License, Version 2.0 (the "License"); you may
3
-      not use this file except in compliance with the License. You may obtain
4
-      a copy of the License at
5
-
6
-      http://www.apache.org/licenses/LICENSE-2.0
7
-
8
-      Unless required by applicable law or agreed to in writing, software
9
-      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
10
-      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
11
-      License for the specific language governing permissions and limitations
12
-      under the License.
13
-
14
-------------------------------
15
-Setup Web Single Sign-On (SSO)
16
-------------------------------
17
-
18
-Keystone Changes
19
-----------------
20
-
21
-1. Update `trusted_dashboard` in keystone.conf.
22
-
23
-Specify URLs of trusted horizon servers. This value may be repeated
24
-multiple times. This setting ensures that keystone only sends token data back
25
-to trusted servers. This is performed as a precaution, specifically to
26
-prevent man-in-the-middle (MITM) attacks.
27
-
28
-.. code-block:: ini
29
-
30
-   [federation]
31
-   trusted_dashboard = http://acme.horizon.com/auth/websso/
32
-   trusted_dashboard = http://beta.horizon.com/auth/websso/
33
-
34
-2. Update httpd vhost file with websso information.
35
-
36
-The `/v3/auth/OS-FEDERATION/websso/<protocol>` and
37
-`/v3/auth/OS-FEDERATION/identity_providers/{idp_id}/protocols/{protocol_id}/websso`
38
-routes must be protected by the chosen httpd module. This is performed so the
39
-request that originates from horizon will use the same identity provider that
40
-is configured in keystone.
41
-
42
-.. WARNING::
43
-    By using the IdP specific route, a user will no longer leverage the Remote
44
-    ID of a specific Identity Provider, and will be unable to verify that the
45
-    Identity Provider is trusted, the mapping will remain as the only means to
46
-    controlling authorization.
47
-
48
-If `mod_shib` is used, then use the following as an example:
49
-
50
-.. code-block:: apache
51
-
52
-   <VirtualHost *:5000>
53
-
54
-       ...
55
-
56
-       <Location ~ "/v3/auth/OS-FEDERATION/websso/saml2">
57
-         AuthType shibboleth
58
-         Require valid-user
59
-         ShibRequestSetting requireSession 1
60
-         ShibRequireSession On
61
-         ShibExportAssertion Off
62
-       </Location>
63
-       <Location ~ "/v3/auth/OS-FEDERATION/identity_providers/samltest/protocols/saml2/websso">
64
-         AuthType shibboleth
65
-         Require valid-user
66
-       </Location>
67
-   </VirtualHost>
68
-
69
-If `mod_auth_openidc` is used, then use the following as an example:
70
-
71
-.. code-block:: apache
72
-
73
-   <VirtualHost *:5000>
74
-
75
-       OIDCRedirectURI https://sp.keystone.example.org/v3/auth/OS-FEDERATION/websso
76
-       OIDCRedirectURI https://sp.keystone.example.org/v3/auth/OS-FEDERATION/identity_providers/samltest/protocols/openid/websso
77
-
78
-       ...
79
-
80
-       <Location ~ "/v3/auth/OS-FEDERATION/websso/openid">
81
-         AuthType openid-connect
82
-         Require valid-user
83
-         ...
84
-       </Location>
85
-       <Location ~ "/v3/auth/OS-FEDERATION/identity_providers/samltest/protocols/openid/websso">
86
-         AuthType openid-connect
87
-         Require valid-user
88
-         ...
89
-       </Location>
90
-   </VirtualHost>
91
-
92
-If `mod_auth_kerb` is used, then use the following as an example:
93
-
94
-.. code-block:: apache
95
-
96
-   <VirtualHost *:5000>
97
-
98
-       ...
99
-
100
-       <Location ~ "/v3/auth/OS-FEDERATION/websso/kerberos">
101
-         AuthType Kerberos
102
-         AuthName "Acme Corporation"
103
-         KrbMethodNegotiate on
104
-         KrbMethodK5Passwd off
105
-         Krb5Keytab /etc/apache2/http.keytab
106
-         ...
107
-       </Location>
108
-       <Location ~ "/v3/auth/OS-FEDERATION/identity_providers/samltest/protocols/kerberos/websso">
109
-         AuthType Kerberos
110
-         AuthName "Acme Corporation"
111
-         KrbMethodNegotiate on
112
-         KrbMethodK5Passwd off
113
-         Krb5Keytab /etc/apache2/http.keytab
114
-         ...
115
-       </Location>
116
-   </VirtualHost>
117
-
118
-If `mod_auth_mellon` is used, then use the following as an example:
119
-
120
-.. code-block:: apache
121
-
122
-   <VirtualHost *:5000>
123
-
124
-       ...
125
-
126
-       <Location ~ "/v3/auth/OS-FEDERATION/websso/saml2">
127
-         AuthType Mellon
128
-         MellonEnable auth
129
-         Require valid-user
130
-         ...
131
-       </Location>
132
-       <Location ~ "/v3/auth/OS-FEDERATION/identity_providers/samltest/protocols/saml2/websso">
133
-         AuthType Mellon
134
-         MellonEnable auth
135
-         Require valid-user
136
-         ...
137
-       </Location>
138
-   </VirtualHost>
139
-
140
-.. NOTE::
141
-    If you are also using SSO via the API, don't forget to make the Location
142
-    settings match your configuration used for the keystone identity provider
143
-    location:
144
-    `/v3/OS-FEDERATION/identity_providers/<idp>/protocols/<protocol>/auth`
145
-
146
-3. Update `remote_id_attribute` in keystone.conf.
147
-
148
-A remote id attribute indicates the header to retrieve from the WSGI
149
-environment. This header contains information about the identity
150
-of the identity provider. For `mod_shib` this would be
151
-``Shib-Identity-Provider``, for `mod_auth_openidc`, this could be
152
-``HTTP_OIDC_ISS``.  For `mod_auth_mellon`, this could be ``MELLON_IDP``.
153
-
154
-It is recommended that this option be set on a per-protocol basis.
155
-
156
-.. code-block:: ini
157
-
158
-   [saml2]
159
-   remote_id_attribute = Shib-Identity-Provider
160
-   [openid]
161
-   remote_id_attribute = HTTP_OIDC_ISS
162
-
163
-Alternatively, a generic option may be set at the `[federation]` level.
164
-
165
-.. code-block:: ini
166
-
167
-   [federation]
168
-   remote_id_attribute = HTTP_OIDC_ISS
169
-
170
-4. Copy the `sso_callback_template.html
171
-<https://git.openstack.org/cgit/openstack/keystone/plain/etc/sso_callback_template.html>`__
172
-template into the location specified by `[federation]/sso_callback_template`.
173
-
174
-Horizon Changes
175
----------------
176
-
177
-.. NOTE::
178
-
179
-    Django OpenStack Auth version 1.2.0 or higher is required for these steps.
180
-
181
-    Identity provider and federation protocol specific webSSO is only available
182
-    in Django OpenStack Auth version 2.0.0 or higher.
183
-
184
-1. Set the `WEBSSO_ENABLED` option.
185
-
186
-Ensure the `WEBSSO_ENABLED` option is set to True in horizon's local_settings.py file,
187
-this will provide users with an updated login screen for horizon.
188
-
189
-.. code-block:: python
190
-
191
-   WEBSSO_ENABLED = True
192
-
193
-2. (Optional) Create a list of authentication methods with the
194
-   `WEBSSO_CHOICES` option.
195
-
196
-Within horizon's settings.py file, a list of supported authentication methods can be
197
-specified. The list includes Keystone federation protocols such as OpenID Connect and
198
-SAML, and also keys that map to specific identity provider and federation protocol
199
-combinations (as defined in `WEBSSO_IDP_MAPPING`). With the exception of ``credentials``
200
-which is reserved by horizon, and maps to the user name and password used by keystone's
201
-identity backend.
202
-
203
-.. code-block:: python
204
-
205
-   WEBSSO_CHOICES = (
206
-       ("credentials", _("Keystone Credentials")),
207
-       ("openid", _("OpenID Connect")),
208
-       ("saml2", _("Security Assertion Markup Language")),
209
-       ("acme_openid", "Acme Corporation - OpenID Connect"),
210
-       ("acme_saml2", "Acme Corporation - SAML2")
211
-   )
212
-
213
-3. (Optional) Create a dictionary of specific identity provider and federation
214
-   protocol combinations.
215
-
216
-A dictionary of specific identity provider and federation protocol combinations.
217
-From the selected authentication mechanism, the value will be looked up as keys
218
-in the dictionary. If a match is found, it will redirect the user to a identity
219
-provider and federation protocol specific WebSSO endpoint in keystone, otherwise
220
-it will use the value as the protocol_id when redirecting to the WebSSO by
221
-protocol endpoint.
222
-
223
-.. code-block:: python
224
-
225
-   WEBSSO_IDP_MAPPING = {
226
-       "acme_openid": ("acme", "openid"),
227
-       "acme_saml2": ("acme", "saml2")
228
-   }
229
-
230
-.. NOTE::
231
-
232
-    The value is expected to be a tuple formatted as: (<idp_id>, <protocol_id>).
233
-
234
-6. (Optional) Specify an initial choice with the `WEBSSO_INITIAL_CHOICE`
235
-   option.
236
-
237
-The list set by the `WEBSSO_CHOICES` option will be generated in a drop-down
238
-menu in the login screen. The setting `WEBSSO_INITIAL_CHOICE` will
239
-automatically set that choice to be highlighted by default.
240
-
241
-.. code-block:: python
242
-
243
-   WEBSSO_INITIAL_CHOICE = "credentials"
244
-
245
-7. Restart your web server:
246
-
247
-.. code-block:: console
248
-
249
-   # service apache2 restart

Loading…
Cancel
Save