From 2b373d49e0e5905fcd8110b1cefa3c8eb18cc8c4 Mon Sep 17 00:00:00 2001 From: victoria Date: Tue, 22 Oct 2024 21:29:45 +0200 Subject: [PATCH] (authentication/social-connections/linear) update guide (#1630) Co-authored-by: Alexis Aguilar <98043211+alexisintech@users.noreply.github.com> --- .../social-connections/linear.mdx | 79 ++++++++++++++----- 1 file changed, 60 insertions(+), 19 deletions(-) diff --git a/docs/authentication/social-connections/linear.mdx b/docs/authentication/social-connections/linear.mdx index 4722ae6656..b20f4e6db2 100644 --- a/docs/authentication/social-connections/linear.mdx +++ b/docs/authentication/social-connections/linear.mdx @@ -1,38 +1,79 @@ --- title: Add Linear as a social connection -description: Learn how to set up social connection with Linear. +description: Learn how to allow users to sign up and sign in to your Clerk app with their Linear account using OAuth. --- -How to set up social connection with Linear + + - Use Linear to authenticate users with OAuth + -## Overview +Enabling OAuth with [Linear](https://developers.linear.app/docs/oauth/authentication) allows your users to sign up and sign in to your Clerk app with their Linear account. -Adding social connection with Linear to your app with Clerk is done in a few steps - you only need to set the **Client ID**, **Client Secret** and **Authorized redirect URL** in your instance settings. +> [!IMPORTANT] +> You must be a workspace admin to create and manage OAuth apps in Linear. -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. +## Configure for your development instance -For production instances, you will need to generate your own Client ID and Client secret using your Linear account. +For _development instances_, Clerk uses preconfigured shared OAuth credentials and redirect URIs—no other configuration is needed. -> [!NOTE] -> The purpose of this guide is to help you create a Linear 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). +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 select **For all users**. +1. In the **Choose provider** dropdown, select **Linear**. +1. Select **Add connection**. -## Before you start +## Configure for your production instance -- 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 Linear account. To create one, [click here](https://linear.app). +For _production instances_, you must provide custom credentials which involves generating your own **Client ID** and **Client Secret** using your Linear account. -## Configuring Linear social connection +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 [Linear's API settings](https://linear.app/clerk/settings/api) page. -First, you need to create a new OAuth Linear app. Navigate on your **Settings > Account > API > OAuth applications** and click on **Create new**. On the modal that pops up, enter all the necessary info for your new app such as the name, the logo etc. + + ### Enable Linear as a social connection in Clerk -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 **Linear**. Toggle on **Use custom credentials** and copy **Redirect URI**. Paste this value in the Callback URLs field of your Linear application. + 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 select **For all users**. + 1. In the **Choose provider** dropdown, select **Linear**. + 1. Ensure that both **Enable for sign-up and sign-in** and **Use custom credentials** are toggled on. + 1. Save the **Redirect URI** somewhere secure. Keep the modal and page open. -![Creating a new application](/docs/images/authentication-providers/linear/creating-new-application.jpg) -When you have filled all the necessary info, click **Create**. Congratulations, you have successfully created your Linear OAuth application. + ### Create a Linear app -![Copying values from the Linear dashboard](/docs/images/authentication-providers/linear/copying-values-from-linear-dashboard.jpg) + 1. In the top-left of [Linear](https://linear.app/), select your workspace, then select **Preferences**. + 1. In the sidebar, under **My Account**, select **API**. Scroll down to **OAuth Applications** and select **Create new OAuth Application**. You'll be navigated to the [**Create new application**](https://linear.app/clerk/settings/api/applications/new) page. + 1. Complete the required fields. In **Callback URLs**, paste the **Redirect URI** you saved from the Clerk Dashboard. + 1. Select **Save**. The page will refresh and you should the **Client ID** and **Client Secret** at the top. Save both values somewhere secure. Keep this page open. -Copy the **Client ID** and **Client secret** as shown in the above image from the **Basic Information** menu of your app. Go back to the Clerk Dashboard and paste them into the respective fields. + ### Set the Client ID and Client Secret in your Clerk Dashboard -Don't forget to click **Apply** in the Clerk dashboard. Congratulations! Social connection with Linear is now configured for your instance. + 1. Navigate back to your Clerk Dashboard where the modal should still be open. Paste these values into the respective fields. + 1. Select **Add connection**. + + > [!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 Linear connection. Under **Use custom credentials**, you can paste the **Client ID** and **Client Secret** into their respective fields. + + ### Test your OAuth + + 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. + + 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: + + - **For development** – `https://your-domain.accounts.dev/sign-in` + - **For production** – `https://accounts.your-domain.com/sign-in` + + 1. Sign in with your Linear account. +