# GitLab

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


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 (opens new window) from GitLab's docs as needed, or let us know (opens new window) 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 (opens new window). If you're using a self-hosted instance, log in to your custom GitLab domain.

  2. From the User Settings area, select Applications (opens new window). Create a new application:

    create an application

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

    Field Description
    Name The name of your web app
    Redirect URI https://${authenticate_service_url}/oauth2/callback
    Scopes openid, 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 (opens new window) with read_api access:

Gitlab Personal Access Token

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

  "private_token": "..."

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

cat json.tmp | 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

# Self-Hosted GitLab

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

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 (opens new window) will be used to affirm group(s) a user belongs to.