# Self-managed: Connect users via GitHub OAuth

[Cortex Self-managed](/self-managed.md) 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](/configure/settings/managing-users/configuring-sso.md).

## Setup GitHub OAuth for self-managed <a href="#setup-instructions" id="setup-instructions"></a>

### Prerequisites[​](https://docs.cortex.io/docs/self-managed/guides/github-oauth#setup-instructions) <a href="#setup-instructions" id="setup-instructions"></a>

Before getting started: Make sure you have already set up a form of GitHub authentication (either via [GitHub App](/self-managed/features/integrations/github.md) or [personal access token](/ingesting-data-into-cortex/integrations/github.md#configure-github-with-a-personal-access-token)).

### Step 1: Create the App[​](https://docs.cortex.io/docs/self-managed/guides/github-oauth#create-the-app) <a href="#create-the-app" id="create-the-app"></a>

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[​](https://docs.cortex.io/docs/self-managed/guides/github-oauth#connect-your-cortex-instance) <a href="#connect-your-cortex-instance" id="connect-your-cortex-instance"></a>

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[​](https://docs.cortex.io/docs/self-managed/guides/github-oauth#install-the-app) <a href="#install-the-app" id="install-the-app"></a>

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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.cortex.io/self-managed/features/users/github-oauth.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.