-
Notifications
You must be signed in to change notification settings - Fork 484
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
Changes from 18 commits
Commits
Show all changes
20 commits
Select commit
Hold shift + click to select a range
526181c
change title
victoriaxyz 6416a97
draft
victoriaxyz ca049f0
Merge branch 'main' into vi/docs-363/oauth-github
victoriaxyz 43ddb26
Merge branch 'main' into vi/docs-363/oauth-github
victoriaxyz 04e7bcb
update
victoriaxyz 21b6cce
Merge branch 'main' into vi/docs-363/oauth-github
victoriaxyz 650aa9e
Update docs/authentication/social-connections/github.mdx
victoriaxyz 4e94904
Update docs/authentication/social-connections/github.mdx
victoriaxyz 09382cd
Update docs/authentication/social-connections/github.mdx
victoriaxyz 3e71d72
Update docs/authentication/social-connections/github.mdx
victoriaxyz 32ff4f5
Update docs/authentication/social-connections/github.mdx
victoriaxyz 67e0de7
Update docs/authentication/social-connections/github.mdx
victoriaxyz 514da1c
Update docs/authentication/social-connections/github.mdx
victoriaxyz 4725c13
Merge branch 'main' into vi/docs-363/oauth-github
victoriaxyz 88282e1
Merge branch 'main' into vi/docs-363/oauth-github
victoriaxyz 8b98b76
update
victoriaxyz 0e32e6b
fix
victoriaxyz 77a91de
Merge branch 'main' into vi/docs-363/oauth-github
victoriaxyz 9824905
Update docs/authentication/social-connections/github.mdx
alexisintech 4a2e32e
Update docs/authentication/social-connections/github.mdx
alexisintech File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,36 +1,79 @@ | ||
--- | ||
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. | ||
1. Select **Generate a new client secret**. | ||
alexisintech marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
- 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, save your **Client ID** and **Client secret** somewhere secure. | ||
alexisintech marked this conversation as resolved.
Show resolved
Hide resolved
|
||
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> |
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
should we move this to the next step? see the next comment