From ec7f8b95b353ea1e172cc15b9703367f1edd0cc1 Mon Sep 17 00:00:00 2001 From: Colleen Murphy Date: Fri, 21 Dec 2018 20:17:53 -0800 Subject: [PATCH] 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 --- .../admin/federation/configure_federation.rst | 4 +- doc/source/admin/federation/openidc.rst | 137 +++++++++++------- 2 files changed, 87 insertions(+), 54 deletions(-) diff --git a/doc/source/admin/federation/configure_federation.rst b/doc/source/admin/federation/configure_federation.rst index 3ebde284ae..094229ee35 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: * For ``mod_auth_mellon``: the attribute name is configured with the ``MellonIdP`` parameter in the VirtualHost configuration, if set to e.g. ``IDP`` then use ``MELLON_IDP`` -* For ``mod_auth_openidc``: use ``HTTP_OIDC_ISS`` +* For ``mod_auth_openidc``: the attribute name is related to the + ``OIDCClaimPrefix`` parameter in the Apache configuration, if set to e.g. + ``OIDC-`` use ``HTTP_OIDC_ISS`` It is recommended that this option be set on a per-protocol basis by creating a new section named after the protocol: diff --git a/doc/source/admin/federation/openidc.rst b/doc/source/admin/federation/openidc.rst index ba34027660..c4d0186cf7 100644 --- a/doc/source/admin/federation/openidc.rst +++ b/doc/source/admin/federation/openidc.rst @@ -11,83 +11,114 @@ License for the specific language governing permissions and limitations under the License. --------------------- -Setup OpenID Connect --------------------- +------------------------- +Setting Up OpenID Connect +------------------------- -Configuring mod_auth_openidc ----------------------------- +See :ref:`keystone-as-sp` before proceeding with these OpenIDC-specific +instructions. -Federate Keystone (SP) and an external IdP using OpenID Connect (`mod_auth_openidc`_) +These examples use Google as an OpenID Connect Identity Provider. The Service +Provider must be added to the Identity Provider in the `Google API console`_. -.. _`mod_auth_openidc`: https://github.com/pingidentity/mod_auth_openidc +.. _Google API console: https://console.developers.google.com/ -To install `mod_auth_openidc` on Ubuntu, perform the following: +Configuring Apache HTTPD for mod_auth_openidc +--------------------------------------------- + +.. note:: + + You are advised to carefully examine the `mod_auth_openidc documentation`_. + +.. _mod_auth_openidc documentation: https://github.com/zmartzone/mod_auth_openidc#how-to-use-it + +Install the Module +~~~~~~~~~~~~~~~~~~ + +Install the Apache module package. For example, on Ubuntu: .. code-block:: console # apt-get install libapache2-mod-auth-openidc -This module is available for other distributions (Fedora/CentOS/Red Hat) from: -https://github.com/pingidentity/mod_auth_openidc/releases +The package and module name will differ between distributions. -Enable the auth_openidc module: +Configure mod_auth_openidc +~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. code-block:: console - - # a2enmod auth_openidc - -In the keystone vhost file, locate the virtual host entry and add the following -entries for OpenID Connect: +In the Apache configuration for the keystone VirtualHost, set the following OIDC +options: .. code-block:: apache - + OIDCClaimPrefix "OIDC-" + OIDCResponseType "id_token" + OIDCScope "openid email profile" + OIDCProviderMetadataURL https://accounts.google.com/.well-known/openid-configuration + OIDCClientID + OIDCClientSecret + OIDCCryptoPassphrase + OIDCRedirectURI https://sp.keystone.example.org/v3/OS-FEDERATION/identity_providers/google/protocols/openid/auth - ... +``OIDCScope`` is the list of attributes that the user will authorize the +Identity Provider to send to the Service Provider. ``OIDCClientID`` and +``OIDCClientSecret`` must be generated and obtained from the Identity Provider. +``OIDCProviderMetadataURL`` is a URL from which the Service Provider will fetch +the Identity Provider's metadata. ``OIDCRedirectURI`` is a vanity URL that must +point to a protected path that does not have any content, such as an extension +of the protected federated auth path. - OIDCClaimPrefix "OIDC-" - OIDCResponseType "id_token" - OIDCScope "openid email profile" - OIDCProviderMetadataURL - OIDCClientID - OIDCClientSecret - OIDCCryptoPassphrase openstack - OIDCRedirectURI https://sp.keystone.example.org/v3/OS-FEDERATION/identity_providers//protocols/openid/auth +.. note:: - - AuthType openid-connect - Require valid-user - LogLevel debug - - + If using a mod_wsgi version less than 4.3.0, then the `OIDCClaimPrefix` must + be specified to have only alphanumerics or a dash ("-"). This is because + `mod_wsgi blocks headers that do not fit this criteria`_. -Note an example of an `OIDCProviderMetadataURL` instance is: https://accounts.google.com/.well-known/openid-configuration -If not using `OIDCProviderMetadataURL`, then the following attributes -must be specified: `OIDCProviderIssuer`, `OIDCProviderAuthorizationEndpoint`, -`OIDCProviderTokenEndpoint`, `OIDCProviderTokenEndpointAuth`, -`OIDCProviderUserInfoEndpoint`, and `OIDCProviderJwksUri` +.. _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 -Note, if using a mod_wsgi version less than 4.3.0, then the `OIDCClaimPrefix` -must be specified to have only alphanumerics or a dash ("-"). This is because -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 -for more details +Configure Protected Endpoints +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Once you are done, restart your Apache daemon: +Configure each protected path to use the ``openid-connect`` AuthType: + +.. code-block:: apache + + + Require valid-user + AuthType openid-connect + + +Do the same for the WebSSO auth paths if using horizon: + +.. code-block:: apache + + + Require valid-user + AuthType openid-connect + + + Require valid-user + AuthType openid-connect + + +Remember to reload Apache after altering the VirtualHost: .. code-block:: console - # service apache2 restart + # systemctl reload apache2 -Tips ----- +.. note:: -1. When creating a `mapping`_, note that the 'remote' attributes will be prefixed, - with `HTTP_`, so for instance, if you set OIDCClaimPrefix to `OIDC-`, then a - typical remote value to check for is: `HTTP_OIDC_ISS`. + When creating `mapping rules`_, in keystone, note that the 'remote' + attributes will be prefixed, with ``HTTP_``, so for instance, if you set + ``OIDCClaimPrefix`` to ``OIDC-``, then a typical remote value to check for + is: ``HTTP_OIDC_ISS``. -2. Don't forget to add openid as an [auth] plugin in keystone.conf, see - `Configure authentication drivers in keystone.conf`_ +.. _`mapping rules`: configure_federation.html#mapping -.. _`Configure authentication drivers in keystone.conf`: federated_identity.html#configure-authentication-drivers-in-keystone-conf -.. _`mapping`: configure_federation.html#mapping +Continue configuring keystone +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +`Continue configuring keystone`_ + +.. _Continue configuring keystone: configure_federation.html#configuring-keystone