Skip to main content
Version: 1.25

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.

Please refer to GitLab's official documentation on Open ID Connect for more information.

Prerequisites​

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

This guide will use https://gitlab.com in the examples. If you're using GitLab self-hosted, replace gitlab.com with the URL of your GitLab instance.

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

Once the application has been created, copy the values of the Application ID and the Secret. You'll need them to configure Okteto.

Copy the Application ID and Secret from the success page

Finally, browse to https://gitlab.com/.well-known/openid-configuration, and copy the values of issuer and authorization_endpoint. You'll need them to configure Okteto.

Copy the issuer and authorization_endpoint from the openid configuration response

Configure Okteto​

Once you have the GitLab application ready, update the auth section of your Okteto Helm configuration file with the values you obtained on the first step of this guide:

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 value of clientSecret as a secret directly in Kubernetes.

Upgrade your Okteto instance for the new configuration to be applied. We recommend that you upgrade to the same version that you already have to minimize the changes and help you troubleshoot any issues.

Once the upgrade has been completed, go to your instance and click on the Log In button to access your instance. If everything is configured correctly, Okteto will now use Gitlab for user authentication.

Log in with Gitlab

Customize the attributes that Okteto consumes​

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

  • Name as the display name of the user.
  • Nickname as the username of the user.
  • Email as the email.
  • Picture URL for the user's profile picture.

If you are not using some of those values, or you want to customize which attributes get mapped, you can customize that by using 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. You can see the available claims in the claims_supported section of https://gitlab.com/.well-known/openid-configuration.