Skip to main content
Version: 1.47

Use GitHub as your Authentication Provider

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

GitHub's documentation explains how to create an OAuth App.

Prerequisites​

  • A working installation of Okteto
  • Helm 3.0+ installed on your local machine
  • Access to a GitHub account with permissions to create an OAuth App

If you plan to use the Okteto GitHub Integration to access private repositories, configure the Okteto GitHub App first. You then use that same GitHub App for both the integration and the OAuth login.

Create the OAuth App​

When you create the OAuth App, provide the following values:

Homepage URL:

https://okteto.DOMAIN

Authorization callback URL:

https://okteto.DOMAIN/auth/callback

Copy the Client ID and Client Secret values. You need them to configure Okteto.

Configure Okteto​

When the GitHub OAuth App is ready, update the auth section of your Helm configuration file with the following values:

config.yaml
auth:
github:
enabled: true
clientId: "REPLACE_ME_WITH_YOUR_OAUTH_APP_CLIEND_ID"
clientSecret: "REPLACE_ME_WITH_YOUR_OAUTH_APP_CLIEND_SECRET"
organization: "REPLACE_ME_WITH_YOUR_GITHUB_ORGANIZATION"

You can also store the sensitive part of these credentials 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.

The organization field is optional but recommended. Setting it restricts login to members of that GitHub organization, so you control who can access your Okteto instance. An empty organization field permits any user with a GitHub account to log in.

warning

If your Okteto instance is publicly reachable, set up access restrictions. An empty organization field lets anyone with a GitHub account log in to your Okteto instance.

To give access to users outside your GitHub organization, list their GitHub accounts in the allowList key.

config.yaml
auth:
github:
enabled: true
clientId: "REPLACE_ME_WITH_YOUR_OAUTH_APP_CLIEND_ID"
clientSecret: "REPLACE_ME_WITH_YOUR_OAUTH_APP_CLIEND_SECRET"
organization: "REPLACE_ME_WITH_YOUR_GITHUB_ORGANIZATION"
allowList: ["acct1","acct2","acct3"]

Installing the GitHub App in your organization​

When you set the organization field, Okteto verifies each user's GitHub organization membership at login and only admits members of that organization. To read that membership, the Okteto GitHub App must be installed in the organization you configured.

GitHub only exposes a user's organization membership to an installed GitHub App that has the Members organization permission set to Read-only. The OAuth login flow doesn't require the App to be installed, so a login can complete while the membership check still fails. When the App isn't installed in the configured organization, Okteto can't confirm that a user belongs to it and rejects the login as unauthorized, even for members of the organization.

To install the App, open https://github.com/apps/YOUR_GITHUB_APP_NAME/installations/new and select the organization you set in the organization field. This is the same GitHub App you configure for private repository access, so a single App covers both authentication and repository access.

info

The organization filter and the App installation must point to the same GitHub organization. If you change the organization value, install the App in the new organization as well.