SAML

hich # SAML: Testing and Troubleshooting

Troubleshooting¶

How to view a SAML response in your browser for troubleshooting
- This is one of the single most helpful things for troubleshooting all kinds of SAML tickets.
- You can take a look at some example SAML responses.

Configuration¶

Using JumpCloud as an IdP in GitLab¶

These docs links will help:

I have this up and running: no configuration of assertions required.

Generating the SHA1 Fingerprint¶

Run openssl x509 -in <your_certificate.crt> -noout -fingerprint to generate the SHA1 fingerprint that can be used in the idp_cert_fingerprint setting.

That will be different than sha1sum your_certificate.crt. You could use OneLogin's Calculate Fingerprint tool.

Settings in 💎 `gitlab.rb`¶

On attributes, Microsofts suggests that the end user select the desired source for the nameID claim. This can be Email or something else. Let's focus in on Email.

A few I'd like to focus in on:

name_identifier_format
attribute_statements
uid_attribute

attribute_statements¶

The docs on configuring assertions say:

See attribute_statements for:

Custom assertion configuration examples.
How to configure custom username attributes.

We also link straight to saml.rb.

name_identifier_format¶

Microsoft identity platform uses Persistent as the nameID format.
- Source: Customize SAML token claims

The value in gitlab.rb should match what is sent by the IdP.

In the SAML Response from JumpCloud, I see:

urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress

In gitlab.rb I have:

      name_identifier_format: "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress"

When this is mismatched: nothing too bad seems to happen. With this obviously incorrect value, I was able to log in for the first time as a particular user:

      name_identifier_format: "urn:oasis:names:tc:SAML:1.1:nameid-format:catmail"

SAML 2.0 name identifier formats

uid_attribute¶

Given an error like Saml response missing 'uid' attribute, what exactly is GitLab looking for and where?

Let's inspect a SAML response for an environment where we know SAML is working.
In the omniauth source, it looks like that error is triggered around line 94 of lib/omniauth/strategies/saml.rb.

That is if whatever value that's being used for uid_attribute is missing. It should be possible to parse a raw SAML response the way that Omniauth does. We also see that saml_uid is set as @name_id. I can totally reproduce this problem when I set uid_attribute: "cutie".

🐾 The customer 100% needs to ensure that the SAML response from the IdP includes the value that GitLab expects as uid_attribute. This comes from the SAML response and should be the name_id. source
📋Check the response for JumpCloud to confirm it exists there.
Look through these lines.

🧪 Testing¶

🐳 All roads point to kristophjunge/test-saml-idp. The Apereo Foundation maintains apereo/saml2-sp. Read more in Testing SAML2 Identity Providers from August 2023.

⭐️ Use SSO authentication locally
Public IDP from SSOCircle

💎 From the Source (Code)¶

What causes the button with the customized SAML label to appear? We know that we're looking for what controls whether the "or sign in with" text appears.

After cloning the gitlab-org/gitlab source I used this ripgrep command to exclude specs and translations:

rg  -g '!{locale/*,spec/*}'  'or sign in with'

That led me to app/views/devise/shared/_omniauth_box.html.haml.

if any_form_based_providers_enabled? || password_authentication_enabled_for_web?

OK, so the "or sign in with" thing should appear if any form-based providers are enabled or if password authentication is enabled for the web.

🚀 ...and beyond!¶

This kind of thing tends to be out of scope but it interesting nonetheless: