GitLab SSO: OpenID Connect for a self-managed instance

Self-managed GitLab supports OpenID Connect through OmniAuth. Users sign in at your identity provider, GitLab validates the ID token, and the user is connected to a GitLab account. It is the standard way to give a whole engineering organization one login for Git, CI and the rest of the toolchain.

This guide is for a self-managed GitLab instance. GitLab.com has its own group SAML/SSO product and does not use the gitlab.rb configuration below.

What you need

• A self-managed GitLab instance with HTTPS. GitLab's OIDC integration expects an HTTPS identity provider, and the callback should be HTTPS too.
• Administrator access to /etc/gitlab/gitlab.rb.
• An identity provider application with a client ID and secret.

Step 1: create the application in the IdP

Create an application for GitLab and add the callback URL:

https://gitlab.example.com/users/auth/openid_connect/callback

Copy the client ID and client secret. The issuer is the identity provider's base URL, for example https://door.example.com. If the provider uses a private CA, make sure GitLab trusts it.

Step 2: configure GitLab

Edit /etc/gitlab/gitlab.rb and add the provider block:

gitlab_rails['omniauth_providers'] = [
  {
    name: "openid_connect",
    label: "Casdoor",
    args: {
      name: "openid_connect",
      scope: ["openid", "profile", "email"],
      response_type: "code",
      issuer: "https://<casdoor-host>",
      client_auth_method: "query",
      discovery: true,
      uid_field: "preferred_username",
      client_options: {
        identifier: "<client-id>",
        secret: "<client-secret>",
        redirect_uri: "https://gitlab.example.com/users/auth/openid_connect/callback"
      }
    }
  }
]

The fields that matter most:

• issuer must be exactly the issuer in the discovery document. A trailing slash or a different host produces a discovery or validation error.
• discovery: true tells GitLab to read the authorization, token, userinfo and JWKS endpoints from /.well-known/openid-configuration.
• uid_field is the claim GitLab uses as the unique identifier. preferred_username is a good choice when the provider sends it; if it sends name instead, use name and make sure it is stable.
• client_auth_method: query sends the client credentials in the token request. Some providers prefer basic; check the provider's documentation if the token request fails.
• scope must include openid, and usually profile and email for the name and address.

Step 3: apply the configuration

Run:

sudo gitlab-ctl reconfigure

Then restart the web service if your version requires it:

sudo gitlab-ctl restart

The GitLab login page should now show the provider button. If it does not, check that the provider block is valid Ruby and that the reconfigure completed without errors.

Step 4: connect accounts and test

Each existing GitLab user can open /-/profile/account and connect the identity provider account. After that, the user can sign in through the provider.

Depending on your GitLab version and settings, administrators can enable automatic account creation or auto-linking by email. Review the OmniAuth settings before turning those on for a large organization; auto-linking by email is convenient but depends on the provider verifying the email address.

Groups and authorization

GitLab uses its own groups and project memberships for authorization. OIDC signs the user in; it does not automatically grant access to projects. Plan how users get into groups:

• Add them manually or through GitLab's group management.
• Use an LDAP sync if the organization already has one.
• Use SAML group links if the identity provider speaks SAML and GitLab's SAML integration is configured.

Do not assume that an IdP group becomes a GitLab group unless you have configured a group sync feature that does that.

Troubleshooting

FAQ

Does this work on GitLab.com? No. GitLab.com uses group SAML/SSO, configured in the group settings. The gitlab.rb configuration is for self-managed instances.

Should I use OIDC or SAML for GitLab? Both are supported. OIDC is simpler for a modern identity provider; SAML is common when the organization standardizes on it and needs SAML group links.

Can GitLab create users automatically? GitLab can auto-create or auto-link users depending on the OmniAuth settings. Review those settings carefully, especially if the provider does not verify email addresses.

Can I enforce SSO for everyone? GitLab has settings to require SSO for certain providers and to disable password authentication. Test with an administrator fallback before enforcing it, or you can lock the organization out.

If you need an identity provider for GitLab and the rest of the engineering stack, Casdoor supports OIDC, SAML, CAS, LDAP and SCIM. Casdoor Cloud starts at $6.67/month billed yearly for a dedicated instance. See the Casdoor GitLab guide for the exact block.