Step-up auth: Custom org-specific documentation links for failed step-up [PART 1]

Gerardo Navarrorequested to merge
gitlab-community/gitlab-org/gitlab:526598-gerardo-navarro-step-up-auth-add-documentation-link-when-not-authenticated-2 into master

What does this MR do and why?

Step-up auth: Custom org-specific documentation links for failed step-up

In a previous MR, we introduced step-up authentication for the admin mode, see !171643 (merged). But, when the step-up auth fails, then GitLab shows a simple notice message "Step-up authentication not successful." This can be improved.

This MR allows GitLab administrators to configure organization-specific documentation links in the step-up auth configuration in the gitlab.yml. These documentation links are displayed when step-up authentication fails.

Key features:

  • Administrators can configure org-specific documentation links in gitlab.yml
  • Only failed providers’ links are displayed, improving relevance
  • Safe HTML generation with proper security attributes
  • Supports inline, comma-separated formatting for multiple providers

When step-up authentication fails, users now see helpful links directing them to organization-specific authentication documentation, improving UX and reducing support burden.

Changelog: other

🛠️ with ❤️ at Siemens

References

Screenshots or screen recordings

Before After
grafik grafik

How to set up and validate locally

Part 1: Configure step-up auth in Keycloak

  1. Follow the steps to set up step-up authentication in Keycloak

Part 2: Prepare your local GitLab gdk instance

  1. Please follow the steps described in another MR to enable admin mode, create an admin user, enable feature flag and configure the step-up auth setting properly in the gitlab.yml.
  2. As part of this MR, I recommend using the step up of configuration from the collapse section below.
Click to expand 
development:
  <<: *base
  omniauth:
    allow_bypass_two_factor:  ["openid_connect"]
    allow_single_sign_on: ["openid_connect"]
    auto_link_ldap_user: null
    auto_link_saml_user: null
    auto_link_user: ["openid_connect"]
    auto_sign_in_with_provider: 
    block_auto_created_users: false
    external_providers: []

    providers:
    - { name: "openid_connect",
        label: "[OIDC] Keycloak",
        args: {
          name: "openid_connect",
          # strategy_class: "OmniAuth::Strategies::OpenIDConnect",
          scope: ["openid", "profile", "email"],
          response_type: "code",
          issuer: "http://localhost:8080/realms/step-up-auth-gitlab-realm",
          client_auth_method: "query",
          discovery: false,
          uid_field: "preferred_username",
          pkce: true,
          allow_authorize_params: ["claims"],
          client_options: {
            host: "localhost",
            scheme: "http",
            port: "8080",
            identifier: "step-up-auth-gitlab-client",
            secret: "C6S2b1ZkifZa6BI8Jy5K3lz2Eglb4JuQ",
            redirect_uri: "http://gdk.test:3000/users/auth/openid_connect/callback",
            authorization_endpoint: "/realms/step-up-auth-gitlab-realm/protocol/openid-connect/auth",
            token_endpoint: "/realms/step-up-auth-gitlab-realm/protocol/openid-connect/token",
            userinfo_endpoint: "/realms/step-up-auth-gitlab-realm/protocol/openid-connect/userinfo",
            jwks_uri: "http://localhost:8080/realms/step-up-auth-gitlab-realm/protocol/openid-connect/certs",
            end_session_endpoint: "/realms/step-up-auth-gitlab-realm/protocol/openid-connect/logout"
          }
        },
        step_up_auth: {
          admin_mode: {
            enabled: true,
            documentation_link: "https://openid.net/specs/openid-connect-core-1_0.html#IDToken",
            id_token: {
              required: {
                acr: 'gold' 
              }
            },
            params: {
              claims: { 
                id_token: { 
                  acr: { 
                    essential: true, 
                    values: ['silver'] # <= NOTE: Because of `silver`, the step-up authentication will fail because `acr` level `gold` is not fulfilled.
                  } 
                } 
              }
            }
          },          
        }
      }

Part 3: Test documentation link

  1. Sign in with the admin user and navigate to admin area => you will be asked to reauthenticate again
  2. Select the specified step-up auth omniauth provider "[OIDC] Keycloak" => you will be redirected to Keycloak and then back to GitLab.
  3. GitLab will check if you fulfill the id token requirements (i.e. acr is required to be gold) and notice that the acr level is silver.
  4. You will be redirected back to reauthenticate again and you will see a notice that includes the docmentaion link

MR acceptance checklist

Please evaluate this MR against the MR acceptance checklist. It helps you analyze changes to reduce risks in quality, performance, reliability, security, and maintainability.

MR Checklist (@gerardo-navarro)

Related to #526598

Edited by Gerardo Navarro

Merge request reports