From 74939e4c49493d5246482001cfea5a8d457f6bdd Mon Sep 17 00:00:00 2001 From: victoria Date: Fri, 11 Oct 2024 22:24:57 +0200 Subject: [PATCH] (/authentication/social-connections/github) update guide (#1602) Co-authored-by: Alexis Aguilar <98043211+alexisintech@users.noreply.github.com> --- .../social-connections/github.mdx | 78 ++++++++++++++----- 1 file changed, 60 insertions(+), 18 deletions(-) diff --git a/docs/authentication/social-connections/github.mdx b/docs/authentication/social-connections/github.mdx index d9fd793902..d553bc1419 100644 --- a/docs/authentication/social-connections/github.mdx +++ b/docs/authentication/social-connections/github.mdx @@ -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 + + - Use GitHub to authenticate users with OAuth + + +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. + + ### 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. +