From 7ac0c3cd33214ff3c926e2b5316b637892d701fb Mon Sep 17 00:00:00 2001
From: Jadon Naas <jadon.naas@canonical.com>
Date: Thu, 1 Aug 2024 21:10:43 -0400
Subject: [PATCH] Update OIDC Apache config to avoid masking Keystone API
 endpoint

The current configuration for the OIDCRedirectURI results in
mod_auth_openidc masking the Keystone federation authentication
endpoint, which results in incorrect responses to requests for
Keystone tokens. This change updates the documentation to
recommend using a vanity URL that does not match a Keystone
API endpoint.

Closes-Bug: 2075349
Change-Id: I1dfba5c71da68522fdb6059f0dc03cddc74cb07d
---
 doc/source/admin/federation/openidc.inc | 10 ++++++++--
 1 file changed, 8 insertions(+), 2 deletions(-)

diff --git a/doc/source/admin/federation/openidc.inc b/doc/source/admin/federation/openidc.inc
index 716ddfbb6e..45163c3148 100644
--- a/doc/source/admin/federation/openidc.inc
+++ b/doc/source/admin/federation/openidc.inc
@@ -63,7 +63,7 @@ options:
    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
+   OIDCRedirectURI https://sp.keystone.example.org/v3/redirect_uri
 
 ``OIDCScope`` is the list of attributes that the user will authorize the
 Identity Provider to send to the Service Provider. ``OIDCClientID`` and
@@ -77,7 +77,9 @@ must be used while using the AuthType ``auth-openidc``, when using the AuthType
 will not be necessary.
 ``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.
+of the protected federated auth path. It should not match any Keystone API endpoints
+or mod_auth_openidc will handle requests to the endpoint instead of Keystone. This
+can lead to unusual errors and behaviors from Keystone.
 
 .. note::
 
@@ -94,6 +96,10 @@ Configure each protected path to use the ``openid-connect`` AuthType:
 
 .. code-block:: apache
 
+   <Location ~ "/redirect_uri">
+       Require valid-user
+       AuthType openid-connect
+   </Location>
    <Location /v3/OS-FEDERATION/identity_providers/google/protocols/openid/auth>
        Require valid-user
        AuthType openid-connect