Browse Source

Add section on configuring protected auth paths

Without this change, the federation guide does not do a good job of
explaining which URL paths should be protected by a federation-capable
auth module and why. Instead, the SP-specific guides give code samples
with no context, which makes it confusing to understand how to modify
the paths in the examples to fit one's own deployment. This change adds
that introduction.

Partial-bug: #1793374

Change-Id: I5cf940e0c54e5dd89cd3db810f8b5889a8ddce2e
tags/15.0.0.0rc1
Colleen Murphy 5 months ago
parent
commit
708d3f4d59
1 changed files with 77 additions and 0 deletions
  1. 77
    0
      doc/source/admin/federation/configure_federation.rst

+ 77
- 0
doc/source/admin/federation/configure_federation.rst View File

@@ -241,6 +241,83 @@ the installation guides for running keystone behind Apache for `SUSE`_,
241 241
 .. _`RedHat`: ../../install/keystone-install-rdo.html#configure-the-apache-http-server
242 242
 .. _`Ubuntu`: ../../install/keystone-install-ubuntu.html#configure-the-apache-http-server
243 243
 
244
+Configure protected endpoints
245
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
246
+
247
+There is a minimum of one endpoint that must be protected in the VirtualHost
248
+configuration for the keystone service:
249
+
250
+.. code-block:: apache
251
+
252
+   <Location /v3/OS-FEDERATION/identity_providers/IDENTITYPROVIDER/protocols/PROTOCOL/auth>
253
+     Require valid-user
254
+     AuthType [...]
255
+     ...
256
+   </Location>
257
+
258
+This is the endpoint for federated users to request an unscoped token.
259
+
260
+If configuring WebSSO, you should also protect one or both of the following
261
+endpoints:
262
+
263
+.. code-block:: apache
264
+
265
+   <Location /v3/auth/OS-FEDERATION/websso/PROTOCOL>
266
+     Require valid-user
267
+     AuthType [...]
268
+     ...
269
+   </Location>
270
+   <Location /v3/auth/OS-FEDERATION/identity_providers/IDENTITYPROVIDER/protocols/PROTOCOL/websso>
271
+     Require valid-user
272
+     AuthType [...]
273
+     ...
274
+   </Location>
275
+
276
+The first example only specifies a protocol, and keystone will use the incoming
277
+remote ID to determine the Identity Provider. The second specifies the Identity
278
+Provider directly, which must then be supplied to horizon when configuring
279
+`horizon for WebSSO`_.
280
+
281
+The path must exactly match the path that will be used to access the keystone
282
+service. For example, if the identity provider you created in `Create an
283
+Identity Provider`_ is ``samltest`` and the protocol you created in `Create a
284
+Protocol`_ is ``saml2``, then the Locations will be:
285
+
286
+.. code-block:: apache
287
+
288
+   <Location /v3/OS-FEDERATION/identity_providers/samltest/protocols/saml2/auth>
289
+     Require valid-user
290
+     AuthType [...]
291
+     ...
292
+   </Location>
293
+   <Location /v3/auth/OS-FEDERATION/websso/saml2>
294
+     Require valid-user
295
+     AuthType [...]
296
+     ...
297
+   </Location>
298
+   <Location /v3/auth/OS-FEDERATION/identity_providers/samltest/protocols/saml2/websso>
299
+     Require valid-user
300
+     AuthType [...]
301
+     ...
302
+   </Location>
303
+
304
+However, if you have configured the keystone service to use a virtual path such as
305
+``/identity``, that part of the path should be included:
306
+
307
+.. code-block:: apache
308
+
309
+   <Location /identity/v3/OS-FEDERATION/identity_providers/samltest/protocols/saml2/auth>
310
+     Require valid-user
311
+     AuthType [...]
312
+     ...
313
+   </Location>
314
+   ...
315
+
316
+.. _horizon for WebSSO: websso.html
317
+
318
+Configure the auth module
319
+~~~~~~~~~~~~~~~~~~~~~~~~~
320
+
244 321
 If your Identity Provider is a SAML IdP, there are two main Apache modules that
245 322
 can be used as a SAML Service Provider: `mod_shib` and `mod_auth_mellon`. For
246 323
 an OpenID Connect Identity Provider, `mod_auth_openidc` is used. You can also

Loading…
Cancel
Save