Browse Source

Merge "Enhance the openidc guide"

tags/15.0.0.0rc1
Zuul 5 months ago
parent
commit
921da38316

+ 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