GitHub OAuth Setup

You can allow users to sign in to your Rocket.Chat workspace with their GitHub or GitHub Enterprise accounts. Setup involves alternating between GitHub and your Rocket.Chat admin panel, so keep both open in separate tabs.

Note

Rocket.Chat treats GitHub and GitHub Enterprise as separate integrations, each with its own section in the OAuth settings and its own callback URL. Configure the one that matches your environment. If you use both, you can configure them independently.

Prerequisites

• A GitHub or GitHub Enterprise account with permission to create OAuth apps

• Administrator access to your Rocket.Chat workspace

Step 1: Create a GitHub OAuth app

1. Go to GitHub Developer Settings. For GitHub Enterprise, go to the equivalent path on your enterprise instance.

2. Select OAuth Apps → New OAuth App.

3. Enter the required app details. You will provide the Authorization callback URL in Step 3.

4. Select Register application.

5. On the app page, copy the Client ID and select Generate a new client secret.

Important

The Client Secret is shown only once at the moment of generation. Copy it immediately and store it somewhere safe. If you navigate away without copying, you must generate a new secret and update Rocket.Chat with the new value.

Leave this page open. You will return to it in Step 3.

Step 2: Get the callback URL from Rocket.Chat

1. Sign in to your Rocket.Chat workspace as an administrator.

2. Go to Manage → Workspace → Settings → OAuth.

3. Expand the GitHub section (or GitHub Enterprise if you are using an enterprise instance).

4. Copy the value of Github Callback URL (or GitHub Enterprise Callback URL). It looks like https://your-domain/_oauth/github or https://your-domain/_oauth/github_enterprise.

Step 3: Add the callback URL to your GitHub OAuth app

1. Return to your GitHub OAuth app page.

2. Paste the callback URL you copied from Rocket.Chat into the Authorization callback URL field.

3. Select Update application.

The Authorization callback URL in GitHub and the callback URL in Rocket.Chat must match exactly, including the scheme and any trailing path. A mismatch typically does not produce an error on GitHub's side, but sign-in will fail at Rocket.Chat with No matching login attempt found.

Step 4: Configure GitHub OAuth in Rocket.Chat

Back in Rocket.Chat, in the same OAuth section, expand GitHub or GitHub Enterprise depending on your environment.

For GitHub:

1. Turn OAuth Enabled on.

2. Enter the following values:

   • Client Id: the Client ID from your GitHub OAuth app

   • Client Secret: the Client Secret from your GitHub OAuth app

3. Select Save changes.

For GitHub Enterprise:

1. Turn OAuth Enabled on.

2. Enter the following values:

   • Server URL: the base URL of your GitHub Enterprise instance, for example https://github.example.com (no trailing slash)

   • Client Id: the Client ID from your GitHub Enterprise OAuth app

   • Client Secret: the Client Secret from your GitHub Enterprise OAuth app

3. Select Save changes.

Verify the setup

1. Sign out of your workspace.

2. On the sign-in page, confirm that the Sign in with GitHub button appears.

3. Select it and complete the GitHub sign-in flow. You should be returned to your workspace and signed in.

Troubleshooting