GitHub OAuth Setup

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

Prerequisites

• A GitHub 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.

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.

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.

4. Copy the value of Github Callback URL. It looks like https://your-domain/_oauth/github.

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.

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.

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