Skip to content

Use JWT as an authentication provider

DETAILS: Tier: Free, Premium, Ultimate Offering: Self-managed

To enable the JWT OmniAuth provider, you must register your application with JWT. JWT provides you with a secret key for you to use.

  1. On your GitLab server, open the configuration file.

    For Linux package installations:

    sudo editor /etc/gitlab/gitlab.rb

    For self-compiled installations:

    cd /home/git/gitlab
sudo -u git -H editor config/gitlab.yml

  2. Configure the common settings to add jwt as a single sign-on provider. This enables Just-In-Time account provisioning for users who do not have an existing GitLab account.

  3. Add the provider configuration.

    For Linux package installations:

    gitlab_rails['omniauth_providers'] = [
  { name: "jwt",
    label: "Provider name", # optional label for login button, defaults to "Jwt"
    args: {
      secret: "YOUR_APP_SECRET",
      algorithm: "HS256", # Supported algorithms: "RS256", "RS384", "RS512", "ES256", "ES384", "ES512", "HS256", "HS384", "HS512"
      uid_claim: "email",
      required_claims: ["name", "email"],
      info_map: { name: "name", email: "email" },
      auth_url: "https://example.com/",
      valid_within: 3600 # 1 hour
    }
  }
]

    For self-compiled installations:

    - { name: 'jwt',
    label: 'Provider name', # optional label for login button, defaults to "Jwt"
    args: {
      secret: 'YOUR_APP_SECRET',
      algorithm: 'HS256', # Supported algorithms: 'RS256', 'RS384', 'RS512', 'ES256', 'ES384', 'ES512', 'HS256', 'HS384', 'HS512'
      uid_claim: 'email',
      required_claims: ['name', 'email'],
      info_map: { name: 'name', email: 'email' },
      auth_url: 'https://example.com/',
      valid_within: 3600 # 1 hour
    }
  }

    NOTE: For more information on each configuration option refer to the OmniAuth JWT usage documentation.

    WARNING: Incorrectly configuring these settings can result in an insecure instance.

  4. Change YOUR_APP_SECRET to the client secret and set auth_url to your redirect URL.

  5. Save the configuration file.

  6. For changes to take effect, if you:

On the sign in page there should now be a JWT icon below the regular sign in form. Select the icon to begin the authentication process. JWT asks the user to sign in and authorize the GitLab application. If everything goes well, the user is redirected to GitLab and signed in.