Skip to main content
Version: 1.50

Use Azure AD as your Authentication Provider

This guide will walk you through the steps necessary to configure Azure Active Directory as the authentication provider for Okteto.

Azure's OpenID Connect documentation has more details.

Prerequisites​

  • A working installation of Okteto
  • Helm 3.0+ installed on your local machine
  • Access to an Azure account with permissions to register applications in Azure Active Directory

Create an App Registration​

Create a new app integration, using the values below:

Create the new App Registration

Fill in the following values in the Register an application window:

  1. Name: The name of your application (e.g. okteto)
  2. Accounts in this organizational directory only (Default Directory only - Single tenant)
  3. Redirect URI: https://okteto.{YOUR_DOMAIN}/auth/callback

After you create the application, save the Application (client) ID value. You need it to configure Okteto.

Copy the Tenant ID

Copy the Directory (tenant) ID value. You need it to configure Okteto.

Copy the Tenant ID

In the left menu, click Certificates & secrets. Create a New client secret and copy its Value. You need it to configure Okteto.

Copy the Secret ID and Value

In the left menu, click API permissions and grant the following permissions:

Grant permissions

Configure Okteto​

When the app registration is ready, update the auth section of your Okteto Helm configuration file with the values you copied in Create an App Registration:

config.yaml
auth:
openid:
enabled: true
clientId: $CLIENT_ID
clientSecret: $CLIENT_SECRET
endpoints:
issuer: https://sts.windows.net/$TENANT_ID/
authorization: https://login.microsoftonline.com/$TENANT_ID/oauth2/v2.0/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 your Azure Active Directory.

Log in with Azure Active Directory

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://sts.windows.net/$TENANT_ID/
authorization: https://login.microsoftonline.com/$TENANT_ID/oauth2/v2.0/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 Azure Active Directory + OpenID configuration, and it must contain a non-empty value.

warning

Microsoft Entra issues a pairwise sub claim that differs per application registration. Set subjectKey to oid in the mapping section so that each user binds to a claim that stays stable across registrations. User identity binding explains how the subject claim binds a user to their provider account, and why you decide it before your first rollout.