Customize the authentication error timeout page in modOIDC

There is a situation that happens when a user triggers an authentication
in OpenStack that uses Identity federation, which leads users to a blank
page with an error message that might not be that clear to users. If the
user takes too long to enter his/her credentials in the login page of
the IdP, the user sees a page saying that the authentication took too
much and that the user must try it again. However, if the user tries
again, she/he is already logged in to the IdP, and then the user gets
access direct to Horizon. This whole process can be a bit confusing for
users, and they saw an error page after the login, which leads them to
think that there was an error in the authentication, but then when
he/she tries again, everything just works.

Therefore, to handle such cases we propose Kolla-ansble to use a custom
error page that has an automatic redirect if the error happens.

The timeout is managed by "OIDCStateTimeout" variable. The default
(which is what we have in place now) is 300 seconds (5 minutes):
https://github.com/zmartzone/mod_auth_openidc/blob/d13ee0e4bd2cef94c4d2b55829310175288e0bdf/src/mod_auth_openidc.c#L651).

I would not recommend the increase of this timeout though. I would
rather decrease this value; 5 minutes to such an operation is already
too much. This variable can be overridden via wsgi-keystone.conf file.

To customize the error page we have the following variable
"OIDCHTMLErrorTemplate". The template is processed in the following
line: https://github.com/zmartzone/mod_auth_openidc/blob/f2b8315cd48faba04320e9a06fc52b57f0989dcb/src/util.c#L1619.
As we can see, there is no default page. The default HTML is hardcoded
in C++, and the template requires two "%s" placeholders that will
receive the title of the error message and the full description of the error.

Change-Id: Iebda3ca7a5f9cef7e5e0930fc4f70764774d6ed5
Signed-off-by: Rafael Weingärtner <rafael@apache.org>

1 files changed, 14 insertions, 0 deletions

diff --git a/doc/source/reference/shared-services/keystone-guide.rst b/doc/source/reference/shared-services/keystone-guide.rst
index d0958a3f9..b92230dcb 100644
--- a/doc/source/reference/shared-services/keystone-guide.rst
+++ b/doc/source/reference/shared-services/keystone-guide.rst
@@ -104,6 +104,20 @@ Example for Keycloak shown below:
     keystone_federation_oidc_additional_options:
       OIDCTokenBindingPolicy: disabled
 
+When using OIDC, operators can also use the following variable
+to customize the delay to retry authenticating in the IdP if the
+authentication has timeout:
+
+``keystone_federation_oidc_error_page_retry_login_delay_milliseconds``
+    Default is 5000 milliseconds (5 seconds).
+
+It is also possible to override the ``OIDCHTMLErrorTemplate``,
+the custom error template page via:
+
+.. code-block:: yaml
+
+  {{ node_custom_config }}/keystone/federation/modoidc-error-page.html
+
 Identity providers configurations
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~