Browse Source

Enhance the openidc guide

Update, reorganize and clean up the openidc guide. Use Google as a
concrete IdP example. Use the systemctl command to modernize the service
management commands. Add examples of configuring all required endpoints
in Apache to mirror the new section on configuring protected endpoints
in the main guide and replace the lost examples from the consolidated
WebSSO guide. Remove use of ``a2enmod`` since the Mellon module is
automatically enabled by the package on all supported distros.

Closes-bug: #1793374

Change-Id: Ie5dc4899beff77f121cc62bc8d56763c7671ecc3
tags/15.0.0.0rc1
Colleen Murphy 5 months ago
parent
commit
ec7f8b95b3

+ 3
- 1
doc/source/admin/federation/configure_federation.rst View File

@@ -375,7 +375,9 @@ is decided by the auth module choice:
375 375
 * For ``mod_auth_mellon``: the attribute name is configured with the
376 376
   ``MellonIdP`` parameter in the VirtualHost configuration, if set to e.g.
377 377
   ``IDP`` then use ``MELLON_IDP``
378
-* For ``mod_auth_openidc``: use ``HTTP_OIDC_ISS``
378
+* For ``mod_auth_openidc``: the attribute name is related to the
379
+  ``OIDCClaimPrefix`` parameter in the Apache configuration, if set to e.g.
380
+  ``OIDC-`` use ``HTTP_OIDC_ISS``
379 381
 
380 382
 It is recommended that this option be set on a per-protocol basis by creating a
381 383
 new section named after the protocol:

+ 83
- 52
doc/source/admin/federation/openidc.rst View File

@@ -11,83 +11,114 @@
11 11
       License for the specific language governing permissions and limitations
12 12
       under the License.
13 13
 
14
---------------------
15
-Setup OpenID Connect
16
---------------------
14
+-------------------------
15
+Setting Up OpenID Connect
16
+-------------------------
17 17
 
18
-Configuring mod_auth_openidc
19
-----------------------------
18
+See :ref:`keystone-as-sp` before proceeding with these OpenIDC-specific
19
+instructions.
20 20
 
21
-Federate Keystone (SP) and an external IdP using OpenID Connect (`mod_auth_openidc`_)
21
+These examples use Google as an OpenID Connect Identity Provider. The Service
22
+Provider must be added to the Identity Provider in the `Google API console`_.
22 23
 
23
-.. _`mod_auth_openidc`: https://github.com/pingidentity/mod_auth_openidc
24
+.. _Google API console: https://console.developers.google.com/
24 25
 
25
-To install `mod_auth_openidc` on Ubuntu, perform the following:
26
+Configuring Apache HTTPD for mod_auth_openidc
27
+---------------------------------------------
26 28
 
27
-.. code-block:: console
29
+.. note::
28 30
 
29
-   # apt-get install libapache2-mod-auth-openidc
31
+   You are advised to carefully examine the `mod_auth_openidc documentation`_.
30 32
 
31
-This module is available for other distributions (Fedora/CentOS/Red Hat) from:
32
-https://github.com/pingidentity/mod_auth_openidc/releases
33
+.. _mod_auth_openidc documentation: https://github.com/zmartzone/mod_auth_openidc#how-to-use-it
33 34
 
34
-Enable the auth_openidc module:
35
+Install the Module
36
+~~~~~~~~~~~~~~~~~~
37
+
38
+Install the Apache module package. For example, on Ubuntu:
35 39
 
36 40
 .. code-block:: console
37 41
 
38
-   # a2enmod auth_openidc
42
+   # apt-get install libapache2-mod-auth-openidc
43
+
44
+The package and module name will differ between distributions.
45
+
46
+Configure mod_auth_openidc
47
+~~~~~~~~~~~~~~~~~~~~~~~~~~
39 48
 
40
-In the keystone vhost file, locate the virtual host entry and add the following
41
-entries for OpenID Connect:
49
+In the Apache configuration for the keystone VirtualHost, set the following OIDC
50
+options:
42 51
 
43 52
 .. code-block:: apache
44 53
 
45
-   <VirtualHost *:5000>
54
+   OIDCClaimPrefix "OIDC-"
55
+   OIDCResponseType "id_token"
56
+   OIDCScope "openid email profile"
57
+   OIDCProviderMetadataURL https://accounts.google.com/.well-known/openid-configuration
58
+   OIDCClientID <openid_client_id>
59
+   OIDCClientSecret <openid_client_secret>
60
+   OIDCCryptoPassphrase <random string>
61
+   OIDCRedirectURI https://sp.keystone.example.org/v3/OS-FEDERATION/identity_providers/google/protocols/openid/auth
62
+
63
+``OIDCScope`` is the list of attributes that the user will authorize the
64
+Identity Provider to send to the Service Provider. ``OIDCClientID`` and
65
+``OIDCClientSecret`` must be generated and obtained from the Identity Provider.
66
+``OIDCProviderMetadataURL`` is a URL from which the Service Provider will fetch
67
+the Identity Provider's metadata. ``OIDCRedirectURI`` is a vanity URL that must
68
+point to a protected path that does not have any content, such as an extension
69
+of the protected federated auth path.
70
+
71
+.. note::
46 72
 
47
-       ...
73
+   If using a mod_wsgi version less than 4.3.0, then the `OIDCClaimPrefix` must
74
+   be specified to have only alphanumerics or a dash ("-"). This is because
75
+   `mod_wsgi blocks headers that do not fit this criteria`_.
48 76
 
49
-       OIDCClaimPrefix "OIDC-"
50
-       OIDCResponseType "id_token"
51
-       OIDCScope "openid email profile"
52
-       OIDCProviderMetadataURL <url_of_provider_metadata>
53
-       OIDCClientID <openid_client_id>
54
-       OIDCClientSecret <openid_client_secret>
55
-       OIDCCryptoPassphrase openstack
56
-       OIDCRedirectURI https://sp.keystone.example.org/v3/OS-FEDERATION/identity_providers/<idp_id>/protocols/openid/auth
77
+.. _mod_wsgi blocks headers that do not fit this criteria: http://modwsgi.readthedocs.org/en/latest/release-notes/version-4.3.0.html#bugs-fixed
57 78
 
58
-       <LocationMatch /v3/OS-FEDERATION/identity_providers/.*?/protocols/openid/auth>
59
-         AuthType openid-connect
60
-         Require valid-user
61
-         LogLevel debug
62
-       </LocationMatch>
63
-   </VirtualHost>
79
+Configure Protected Endpoints
80
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
64 81
 
65
-Note an example of an `OIDCProviderMetadataURL` instance is: https://accounts.google.com/.well-known/openid-configuration
66
-If not using `OIDCProviderMetadataURL`, then the following attributes
67
-must be specified: `OIDCProviderIssuer`, `OIDCProviderAuthorizationEndpoint`,
68
-`OIDCProviderTokenEndpoint`, `OIDCProviderTokenEndpointAuth`,
69
-`OIDCProviderUserInfoEndpoint`, and `OIDCProviderJwksUri`
82
+Configure each protected path to use the ``openid-connect`` AuthType:
70 83
 
71
-Note, if using a mod_wsgi version less than 4.3.0, then the `OIDCClaimPrefix`
72
-must be specified to have only alphanumerics or a dash ("-"). This is because
73
-mod_wsgi blocks headers that do not fit this criteria. See http://modwsgi.readthedocs.org/en/latest/release-notes/version-4.3.0.html#bugs-fixed
74
-for more details
84
+.. code-block:: apache
85
+
86
+   <Location /v3/OS-FEDERATION/identity_providers/google/protocols/openid/auth>
87
+       Require valid-user
88
+       AuthType openid-connect
89
+   </Location>
90
+
91
+Do the same for the WebSSO auth paths if using horizon:
92
+
93
+.. code-block:: apache
94
+
95
+   <Location /v3/auth/OS-FEDERATION/websso/openid>
96
+       Require valid-user
97
+       AuthType openid-connect
98
+   </Location>
99
+   <Location /v3/auth/OS-FEDERATION/identity_providers/google/protocols/openid/websso>
100
+       Require valid-user
101
+       AuthType openid-connect
102
+   </Location>
75 103
 
76
-Once you are done, restart your Apache daemon:
104
+Remember to reload Apache after altering the VirtualHost:
77 105
 
78 106
 .. code-block:: console
79 107
 
80
-   # service apache2 restart
108
+   # systemctl reload apache2
109
+
110
+.. note::
111
+
112
+   When creating `mapping rules`_, in keystone, note that the 'remote'
113
+   attributes will be prefixed, with ``HTTP_``, so for instance, if you set
114
+   ``OIDCClaimPrefix`` to ``OIDC-``, then a typical remote value to check for
115
+   is: ``HTTP_OIDC_ISS``.
81 116
 
82
-Tips
83
-----
117
+.. _`mapping rules`: configure_federation.html#mapping
84 118
 
85
-1. When creating a `mapping`_, note that the 'remote' attributes will be prefixed,
86
-   with `HTTP_`, so for instance, if you set OIDCClaimPrefix to `OIDC-`, then a
87
-   typical remote value to check for is: `HTTP_OIDC_ISS`.
119
+Continue configuring keystone
120
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
88 121
 
89
-2. Don't forget to add openid as an [auth] plugin in keystone.conf, see
90
-   `Configure authentication drivers in keystone.conf`_
122
+`Continue configuring keystone`_
91 123
 
92
-.. _`Configure authentication drivers in keystone.conf`: federated_identity.html#configure-authentication-drivers-in-keystone-conf
93
-.. _`mapping`: configure_federation.html#mapping
124
+.. _Continue configuring keystone: configure_federation.html#configuring-keystone

Loading…
Cancel
Save