diff options
authorColleen Murphy <>2018-12-21 20:17:53 -0800
committerColleen Murphy <>2019-01-07 16:56:28 +0100
commitec7f8b95b353ea1e172cc15b9703367f1edd0cc1 (patch)
parentdcb9d8d084a60c1e8f83adf0a9ae84df9cc85ebe (diff)
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
Notes (review): Code-Review+2: Lance Bragstad <> Code-Review+2: wangxiyuan <> Workflow+1: wangxiyuan <> Verified+2: Zuul Submitted-by: Zuul Submitted-at: Wed, 09 Jan 2019 03:16:21 +0000 Reviewed-on: Project: openstack/keystone Branch: refs/heads/master
2 files changed, 86 insertions, 53 deletions
diff --git a/doc/source/admin/federation/configure_federation.rst b/doc/source/admin/federation/configure_federation.rst
index 3ebde28..094229e 100644
--- a/doc/source/admin/federation/configure_federation.rst
+++ b/doc/source/admin/federation/configure_federation.rst
@@ -375,7 +375,9 @@ is decided by the auth module choice:
375* For ``mod_auth_mellon``: the attribute name is configured with the 375* For ``mod_auth_mellon``: the attribute name is configured with the
376 ``MellonIdP`` parameter in the VirtualHost configuration, if set to e.g. 376 ``MellonIdP`` parameter in the VirtualHost configuration, if set to e.g.
377 ``IDP`` then use ``MELLON_IDP`` 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
380It is recommended that this option be set on a per-protocol basis by creating a 382It is recommended that this option be set on a per-protocol basis by creating a
381new section named after the protocol: 383new section named after the protocol:
diff --git a/doc/source/admin/federation/openidc.rst b/doc/source/admin/federation/openidc.rst
index ba34027..c4d0186 100644
--- a/doc/source/admin/federation/openidc.rst
+++ b/doc/source/admin/federation/openidc.rst
@@ -11,83 +11,114 @@
11 License for the specific language governing permissions and limitations 11 License for the specific language governing permissions and limitations
12 under the License. 12 under the License.
13 13
14-------------------- 14-------------------------
15Setup OpenID Connect 15Setting Up OpenID Connect
16-------------------- 16-------------------------
17 17
18Configuring mod_auth_openidc 18See :ref:`keystone-as-sp` before proceeding with these OpenIDC-specific
19---------------------------- 19instructions.
20 20
21Federate Keystone (SP) and an external IdP using OpenID Connect (`mod_auth_openidc`_) 21These examples use Google as an OpenID Connect Identity Provider. The Service
22Provider must be added to the Identity Provider in the `Google API console`_.
22 23
23.. _`mod_auth_openidc`: 24.. _Google API console:
24 25
25To install `mod_auth_openidc` on Ubuntu, perform the following: 26Configuring Apache HTTPD for mod_auth_openidc
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
31This module is available for other distributions (Fedora/CentOS/Red Hat) from: 33.. _mod_auth_openidc documentation:
33 34
34Enable the auth_openidc module: 35Install the Module
38Install the Apache module package. For example, on Ubuntu:
35 39
36.. code-block:: console 40.. code-block:: console
37 41
38 # a2enmod auth_openidc 42 # apt-get install libapache2-mod-auth-openidc
44The package and module name will differ between distributions.
46Configure mod_auth_openidc
39 48
40In the keystone vhost file, locate the virtual host entry and add the following 49In the Apache configuration for the keystone VirtualHost, set the following OIDC
41entries for OpenID Connect: 50options:
42 51
43.. code-block:: apache 52.. code-block:: apache
44 53
45 <VirtualHost *:5000> 54 OIDCClaimPrefix "OIDC-"
55 OIDCResponseType "id_token"
56 OIDCScope "openid email profile"
57 OIDCProviderMetadataURL
58 OIDCClientID <openid_client_id>
59 OIDCClientSecret <openid_client_secret>
60 OIDCCryptoPassphrase <random string>
61 OIDCRedirectURI
63``OIDCScope`` is the list of attributes that the user will authorize the
64Identity 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
67the Identity Provider's metadata. ``OIDCRedirectURI`` is a vanity URL that must
68point to a protected path that does not have any content, such as an extension
69of the protected federated auth path.
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-" 77.. _mod_wsgi blocks headers that do not fit this criteria:
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<idp_id>/protocols/openid/auth
57 78
58 <LocationMatch /v3/OS-FEDERATION/identity_providers/.*?/protocols/openid/auth> 79Configure Protected Endpoints
59 AuthType openid-connect 80~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
60 Require valid-user
61 LogLevel debug
62 </LocationMatch>
63 </VirtualHost>
64 81
65Note an example of an `OIDCProviderMetadataURL` instance is: 82Configure each protected path to use the ``openid-connect`` AuthType:
66If not using `OIDCProviderMetadataURL`, then the following attributes
67must be specified: `OIDCProviderIssuer`, `OIDCProviderAuthorizationEndpoint`,
68`OIDCProviderTokenEndpoint`, `OIDCProviderTokenEndpointAuth`,
69`OIDCProviderUserInfoEndpoint`, and `OIDCProviderJwksUri`
70 83
71Note, if using a mod_wsgi version less than 4.3.0, then the `OIDCClaimPrefix` 84.. code-block:: apache
72must be specified to have only alphanumerics or a dash ("-"). This is because 85
73mod_wsgi blocks headers that do not fit this criteria. See 86 <Location /v3/OS-FEDERATION/identity_providers/google/protocols/openid/auth>
74for more details 87 Require valid-user
88 AuthType openid-connect
89 </Location>
91Do the same for the WebSSO auth paths if using horizon:
93.. code-block:: apache
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
76Once you are done, restart your Apache daemon: 104Remember to reload Apache after altering the VirtualHost:
77 105
78.. code-block:: console 106.. code-block:: console
79 107
80 # service apache2 restart 108 # systemctl reload apache2
110.. note::
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
82Tips 117.. _`mapping rules`: configure_federation.html#mapping
84 118
851. When creating a `mapping`_, note that the 'remote' attributes will be prefixed, 119Continue configuring keystone
86 with `HTTP_`, so for instance, if you set OIDCClaimPrefix to `OIDC-`, then a 120~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
87 typical remote value to check for is: `HTTP_OIDC_ISS`.
88 121
892. Don't forget to add openid as an [auth] plugin in keystone.conf, see 122`Continue configuring keystone`_
90 `Configure authentication drivers in keystone.conf`_
91 123
92.. _`Configure authentication drivers in keystone.conf`: federated_identity.html#configure-authentication-drivers-in-keystone-conf 124.. _Continue configuring keystone: configure_federation.html#configuring-keystone
93.. _`mapping`: configure_federation.html#mapping