Resolve "Improve Group SAML authentication failed messages"

Hakeem Abdul-Razakrequested to merge
33713-improve_group_saml_error_messages into master

Related to #33713 (closed)

What?

This merge request creates clearer error messages and validation conditions for authentication errors related to the SAML NameID/extern_uid.

Why?

Before this improvement, users encountered vague error messages which impacted their ability to debug SAML related errors.

Proposed Solution

Kept here as a reference to the discussion below

Solution

  1. Extern UID has already been taken:

This happens when your current IDP NameID (extern_uid/username) is already in use by another user & associated with a Gitlab account.

  • Message: “SAML authentication failed: Your NameID has already been taken. Please contact your administrator to generate a unique NameID.”

  • Cause & Solution:

    Cause Solution
    Trying to link your existing GitLab.com account (has no SAML identity) with an active session (logged-in) to a Gitlab group via Group SSO Tell your administrator to re-generate a non-duplicate NameID (external_uid) for your IDP account while following GitLab’s NameID constraints.
    1. User has already been taken:

    I could not reproduce this & its description is quite confusing. I believe it should be removed especially due to this error message being more relevant: SAML Name ID and email address do not match your user account

    3. Both of the above:

    Based on my UI tests & the Rails validation, Gitlab does not seem to enforce/check for case-sensitivity, contrary to what is mentioned in the docs. So, NameID values like abc123 and ABC123 would be treated as the same value.

    Is this a typo in the documentation that needs to be removed?

    4. Ensure there is a sensible error message when NameID is missing:

    • UI Error Change:
      • Current Flash Error: SAML authentication failed: SAML NameID can’t be blank
      • Proposed: SAML authentication failed: SAML NameID is not in your response. Please contact your administrator
    • Docs Change:
      • Message: “SAML authentication failed: SAML NameID is not in your response. Please contact your administrator”
      • Cause & Solution:
    Cause Solution
    Signed into your Gitlab account via Group SSO but, your SAML response does not have a NameID. Contact your administrator to ensure your IDP has assigned a valid NameID. Verify that your SAML response has a valid NameID.

Steps To Reproduce

  1. Extern UID has already been taken
    • Create a Gitlab Group
    • Create 2 new Gitlab user accounts (user1 & user2) via the self-register page or admin/users page
    • Create an Okta Developer (any IDP works) account & configure Group SOO to the created Gitlab Group
    • Create okta_user1 with NameID = 25 and link it to your Gitlab user1
    • Sign in your user2 Gitlab account and maintain an active session.
    • Create okta_user2 with NameID = 25 and try to link it to your Gitlab user2
    • The error should pop up here
  2. Missing NameID

    • Navigate to lib/gitlab/auth/omniauth_identity_linker_base.rb & set the return nil for the uid

      def uid
 # oauth['uid']   This is the NameID that Gitlab receives from omniauth
  nil
end

    • Try to relink a SAML identity from Okta to your Gitlab Group

    • The error should pop up here

Documentation MR

!168710 (merged)

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.

Edited by Hakeem Abdul-Razak

Merge request reports