Use Okta as your Authentication Provider
This guide will walk you through the steps necessary to configure Okta as the authentication provider for your instance of Okteto.
Okta's OpenID Connect documentation has more details.
Prerequisites
- A working installation of Okteto
- Helm 3.0+ installed on your local machine
- Access to an Okta Workforce Identity Cloud account with permissions to create Applications
Create the Okta Application
Create a new app integration, using the values below:

Fill in the following values in the New Web App Integration window:
- Name: The name of your app (e.g. Okteto)
- Grant type: authorization code
- Sign-in redirect URIs:
https://okteto.{YOUR_DOMAIN}andhttps://okteto.{YOUR_DOMAIN}/auth/callback - Assignments: create a dedicated group for Okteto (recommended), so you control from Okta who can access your instance
Leave the other values empty and click Save.


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

Assign the users or groups that need access to Okteto to the application.

By default, Okteto will use the attributes below when creating a user. These will be synchronized when the account is created, and every time the user logs in.
Nameas the user's display name.Nicknameas the user's username.Emailas the email. Addresses must contain only lowercase alphanumeric characters, '-', or '.'Picture URLfor the user's profile picture.
Authentication will fail if the Nickname or Email property is missing or empty. Please refer to the Customize the attributes that Okteto consumes section below on how to change the attributes that Okteto will use during authentication and account creation.
Open https://{YOUR_TENANT}.okta.com/.well-known/openid-configuration and copy the issuer and authorization_endpoint values.
You need them to configure Okteto.

Update your Users Profile for Okteto
Okta sends the values from the user profile during authentication. To set specific values for Okteto, set an application-specific override in Directory → People → ${User} → Applications → Okteto → Edit.


If you want to sync the profile picture from Okta, you'll need to set the Picture URL property in the dialog shown above.
Configure Okteto
When the Okta application is ready, update the auth section of your Okteto Helm configuration file with the values you copied in Create the Okta Application:
auth:
openid:
enabled: true
clientId: $CLIENT_ID
clientSecret: $CLIENT_SECRET
endpoints:
issuer: $ISSUER_URL
authorization: $AUTHORIZATION_URL
mapping:
externalIDKey: email
You can read more about mapping here.
For a sample Okta tenant, the configuration looks like this:
auth:
openid:
enabled: true
clientId: 0oa76rh0z5zgKG7XXXXX
clientSecret: dTgsfHbYV9tt91Ng4dzvpULw6y7kjJaYxzfXXXXX
endpoints:
issuer: https://dev-6093102.okta.com
authorization: https://dev-6093102.okta.com/oauth2/v1/authorize
mapping:
externalIDKey: email
You can also store the
clientSecretvalue 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 to log in with Okta.

Customize the attributes that Okteto consumes
By default, Okteto will use the following attributes below when creating a user:
Nameas the user's display name.Nicknameas the user's username.Emailas the email. Addresses must contain only lowercase alphanumeric characters, '-', or '.'Picture URLfor 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.
auth:
openid:
enabled: true
clientId: $CLIENT_ID
clientSecret: $CLIENT_SECRET
endpoints:
issuer: $ISSUER_URL
authorization: $AUTHORIZATION_URL
mapping:
externalIDKey: nickname
nameKey: name
emailKey: email
pictureKey: picture
The value of every key in the mapping section must match a claim in your Okta + OpenID configuration, and it must contain a non-empty value.
For example, to use the email instead of the nickname as the username, use the following configuration:
auth:
openid:
enabled: true
clientId: 0oa76rh0z5zgKG7XXXXX
clientSecret: dTgsfHbYV9tt91Ng4dzvpULw6y7kjJaYxzfXXXXX
endpoints:
issuer: https://dev-6093102.okta.com
authorization: https://dev-6093102.okta.com/oauth2/v1/authorize
mapping:
externalIDKey: email
Configure Automatic User Deprovisioning
Okta user deprovisioning explains how to set up the Okta event hook that deprovisions users.
Troubleshooting
Log in fails with a 500 error
The most likely cause is that the user isn't assigned to the application. Make sure the user (or their group) is assigned to the Okteto application in Okta.
To fix it, go to Applications → Okteto → Assignments and add the users or groups.
