Skip to main content
Version: 1.48

Use GitLab as your Authentication Provider

This guide will walk you through the steps necessary to configure Gitlab as the authentication provider for your Okteto instance.

GitLab's OpenID Connect documentation has more details.

Prerequisites​

  • A working installation of Okteto
  • Helm 3.0+ installed on your local machine
  • Access to a GitLab account with permissions to enable and configure OAuth and OpenID, on gitlab.com or on a self-hosted GitLab instance
note

The examples use https://gitlab.com. If you use a self-hosted GitLab instance, replace gitlab.com with your GitLab instance's URL.

Create the GitLab Application​

Create a new OAuth application integration, using the values below:

Create the new GitLab App

Set the OpenID Scopes for the GitLab App

After you create the application, copy the Application ID and Secret values. You need them to configure Okteto.

Copy the Application ID and Secret from the success page

Open https://gitlab.com/.well-known/openid-configuration and copy the issuer and authorization_endpoint values. You need them to configure Okteto.

Copy the issuer and authorization_endpoint from the openid configuration response

Configure Okteto​

When the GitLab application is ready, update the auth section of your Okteto Helm configuration file with the values you copied in Create the GitLab Application:

config.yaml
auth:
openid:
enabled: true
clientId: $CLIENT_ID
clientSecret: $CLIENT_SECRET
endpoints:
issuer: "https://gitlab.com"
authorization: "https://gitlab.com/oauth/authorize"
mapping:
externalIDKey: email

You can also store the clientSecret value in a Kubernetes secret.

Upgrade your Okteto instance to apply the new configuration. Upgrade to the same version you already run: it keeps the changes to a minimum and makes any issue easier to troubleshoot.

After the upgrade completes, open your Okteto instance and click Log In. If the configuration is correct, Okteto authenticates users with GitLab.

Customize the attributes that Okteto consumes​

By default, Okteto will use the following attributes below when creating a user:

  • Name as the user's display name.
  • Nickname as the user's username.
  • Email as the email. Addresses must contain only lowercase alphanumeric characters, '-', or '.'
  • Picture URL for the user's profile picture.

If you don't use some of those values, or you want to change which attributes Okteto maps, set the mapping field inside the openid key in your Helm configuration file.

config.yaml
auth:
openid:
enabled: true
clientId: $CLIENT_ID
clientSecret: $CLIENT_SECRET
endpoints:
issuer: "https://gitlab.com"
authorization: "https://gitlab.com/oauth/authorize"
mapping:
externalIDKey: nickname
nameKey: name
emailKey: email
pictureKey: picture

The value of every key in the mapping section must match a claim in your GitLab OpenID configuration, and it must contain a non-empty value. The claims_supported section of https://gitlab.com/.well-known/openid-configuration lists the available claims.