Add customisable SAML failure messages when authentication fails

Release notes

Informational messages can now be presented to users when external authentication via SAML fails. This can be useful for guiding end users to internal organisation resources (such as wiki pages), that explain how they can investigate or report this behaviour to a relevant administrator.

Problem to solve

A Large Self-Managed Customer has reported interest in this ticket custom messaging or redirection when a user fails SAML-based authentication. An informative message (that an Administrator can define), would be useful to help end users self-diagnose a problem, or know who to consult to get the behaviour fixed.

In some enterprise organisations, a new user might be allocated SAML authentication within the organisation, but not be appropriately assigned for the GitLab application. Without any additional context, the user might get confused due to the technical nature of the error message.

Intended users

Personas are described at https://handbook.gitlab.com/handbook/product/personas/

• Sidney (Systems Administrator)

Proposal

The existing behaviour consists of a technical response in the red banner. The feature request proposed example message is presented in yellow:

From the gitlab.rb file, this could look like:

gitlab_rails['omniauth_providers'] = [
  {
    name: "saml",
    label: "Provider name", # optional label for login button, defaults to "Saml"
    args: {
      # Existing arguments
      failure_banner: "SAML Authenticated failed. Please refer to company documentation on how to login and resolve any known errors: https://company.example.com/docs/gitlab-saml.md"
    }
  }
]

Available Tier

Free, Premium and Ultimate to keep in-line with the existing SAML SSO feature.