From 0fb8185bb1156e77e5fef4cc18f6d7d8fd6167a8 Mon Sep 17 00:00:00 2001 From: vi Date: Wed, 23 Oct 2024 17:19:48 +0200 Subject: [PATCH] update guide --- .../social-connections/slack.mdx | 77 ++++++++++++++----- 1 file changed, 57 insertions(+), 20 deletions(-) diff --git a/docs/authentication/social-connections/slack.mdx b/docs/authentication/social-connections/slack.mdx index 7ae143a044..d18922004d 100644 --- a/docs/authentication/social-connections/slack.mdx +++ b/docs/authentication/social-connections/slack.mdx @@ -1,39 +1,76 @@ --- title: Add Slack as a social connection -description: Learn how to set up social connection with Slack. +description: Learn how to allow users to sign up and sign in to your Clerk app with their Slack account using OAuth. --- -How to set up social connection with Slack + + - Use Slack to authenticate users with OAuth + -## Overview +Enabling OAuth with [Slack](https://api.slack.com/authentication) allows your users to sign up and sign in to your Clerk app with their Slack account. -Adding social connection with Slack 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. +## Configure for your development instance -> [!NOTE] -> Please note that Sign in with Slack doesn't support any additional OAuth scopes other than **openid**, **email**, **profile**, which are requested by default +For _development instances_, Clerk uses preconfigured shared OAuth credentials and redirect URIs—no other configuration is needed. -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. +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 **Slack**. +1. Select **Add connection**. -For production instances, you will need to generate your own Client ID and Client secret using your Slack account. +## Configure for your production instance -> [!NOTE] -> The purpose of this guide is to help you create a Slack 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). +For _production instances_, you must provide custom credentials which involves generating your own **Client ID** and **Client Secret** using your Slack account. -## Before you start +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 [Slack's API Platform](https://api.slack.com/). -- 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 Slack account. To create one, [click here](https://slack.com/get-started#/createnew). + + ### Enable Slack as a social connection in Clerk -## Configuring Slack social connection + 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 **Slack**. + 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. -First, you need to create a new OAuth Slack app. On the main [Slack apps page](https://api.slack.com/apps), click on **Create new app**. On the modal that pops up, choose **From scratch,** enter your application name and choose a Slack workspace to associate with it. + ### Create a Slack app -![Creating a new application](/docs/images/authentication-providers/slack/creating-new-application.jpg) + 1. In the [**Your Apps**](https://api.slack.com/apps) page on the Slack API Platform, select **Create an App**. + 1. A modal will open. Depending on your app needs, select either **From a manifest** for **From scratch**. For more information on which to choose, refer to [Slack docs on manifests](https://api.slack.com/reference/manifests). + 1. After following the respective steps for either option, you'll be redirected to the **App Credentials** page. Save the **Client ID** and **Client Secret** somewhere secure. Keep this page open. + 1. In the sidebar, navigate to the **OAuth & Permissions** page. + 1. Scroll down to the **Redirect URLs** section and paste the **Redirect URI** you saved from the Clerk Dashboard. Select **Done** then select **Save URLs**. -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 **Slack**. Toggle on **Use custom credentials** and copy **Redirect URI**. Navigate to **OAuth & Permissions > Redirect URLs** and paste the value to add a new record. + ### Set the Client ID and Client Secret in your Clerk Dashboard -![Copying values from the Slack dashboard](/docs/images/authentication-providers/slack/copying-values-from-slack-dashboard.jpg) + 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**. -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. + > [!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 Slack connection. Under **Use custom credentials**, you can paste the **Client ID** and **Client Secret** into their respective fields. -Finally, select **Add connection** so that the settings are applied. Congratulations! Social connection with Slack is now configured for your instance. + ### 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 Slack account. +