openstack/keystone
Code Issues Proposed changes

extend docs explaining OIDC

Browse Source 
OpenID Connect has specific terms for different parts so add those to
the documentation or use them when the wrong term was used. Added some
more expanded details around the different settings and how they work.
mod_auth_openidc takes lists in claims and when it converts them to a
header it uses a comma as its delimiter by default. But keystone uses ;
as it's delimiter when using a field in a mapping as a list. So the user
must configure mod_auth_openidc to use a ; instead of a ,

Change-Id: I3c44ed0937679f01d554b2fa74c9916d54c68464
This commit is contained in:
Doug Goldstein
2024-09-13 12:52:35 -05:00
parent 97431ec99b
commit bc8bdce77e
3 changed files with 39 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
devstack/files/oidc/apache_oidc.conf
View File

@@ -4,6 +4,7 @@ OIDCOAuthSSLValidateServer Off
OIDCCookieSameSite On
OIDCClaimPrefix "OIDC-"
OIDCClaimDelimiter ";"
OIDCResponseType "id_token"
OIDCScope "openid email profile"
OIDCProviderMetadataURL "%OIDC_METADATA_URL%"

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

@@ -62,8 +62,8 @@ information and use them consistently throughout your configuration:
You will also need to decide what HTTPD module to use as a Service Provider.
This guide provides examples for ``mod_shib`` and ``mod_auth_mellon`` as SAML
service providers, and ``mod_auth_openidc`` as an OpenID Connect Service
Provider.
service providers, and ``mod_auth_openidc`` as an OpenID Connect Relying
Party.
.. note::

39
doc/source/admin/federation/openidc.inc
View File

@@ -22,9 +22,28 @@ Setting Up OpenID Connect
See :ref:`keystone-as-sp` before proceeding with these OpenIDC-specific
instructions.
These examples use Google as an OpenID Connect Identity Provider. The Service
When using OpenID Connect, you must have a third party `OpenID Provider or
Identity Provider`_. Some examples of OpenID Connect Providers are Google,
Keycloak, Microsoft Entra, and GitLab. Keystone will use `mod_auth_openidc`_
to enable Keystone to act as an OpenID Connect Relying Party, which is
the name of an application that depends on an OpenID Connect Provider for
identity. You must add an OpenID Connect Client representing the Keystone
Service Provider in your OpenID Connect Provider.
Claims are pieces of user details or attributes provided by the OpenID
Connect Provider to the OpenID Connect Relying Party. Claims can be
retrieved from the ID token or from the UserInfo endpoint. Claims are
requested by specifying scopes, which map to sets of claims.
For the purposes of consistency with the rest of the Keystone documentation,
the term Service Provider will be used which means Keystone acting as
a Service Provider and is equivilent to OpenID Connect Relying Party.
These examples use Google as an OpenID Connect Provider. The Service
Provider must be added to the Identity Provider in the `Google API console`_.
.. _OpenID Provider or Identity Provider: https://openid.net/developers/how-connect-works/
.. _mod_auth_openidc: https://github.com/OpenIDC/mod_auth_openidc
.. _Google API console: https://console.developers.google.com/
Configuring Apache HTTPD for mod_auth_openidc
@@ -56,6 +75,7 @@ options:
.. code-block:: apache
OIDCClaimPrefix "OIDC-"
OIDCClaimDelimiter ";"
OIDCResponseType "id_token"
OIDCScope "openid email profile"
OIDCProviderMetadataURL https://accounts.google.com/.well-known/openid-configuration
@@ -65,9 +85,21 @@ options:
OIDCCryptoPassphrase <random string>
OIDCRedirectURI https://sp.keystone.example.org/v3/redirect_uri
``OIDCScope`` is the list of attributes that the user will authorize the
``OIDCClaimPrefix`` prefixes all claims with the value, which will then
be prefixed with ``HTTP_`` when presented to Keystone, with dashes ("-")
converted to underscores ("_") and uppercased. Resulting in the ``iss`` claim
being presented to Keystone as ``HTTP_OIDC_ISS`` using the ``OIDCClaimPrefix``
from above. Claims are pieces of JSON data but Apache only forwards on string
data to Keystone. So by default lists are converted to comma (",") separated
strings while Keystone's mapping code expects them to be semi-colon (";")
separated. To properly support this set the ``OIDCClaimDelimiter`` to utilize
semi-colons (";"). ``OIDCResponseType`` specifies the OpenID Connect Flow
which will be used. To use the Implicit Flow then specify the value ``id_token``
and to use the Authorization Code Flow, specify the value ``code``. Some OpenID
Connect Providers do not enable Implicit Flow by default.
``OIDCScope`` is the list of attributes or claims 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.
``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. ``OIDCOAuthVerifyJwksUri`` is a URL from
which the Service Provider will download the public key from the Identity
@@ -146,6 +178,7 @@ set your OIDC options like the following options:
.. code-block:: apache
OIDCClaimPrefix "OIDC-"
OIDCClaimDelimiter ";"
OIDCResponseType "id_token"
OIDCScope "openid email profile"
OIDCMetadataDir <IDP metadata directory>