Skip to main content

GitLab

This document details how to use GitLab as an identity provider with Pomerium. It assumes you have already installed Pomerium

caution

While we do our best to keep our documentation up to date, changes to third-party systems are outside our control. Refer to GitLab as an OAuth 2.0 authentication service provider from GitLab's docs as needed, or let us know if we need to re-visit this page.

Setting up GitLab OAuth2 for your Application​

  1. Log in to your GitLab account or create one here. If you're using a self-hosted instance, log in to your custom GitLab domain.

  2. From the User Settings area, select Applications. Create a new application:

    create an application

  3. Add a new application by setting the following parameters:

    FieldDescription
    NameThe name of your web app
    Redirect URIhttps://${authenticate_service_url}/oauth2/callback
    Scopesopenid, profile, email

    Click Save application.

  4. Your Application ID and Secret will be displayed:

    Gitlab OAuth Client ID and Secret

    Note the ID and Secret to apply in Pomerium's settings.

Service Account​

To use allowed_groups in a policy, an idp_service_account needs to be set in the Pomerium configuration. The service account for Gitlab uses a personal access token generated at: gitlab.com/-/profile/personal_access_tokens with read_api access:

Gitlab Personal Access Token

The format of the idp_service_account for Gitlab is a base64-encoded JSON document:

tmp.json
{
  "private_token": "..."
}

If you save this JSON document as a temporary file, you can encode it like this:

cat tmp.json | base64 -w 0

Pomerium Configuration​

Edit your Pomerium configuration to provide the Client ID, secret, service credentials, and domain (for self-hosted instances):

GitLab.com​

idp_provider: "gitlab"
idp_client_id: "REDACTED"   # gitlab application ID
idp_client_secret: "REDACTED"   # gitlab application secret
idp_service_account: "REDACTED"   # gitlab service account, base64-encoded json

Self-Hosted GitLab​

Self-hosted CE/EE instances should be configured as a generic OpenID Connect provider:

idp_provider: oidc
idp_client_id: "REDACTED"
idp_client_secret: "REDACTED"
idp_scopes: openid,profile,email
idp_provider_url: https://gitlab.example.com # Base URL of GitLab instance
idp_service_account: "REDACTED"   # gitlab service account, base64-encoded json

When a user first uses Pomerium to login, they are presented with an authorization screen:

gitlab access authorization screen

Please be aware that Group ID will be used to affirm group(s) a user belongs to.