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.

Please refer to GitHub's official documentation on how to create an OAuth App for more information.

Prerequisites​

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

If you are planning on using our GitHub Integration for accessing private repositories, you should follow the guide to configure our GitHub App. You'll then use the same Github Application for the Integration as the one from Oauth.

Create the OAuth App​

When creating the OAuth App, you will need to 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'll need them to configure Okteto.

Configure Okteto​

Once you have the GitHub OAuth App 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 use a secret to store the sensitive part of these credentials.

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.

The organization field is optional but recommended. Setting it restricts login to members of the given GitHub organization, giving you finer control over 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, we highly recommend that you set up access restrictions. Leaving the organization field blank lets anyone with a GitHub account log in to your Okteto instance.

If you want to provide access to users outside of your GitHub organization, you can additionally use the allowList key to list the GitHub accounts you want to allow.

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 does not require the App to be installed, so a login can complete while the membership check still fails. When the App is not installed in the configured organization, Okteto cannot 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.

Video walkthrough​

The following video walks you through configuring GitHub as an authentication provider for your Okteto instance: