openstack
/
keystone
Code Issues Proposed changes

Merge "Enhance the openidc guide"

This commit is contained in:
Zuul 2019-01-09 03:16:21 +00:00 committed by Gerrit Code Review
parent 0ffc236fb1 ec7f8b95b3
commit 921da38316
2 changed files with 87 additions and 54 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
doc/source/admin/federation/configure_federation.rst
View File

@ -375,7 +375,9 @@ is decided by the auth module choice:
* For ``mod_auth_mellon``: the attribute name is configured with the * For ``mod_auth_mellon``: the attribute name is configured with the
``MellonIdP`` parameter in the VirtualHost configuration, if set to e.g. ``MellonIdP`` parameter in the VirtualHost configuration, if set to e.g.
``IDP`` then use ``MELLON_IDP`` ``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 It is recommended that this option be set on a per-protocol basis by creating a
new section named after the protocol: new section named after the protocol:

137
doc/source/admin/federation/openidc.rst
View File

@ -11,83 +11,114 @@
License for the specific language governing permissions and limitations License for the specific language governing permissions and limitations
under the License. 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 .. code-block:: console
# apt-get install libapache2-mod-auth-openidc # apt-get install libapache2-mod-auth-openidc
This module is available for other distributions (Fedora/CentOS/Red Hat) from: The package and module name will differ between distributions.
https://github.com/pingidentity/mod_auth_openidc/releases
Enable the auth_openidc module: Configure mod_auth_openidc
~~~~~~~~~~~~~~~~~~~~~~~~~~
.. code-block:: console In the Apache configuration for the keystone VirtualHost, set the following OIDC
options:
# a2enmod auth_openidc
In the keystone vhost file, locate the virtual host entry and add the following
entries for OpenID Connect:
.. code-block:: apache .. code-block:: apache
<VirtualHost *:5000> OIDCClaimPrefix "OIDC-"
OIDCResponseType "id_token"
OIDCScope "openid email profile"
OIDCProviderMetadataURL https://accounts.google.com/.well-known/openid-configuration
OIDCClientID <openid_client_id>
OIDCClientSecret <openid_client_secret>
OIDCCryptoPassphrase <random string>
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-" .. note::
OIDCResponseType "id_token"
OIDCScope "openid email profile"
OIDCProviderMetadataURL <url_of_provider_metadata>
OIDCClientID <openid_client_id>
OIDCClientSecret <openid_client_secret>
OIDCCryptoPassphrase openstack
OIDCRedirectURI https://sp.keystone.example.org/v3/OS-FEDERATION/identity_providers/<idp_id>/protocols/openid/auth
<LocationMatch /v3/OS-FEDERATION/identity_providers/.*?/protocols/openid/auth> If using a mod_wsgi version less than 4.3.0, then the `OIDCClaimPrefix` must
AuthType openid-connect be specified to have only alphanumerics or a dash ("-"). This is because
Require valid-user `mod_wsgi blocks headers that do not fit this criteria`_.
LogLevel debug
</LocationMatch>
</VirtualHost>
Note an example of an `OIDCProviderMetadataURL` instance is: https://accounts.google.com/.well-known/openid-configuration .. _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
If not using `OIDCProviderMetadataURL`, then the following attributes
must be specified: `OIDCProviderIssuer`, `OIDCProviderAuthorizationEndpoint`,
`OIDCProviderTokenEndpoint`, `OIDCProviderTokenEndpointAuth`,
`OIDCProviderUserInfoEndpoint`, and `OIDCProviderJwksUri`
Note, if using a mod_wsgi version less than 4.3.0, then the `OIDCClaimPrefix` Configure Protected Endpoints
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
Once you are done, restart your Apache daemon: Configure each protected path to use the ``openid-connect`` AuthType:
.. code-block:: apache
<Location /v3/OS-FEDERATION/identity_providers/google/protocols/openid/auth>
Require valid-user
AuthType openid-connect
</Location>
Do the same for the WebSSO auth paths if using horizon:
.. code-block:: apache
<Location /v3/auth/OS-FEDERATION/websso/openid>
Require valid-user
AuthType openid-connect
</Location>
<Location /v3/auth/OS-FEDERATION/identity_providers/google/protocols/openid/websso>
Require valid-user
AuthType openid-connect
</Location>
Remember to reload Apache after altering the VirtualHost:
.. code-block:: console .. code-block:: console
# service apache2 restart # systemctl reload apache2
Tips .. note::
----
1. When creating a `mapping`_, note that the 'remote' attributes will be prefixed, When creating `mapping rules`_, in keystone, note that the 'remote'
with `HTTP_`, so for instance, if you set OIDCClaimPrefix to `OIDC-`, then a attributes will be prefixed, with ``HTTP_``, so for instance, if you set
typical remote value to check for is: `HTTP_OIDC_ISS`. ``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 .. _`mapping rules`: configure_federation.html#mapping
`Configure authentication drivers in keystone.conf`_
.. _`Configure authentication drivers in keystone.conf`: federated_identity.html#configure-authentication-drivers-in-keystone-conf Continue configuring keystone
.. _`mapping`: configure_federation.html#mapping ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
`Continue configuring keystone`_
.. _Continue configuring keystone: configure_federation.html#configuring-keystone