Self-managed: Connect users via GitHub OAuth

Cortex Self-managed attempts to map users to your GitHub organization, but you may need to use the GitHub OAuth flow to connect a GitHub user to a Cortex user.

If you are looking for instructions on SSO for a Cortex cloud workspace, please see Configuring SSO for Cortex workspace logins.

Setup GitHub OAuth for self-managed

Prerequisites​

Before getting started: Make sure you have already set up a form of GitHub authentication (either via GitHub App or personal access token).

Step 1: Create the App​

First, you'll need to create a GitHub App in your GH organization.

1. Go to https://github.com/organizations/<org>/settings/apps

2. Click OAuth Apps > New OAuth App.

3. Set the following settings:

   • Authorization callback URL: <FRONTEND HOST>/oauth/internal/github

   • Application name: Enter a descriptive name for this application, e.g., SSO for Cortex.

   • Homepage URL: This field does not require a specific value in order for the integration to work.

4. Click Register application.

5. View the Client ID. Copy it and store it in a secure location, as you will need it in the next steps.

6. Click Generate a new client secret. Copy this value and store it in a secure location, as you will need it in the next steps.

Step 2: Connect your Cortex instance​

In this step, you will configure your on-prem deployment to communicate with your GitHub OAuth App.

1. Create a k8s secret and add the secret in your values.yaml file for the Helm chart.

   • You may already have a secret set up if you had configured a persistent store previously, so be sure to verify in your Helm chart.

2. Add the following keys to your secret (make sure they're base64 encoded with no extraneous characters at the end):

   • GITHUB_OAUTH_CLIENT_ID (the Client ID you obtained in the previous steps)

   • GITHUB_OAUTH_CLIENT_SECRET (the Client secret you obtained in the previous steps.

   • If using a self-hosted GitHub Enterprise instance

     1. If you didn't configure it during GitHub App setup, set GITHUB_URL to your GitHub enterprise API endpoint

     2. Set GITHUB_OAUTH_URL to <GITHUB_URL>/login/oauth/authorize

     3. Set GITHUB_OAUTH_ACCESS_TOKEN_URL to <GITHUB_URL>/login/oauth/access_token

3. Restart the Cortex backend deployment in k8s.

Step 3: Install the App​

Once your backend has restarted, you're ready to start connecting users.

Navigate to <FRONTEND HOST>/admin/settings/github-connection with a Cortex account you'd like to connect to a GitHub account, and follow the OAuth flow.