Skip to main content

Enabling OAuth with GitHub allows your users to sign up and sign in to your Clerk app with their GitHub account.

Configure for your development instance

For development instances, Clerk uses preconfigured shared OAuth credentials and redirect URIs—no other configuration is needed.

  1. In the Clerk Dashboard, navigate to the SSO connections page.
  2. Select Add connection and select For all users.
  3. Select GitHub from the provider list.

Important

The shared credentials belong to a GitHub OAuth App. To test a GitHub App in development, toggle on Use custom credentials and follow the production instance steps.

Configure for your production instance

For production instances, you must provide custom credentials.

Keep two browser tabs open during setup: one for the Clerk Dashboard and one for GitHub's Developer Settings.

Enable GitHub as a social connection in Clerk

  1. In the Clerk Dashboard, navigate to the SSO connections page.
  2. Select Add connection and select For all users.
  3. Select GitHub from the provider list.
  4. Ensure that both Enable for sign-up and sign-in and Use custom credentials are toggled on.
  5. In the App type dropdown, select GitHub OAuth App or GitHub App, depending on which type of app you'll create in GitHub.
  6. Save the Authorization Callback URL somewhere secure. Keep this page open.

Create your GitHub app

Follow the steps for the App type you selected in the Clerk Dashboard.

  1. In your GitHub's Developer Settings, navigate to the Register a new OAuth app page.
  2. Complete the required fields (Application name and Homepage URL).
  3. Under Redirect URIs, in Redirect URI, paste the Authorization Callback URL you saved from the Clerk Dashboard.
  4. Select Register application. You'll be redirected to your app's General page.
  5. Select Generate a new client secret. Save the Client ID and Client Secret somewhere secure.
  1. In your GitHub's Developer Settings, navigate to the Create GitHub App page.
  2. Complete the required fields (GitHub App name and Homepage URL).
  3. Under Identifying and authorizing users, in Redirect URI, paste the Authorization Callback URL you saved from the Clerk Dashboard.
  4. Keep Expire user authorization tokens selected. Clerk uses the refresh token to renew expired tokens. See GitHub App access tokens for details.
  5. Leave Request user authorization (OAuth) during installation unchecked. Clerk can't complete a sign-in that starts from an app installation.
  6. Under Webhook, uncheck Active. Clerk doesn't use GitHub App webhooks.
  7. Under Permissions, expand Account permissions and set Email addresses to Read-only. Without this permission, users who keep their email address private on GitHub can't sign in, and Clerk returns an error that names the missing permission.
  8. Under Where can this GitHub App be installed?, select Any account. A GitHub App that can only be installed on your account can only be authorized by you or your organization's members.
  9. Select Create GitHub App. You'll be redirected to your app's General page.
  10. Select Generate a new client secret. Save the Client ID and Client Secret somewhere secure. Use the Client ID, not the App ID.

Set the Client ID and Client Secret in the Clerk Dashboard

  1. Navigate back to the Clerk Dashboard where the configuration page should still be open. Paste the Client ID and Client Secret values that you saved into the respective fields.
  2. Select Save.

Note

If the page is no longer open, navigate to the SSO connections page in the Clerk Dashboard. Select the connection. Under Use custom credentials, paste the values into their respective fields.

Test your connection

The simplest way to test your connection is to visit your Clerk app's Account Portal, which is available for all Clerk apps out-of-the-box.

  1. In the Clerk Dashboard, navigate to the Account Portal page.
  2. Next to Sign-in, select the button to visit the sign-in page. The URL should resemble:
    • For development - https://your-domain.accounts.dev/sign-in
    • For production - https://accounts.your-domain.com/sign-in
  3. Sign in with your connection's credentials.

If sign-in fails, check Application Logs for an oauth_callback.failed event. Its details include the failure reason and may include an error message.

Once you confirm the connection, get the user's OAuth access token from your backend using the getUserOauthAccessToken() method to retrieve their data from the social provider.

GitHub App access tokens

If you use a GitHub App, its user access tokens differ from GitHub OAuth App tokens:

  • Permissions instead of scopes: GitHub Apps ignore OAuth scopes, so the Clerk Dashboard doesn't show Scopes for them. A token can only access what both the user and your app's permissions allow. Account permissions, such as Email addresses, apply once the user authorizes your app, so users don't need to install it to sign in. You can read public resources without installing the app. Accessing non-public repository or organization resources, or writing to public repositories, requires installation on the relevant account.
  • Expiring tokens: With Expire user authorization tokens selected, user access tokens expire after 8 hours. getUserOauthAccessToken() returns a renewed token when the current one has expired. If GitHub rejects the refresh token, for example because it expired after 6 months, the call returns an oauth_token_retrieval_error error, and the user needs to sign in with GitHub again.
  • Sign-in only: Clerk uses your GitHub App to sign users in. It doesn't install your app or create installation access tokens. If your app needs to act as itself rather than on behalf of a user, use GitHub's installation authentication.

Feedback

What did you think of this content?

Last updated on