-
Notifications
You must be signed in to change notification settings - Fork 533
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
35 changed files
with
625 additions
and
912 deletions.
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 +1,4 @@ | ||
| * @clerk/docs | ||
|
|
||
| # Help keep docs quickstart content in sync with Dashboard | ||
| docs/quickstarts/* @clerk/growth |
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,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 | ||
| <TutorialHero | ||
| beforeYouStart={[ | ||
| { | ||
| title: "A Clerk app is required.", | ||
| link: "/docs/quickstarts/setup-clerk", | ||
| icon: "clerk", | ||
| }, | ||
| { | ||
| title: "A Slack account is required.", | ||
| link: "https://slack.com/get-started#/createnew", | ||
| icon: "user-circle", | ||
| }, | ||
| ]} | ||
| > | ||
| - Use Slack to authenticate users with OAuth | ||
| </TutorialHero> | ||
|
|
||
| ## 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). | ||
| <Steps> | ||
| ### 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 | ||
|
|
||
|  | ||
| 1. In the Slack API Platform, navigate to the [**Your Apps**](https://api.slack.com/apps) page and 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's doc 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 **Add**, 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 | ||
|
|
||
|  | ||
| 1. Navigate back to your Clerk Dashboard where the modal should still be open. Paste the **Client ID** and **Client Secret** values that you saved 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. | ||
| </Steps> |
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 |
|---|---|---|
| @@ -0,0 +1,89 @@ | ||
| --- | ||
| title: Handling requests with a JS Backend SDK | ||
| description: Learn how to handle authenticated requests with one of Clerk's JS Backend SDKs. | ||
| --- | ||
|
|
||
| To handle authenticated requests, use one of the following JS Backend SDKs. | ||
|
|
||
| ## Clerk Express SDK | ||
|
|
||
| The `clerkMiddleware()` function checks the request's cookies and headers for a session JWT. If the user has a valid session, the `clerkMiddleware()` function attaches the [properties](/docs/references/nextjs/auth-object#auth-object-properties) of the authenticated user to the request object. | ||
|
|
||
| ```js | ||
| import { clerkMiddleware } from '@clerk/express' | ||
|
|
||
| const app = express() | ||
|
|
||
| // Pass no parameters | ||
| app.use(clerkMiddleware()) | ||
|
|
||
| // Pass options | ||
| app.use(clerkMiddleware(options)) | ||
| ``` | ||
|
|
||
| For more information on the Middleware functions and SDK features, see the [Express SDK](/docs/references/express/overview) page. | ||
|
|
||
| ## Clerk Fastify SDK | ||
|
|
||
| The `clerkPlugin` checks the request's cookies and headers for a session JWT. If the user has a valid session, the `clerkPlugin` attaches the [properties](/docs/references/nextjs/auth-object#auth-object-properties) of the authenticated user to the request object. | ||
|
|
||
| ```ts | ||
| import 'dotenv/config' | ||
| import Fastify from 'fastify' | ||
| import { clerkClient, clerkPlugin, getAuth } from '@clerk/fastify' | ||
|
|
||
| const fastify = Fastify({ logger: true }) | ||
|
|
||
| fastify.register(clerkPlugin) | ||
|
|
||
| fastify.get('/', async (request, reply) => { | ||
| const { userId } = getAuth(request) | ||
|
|
||
| // Protect the route from unauthenticated users | ||
| if (!userId) { | ||
| return reply.code(403).send({ error: 'Unauthorized request.' }) | ||
| } | ||
|
|
||
| const user = userId ? await clerkClient.users.getUser(userId) : null | ||
|
|
||
| return reply.send({ | ||
| message: 'User retrieved successfully.', | ||
| user, | ||
| }) | ||
| }) | ||
|
|
||
| const start = async () => { | ||
| try { | ||
| await fastify.listen({ port: 8080 }) | ||
| } catch (error) { | ||
| fastify.log.error(error) | ||
| process.exit(1) | ||
| } | ||
| } | ||
|
|
||
| start() | ||
| ``` | ||
|
|
||
| For more information on the Clerk plugin and SDK features, see the [Fastify SDK](/docs/quickstarts/fastify) page. | ||
|
|
||
| ## Clerk Backend SDK | ||
|
|
||
| If you're not using Express or Fastify, use the `@clerk/backend` package to access `clerkClient`. | ||
|
|
||
| ```ts | ||
| import { createClerkClient } from '@clerk/backend' | ||
|
|
||
| const clerkClient = createClerkClient({ | ||
| secretKey: process.env.CLERK_SECRET_KEY, | ||
| publishableKey: process.env.CLERK_PUBLISHABLE_KEY, | ||
| }) | ||
|
|
||
| const { isSignedIn } = await clerkClient.authenticateRequest(req, { | ||
| jwtKey: process.env.CLERK_JWT_KEY, | ||
| authorizedParties: ['https://example.com'], | ||
| }) | ||
|
|
||
| if (!isSignedIn) { | ||
| return Response.json({ status: 401 }) | ||
| } | ||
| ``` |
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
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
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
Oops, something went wrong.