Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

(/authentication/social-connections/github) update guide #1602

Merged
merged 20 commits into from
Oct 11, 2024
Merged
Changes from all commits
Commits
Show all changes
20 commits
Select commit Hold shift + click to select a range
526181c
change title
victoriaxyz Oct 4, 2024
6416a97
draft
victoriaxyz Oct 4, 2024
ca049f0
Merge branch 'main' into vi/docs-363/oauth-github
victoriaxyz Oct 8, 2024
43ddb26
Merge branch 'main' into vi/docs-363/oauth-github
victoriaxyz Oct 9, 2024
04e7bcb
update
victoriaxyz Oct 9, 2024
21b6cce
Merge branch 'main' into vi/docs-363/oauth-github
victoriaxyz Oct 9, 2024
650aa9e
Update docs/authentication/social-connections/github.mdx
victoriaxyz Oct 9, 2024
4e94904
Update docs/authentication/social-connections/github.mdx
victoriaxyz Oct 9, 2024
09382cd
Update docs/authentication/social-connections/github.mdx
victoriaxyz Oct 10, 2024
3e71d72
Update docs/authentication/social-connections/github.mdx
victoriaxyz Oct 10, 2024
32ff4f5
Update docs/authentication/social-connections/github.mdx
victoriaxyz Oct 10, 2024
67e0de7
Update docs/authentication/social-connections/github.mdx
victoriaxyz Oct 10, 2024
514da1c
Update docs/authentication/social-connections/github.mdx
victoriaxyz Oct 10, 2024
4725c13
Merge branch 'main' into vi/docs-363/oauth-github
victoriaxyz Oct 10, 2024
88282e1
Merge branch 'main' into vi/docs-363/oauth-github
victoriaxyz Oct 10, 2024
8b98b76
update
victoriaxyz Oct 10, 2024
0e32e6b
fix
victoriaxyz Oct 10, 2024
77a91de
Merge branch 'main' into vi/docs-363/oauth-github
victoriaxyz Oct 10, 2024
9824905
Update docs/authentication/social-connections/github.mdx
alexisintech Oct 11, 2024
4a2e32e
Update docs/authentication/social-connections/github.mdx
alexisintech Oct 11, 2024
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
78 changes: 60 additions & 18 deletions docs/authentication/social-connections/github.mdx
Original file line number Diff line number Diff line change
@@ -1,36 +1,78 @@
---
title: Add GitHub as a social connection
description: Learn how to set up social connection with GitHub.
description: Learn how to allow users to sign up and sign in to your Clerk app with their GitHub account using OAuth.

---

How to set up social connection with GitHub
<TutorialHero
beforeYouStart={[
{
title: "A Clerk app is required.",
link: "/docs/quickstarts/setup-clerk",
icon: "clerk",
},
{
title: "A GitHub account is required.",
link: "https://github.com/signup",
icon: "user-circle",
},
]}
>
- Use GitHub to authenticate users with OAuth
</TutorialHero>

Enabling OAuth with [GitHub](https://docs.github.com/en/developers/apps/building-oauth-apps/creating-an-oauth-app) 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**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page.
1. Select **Add connection** and choose **For all users**.
1. In the **Choose provider** dropdown, select **GitHub**.
1. Select **Add connection**.

## Configure for your production instance

## Overview
For _production instances_, you must provide custom credentials which involves generating your own **Client ID** and **Client Secret** using your GitHub account.

Adding social connection with GitHub to your app with Clerk is done in a few steps - you only need to set the **Client ID**, **Client Secret** and **Authorized redirect URI** in your instance settings.
To make the setup process easier, it's recommended to keep two browser tabs open: one for your [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) and one for your [GitHub Developers](https://GitHub.com/developers/applications) page.

To make the development flow as smooth as possible, Clerk uses preconfigured shared OAuth credentials and redirect URIs for development instances - no other configuration is needed.
<Steps>
### Enable GitHub as a social connection in Clerk

For production instances, you will need to generate your own Client ID and Client secret using your GitHub account.
1. In the Clerk Dashboard, navigate to the [**SSO Connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page.
1. Select **Add connection** and choose **For all users**.
1. In the **Choose provider** dropdown, select **GitHub**.
1. Ensure that both **Enable for sign-up and sign-in** and **Use custom credentials** are toggled on.
1. Save the **Authorized redirect URI** somewhere secure. Keep the modal and page open.

> [!NOTE]
> The purpose of this guide is to help you create a GitHub account and a GitHub OAuth app - if you're looking for step-by-step instructions using Clerk to add social connection (OAuth) to your application, follow the [Social connection (OAuth) guide](/docs/authentication/social-connections/oauth).
### Create a GitHub app

## Before you start
1. On a separate page, go to [GitHub's Developer Settings](https://github.com/settings/apps).
1. In the sidebar, select **OAuth Apps**, then select [**New OAuth app**](https://github.com/settings/applications/new). You'll be redirected to the **Register a new OAuth app** form.
1. Enter your **Application name** and **Homepage URL**.
1. In **Authorization callback URL**, paste the **Authorized Redirect URI** you saved from the Clerk Dashboard.
1. Select **Register application**. You'll be redirected to your GitHub app's **General** page.

- You need to create a Clerk Application in your [Clerk Dashboard](https://dashboard.clerk.com/). For more information, check out our [Set up your application guide](/docs/quickstarts/setup-clerk).
- You need to have a GitHub account. To create one, [click here](https://github.com/signup).
### Set the Client ID and Client Secret in your Clerk Dashboard

## Configuring GitHub social connection
1. In the GitHub app's **General** page, select **Generate a new client secret**. Save your **Client ID** and **Client secret** somewhere secure.
1. Navigate back to your Clerk Dashboard where the modal should still be open and paste these values into the respective fields.
1. Select **Add connection**.

First, you need to register a new OAuth GitHub app. Follow the official GitHub instructions on [how to create an OAuth app](https://docs.github.com/en/developers/apps/building-oauth-apps/creating-an-oauth-app).
> [!NOTE]
> If the modal or page is not still open, navigate to the [**SSO Connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page in the Clerk Dashboard. Select the GitHub connection. Under **Use custom credentials**, you can paste the **Client ID** and **Client Secret** into their respective fields.

![Registering an OAuth GitHub app](/docs/images/authentication-providers/github/ff83ad81ca491cf17e5a755376fae9c88148ce7c-1395x799.png)
### Test your OAuth

Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections). In the top navigation, select **Configure**. Then in the sidebar, select **SSO Connections**. Select the **Add connection** button, and select **For all users**. In the **Choose provider** dropdown, select **GitHub**. Toggle on **Use custom credentials** and copy **Authorized redirect URI**. Go back to the GitHub panel, paste the value into the **Authorization callback URL** field and complete the registration.
The simplest way to test your OAuth is to visit your Clerk app's [Account Portal](/docs/customization/account-portal/overview), which is available for all Clerk apps out-of-the-box.

Once registration is complete, you'll get redirected to project's admin panel. Click the **Generate a new client secret** button to get your new client secret. Then, copy the **Client ID** and **Client secret.** Go back to the Clerk Dashboard and paste them into the respective fields.
1. In the Clerk Dashboard, navigate to the [**Account Portal**](https://dashboard.clerk.com/last-active?path=account-portal) page.
1. Next to the **Sign-in** URL, select **Visit**. The URL should resemble:

![Obtaining the Client ID and Client secret](/docs/images/authentication-providers/github/3b1f58462fab3cc238c1a59994d1e2eb98f46b73-1489x964.png)
- **For development** – `https://your-domain.accounts.dev/sign-in`
- **For production** – `https://accounts.your-domain.com/sign-in`

Finally, select **Add connection** so that the settings are applied. Congratulations! Social connection with GitHub is now configured for your instance.
1. Sign in with your GitHub account.
</Steps>
Loading