summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorZuul <zuul@review.openstack.org>2019-01-09 03:16:21 +0000
committerGerrit Code Review <review@openstack.org>2019-01-09 03:16:21 +0000
commit921da3831678be24a2946c57831b6755716a61b7 (patch)
tree5b7b55108ce47e01889e4dc7d7e3b488044bf0f4
parent0ffc236fb11cdfe748694ce60dfd0c41b4ca6e20 (diff)
parentec7f8b95b353ea1e172cc15b9703367f1edd0cc1 (diff)
Merge "Enhance the openidc guide"
-rw-r--r--doc/source/admin/federation/configure_federation.rst4
-rw-r--r--doc/source/admin/federation/openidc.rst135
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`: https://github.com/pingidentity/mod_auth_openidc 24.. _Google API console: https://console.developers.google.com/
24 25
25To install `mod_auth_openidc` on Ubuntu, perform the following: 26Configuring 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
31This module is available for other distributions (Fedora/CentOS/Red Hat) from: 33.. _mod_auth_openidc documentation: https://github.com/zmartzone/mod_auth_openidc#how-to-use-it
32https://github.com/pingidentity/mod_auth_openidc/releases
33 34
34Enable the auth_openidc module: 35Install the Module
36~~~~~~~~~~~~~~~~~~
37
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
43
44The package and module name will differ between distributions.
45
46Configure mod_auth_openidc
47~~~~~~~~~~~~~~~~~~~~~~~~~~
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 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
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.
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-" 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
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
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: https://accounts.google.com/.well-known/openid-configuration 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 http://modwsgi.readthedocs.org/en/latest/release-notes/version-4.3.0.html#bugs-fixed 86 <Location /v3/OS-FEDERATION/identity_providers/google/protocols/openid/auth>
74for more details 87 Require valid-user
88 AuthType openid-connect
89 </Location>
90
91Do 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
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
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
82Tips 117.. _`mapping rules`: configure_federation.html#mapping
83----
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