Skip to content

GitLab.com SSO with Entra ID and Access Packages

A small test of granting GitLab.com roles through Entra ID access packages. Entra ID is the identity provider for the grinntec-cloud GitLab group over SAML. An access package adds a user to an Entra group, and a GitLab SAML Group Link turns that group into a GitLab role. The test worked: a user who requested the package signed in and landed in GitLab as Developer.

1. How it fits together

flowchart LR
    U["User"] -->|"1. requests"| AP["Access package<br/>GitLab Developer"]
    AP -->|"2. adds as Member"| G["Entra group<br/>gl-developers"]
    G -. "assigned to" .-> APP["Entra enterprise app<br/>Gitlab (SAML)"]
    U -->|"3. signs in"| GL["gitlab.com/groups/grinntec-cloud"]
    GL -->|"4. redirects"| APP
    APP -->|"5. SAML response<br/>incl. Groups claim"| GL
    GL -->|"6. SAML Group Link<br/>group ID → Developer"| R["Developer role"]
Piece Job
Access package Who can get access, and for how long. Grants membership of an Entra group.
Entra group Holds the people who should have the role. Assigned to the GitLab app.
Entra enterprise app Signs users in to GitLab over SAML and sends their groups in a Groups claim.
GitLab SAML Group Link Maps the Entra group's Object ID to a GitLab role in the group.

Roles only change at sign-in

GitLab reads the Groups claim when the user signs in through SSO. If someone loses the access package, their GitLab role stays until their next SSO sign-in. Without SCIM, their GitLab account is not removed or disabled.

2. Prerequisites

  • GitLab Premium or Ultimate on the top-level group. GitLab.com Free has no group SAML. The test used an Ultimate trial.
  • SAML is set on the top-level group (grinntec-cloud), not a subgroup.
  • Entra ID P2 or Entra ID Governance for access packages.
  • An active admin role in Entra. With PIM, activate it before editing the app (see gotchas).

3. Setup

Entra: enterprise app

  1. Enterprise apps → New application → Create your own application. Name it Gitlab, choose non-gallery, and pick SAML single sign-on.

  2. Basic SAML Configuration. Copy the values from GitLab's Settings → SAML SSO page:

    Entra field Value
    Identifier https://gitlab.com/groups/grinntec-cloud
    Reply URL https://gitlab.com/groups/grinntec-cloud/-/saml/callback
    Sign on URL https://gitlab.com/groups/grinntec-cloud/-/saml/sso

  3. Attributes & Claims.

    • Edit Unique User Identifier (Name ID): source user.objectid, format Persistent.
    • Add a group claim: Groups assigned to the application, source Group ID. Under advanced options, tick Customize the name and set it to Groups, with no namespace.
    • Keep the default emailaddress claim (user.mail). GitLab needs it.

GitLab: SAML settings

  1. In Settings → SAML SSO on the top-level group:
    • Identity provider single sign-on URL: the Entra Login URL.
    • Certificate fingerprint: the Entra signing certificate Thumbprint.
    • Tick Enable SAML authentication for this group. Leave Enforce SSO off while testing.

Entra: group and access package

  1. Create a security group (test used gl-developers). Assign it to the Gitlab app under Users and groups. Leave it empty; the access package fills it.
  2. Identity Governance → Entitlement management → Access packages → New:
    • Basics: name GitLab Developer, catalog General.
    • Resource roles: the group, role Member.
    • Requests: For users in your directory → Specific users and groups, with no approval (test only).

GitLab: map the group to a role

  1. Settings → SAML Group Links: SAML Group Name = the group's Object ID from Entra, access level Developer.

Test

  1. As the test user, request GitLab Developer at https://myaccess.microsoft.com.
  2. In a private window, go to https://gitlab.com/groups/grinntec-cloud. It redirects to Entra to sign in.
  3. Check Manage → Members in the GitLab group. The test user shows as Developer.

Test with a separate user

Group sync can remove members who are not in any linked group. Don't test SSO with the group owner account.

4. Gotchas we hit

Symptom Cause Fix
"An error occurred when attempting to save the SSO user claims" on every claim change Admin role not active (PIM) Activate the role in PIM, then retry.
Access package creation fails: "A linked Azure subscription is required…for guest users" Test user was a B2B guest. Governance for guests is billed per user and needs a linked subscription. Use an internal member test user, or link a subscription.
Error 53010 at myaccess.microsoft.com A Conditional Access policy blocked the new user from registering MFA Exclude the test user from that policy, or give it a Temporary Access Pass.
GitLab: "The SAML response did not contain an email address" The email claim uses user.mail, which is empty for a user with no mailbox Set Email on the user (Edit properties → Contact information).
SSO sign-in lands on GitLab's normal sign-in page with "Register now" GitLab.com does not auto-create accounts from SAML without SCIM Register a GitLab account, then sign in through SSO to link it.
GitLab register: "Email has already been taken" An account from an earlier attempt already used that email Use a new email, and set the same one on the Entra user.
SAML response has no Groups claim Group claim not saved, or the user is not in a group assigned to the app Check the claim exists and the user holds the access package.

5. How users sign in

Users always have a GitLab.com account. They sign in through the group URL, which redirects to Entra:

https://gitlab.com/groups/grinntec-cloud

The /-/saml/sso URL is used for linking and testing, not for everyday sign-in.

6. Not covered by this test

  • SCIM provisioning. It creates and removes GitLab accounts from Entra, so leavers lose access straight away.
  • Removal. Taking away the access package and confirming the role drops at next sign-in was not tested.
  • Enforce SSO. This setting was left off.
  • Naming. The test group gl-developers does not follow the grp-{team}-{purpose} naming standard. A real rollout should use a compliant name and manage the group, app and access package in Terraform (azure-access-management).