branch 'main' into aa/update-component-references

docs/_partials/authentication/set-client-id-secret.mdx

@@ -0,0 +1,5 @@
+1. Navigate back to the 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**.
+
+> [!NOTE]
+> If the modal or page is no longer open, navigate to the [**SSO connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page in the Clerk Dashboard. Select the connection. Under **Use custom credentials**, paste the values into their respective fields.

docs/_partials/authentication/test-your-connection.mdx

@@ -0,0 +1,9 @@
+The simplest way to test your connection 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 connection's credentials.

docs/authentication/enterprise-connections/easie/google.mdx

@@ -42,7 +42,7 @@ For _development instances_, Clerk uses preconfigured shared credentials and red
 > [!WARNING]
 > If you already [configured Google as a social provider](/docs/authentication/social-connections/google), you can skip this step. EASIE SSO will automatically use the credentials you configured for your social connection.
 
-For _production instances_, you must provide custom credentials, which involves generating your own **Client ID** and **Client Secret** using your Google Developer account.
+For _production instances_, you must provide custom credentials.
 
 To make the setup process easier, it's recommended to keep two browser tabs open: one for the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) and one for your [Google Cloud Console](https://console.cloud.google.com/).
 

docs/authentication/enterprise-connections/easie/microsoft.mdx

@@ -42,7 +42,7 @@ For _development instances_, Clerk uses preconfigured shared credentials and red
 > [!WARNING]
 > If you already [configured Microsoft as a social provider](/docs/authentication/social-connections/microsoft), you can skip this step. EASIE SSO will automatically use the credentials you configured for your social connection.
 
-For _production instances_, you must provide custom credentials, which involves generating your own **Client ID** and **Client Secret** using your Microsoft Entra ID account.
+For _production instances_, you must provide custom credentials.
 
 To make the setup process easier, it's recommended to keep two browser tabs open: one for the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) and one for your [Microsoft Azure portal](https://portal.azure.com).
 

docs/authentication/social-connections/apple.mdx

@@ -117,7 +117,7 @@ To make the setup process easier, it's recommended to keep two browser tabs open
   1. Under **Sign in with Apple for Email Communication**, select **Configure**. You'll be redirected to the **Configure Sign in with Apple for Email Communication** page.
   1. Next to **Email Sources** at the top of the page, select the plus icon (+) to add a new **Email Source**.
   1. In the **Register your email sources** modal that opens, under **Email Addresses**, add the **Email Source for Apple Private Email Relay** value that you saved from the Clerk Dashboard. It should look something like this: `[email protected]`.
-  1. Select **Next**. The modal will redirect to the **Confirm your email sources** page.
+  1. Select **Next**. The modal will redirect to the **Confirm your email sources** screen.
   1. Select **Register**. The modal will redirect to the **Email Source Registration Complete** screen.
   1. Select **Done**.
 
@@ -161,13 +161,7 @@ To make the setup process easier, it's recommended to keep two browser tabs open
   1. Add all the corresponding fields depending on your desired flow. For the **Apple Private Key** file, open it with a text editor and copy/paste the contents.
   1. Select **Add connection**.
 
-  ### Test your OAuth
+  ### Test your connection
 
-  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 Apple account.
+  <Include src="_partials/authentication/test-your-connection" />
 </Steps>

docs/authentication/social-connections/atlassian.mdx

@@ -1,89 +1,82 @@
 ---
 title: Add Atlassian as a social connection
-description: Learn how to set up social connection with Atlassian.
+description: Learn how to allow users to sign up and sign in to your Clerk app with their Atlassian account using OAuth.
 ---
 
-How to set up social connection with Atlassian
+<TutorialHero
+  beforeYouStart={[
+    {
+      title: "A Clerk app is required.",
+      link: "/docs/quickstarts/setup-clerk",
+      icon: "clerk",
+    },
+    {
+      title: "An Atlassian account is required.",
+      link: "https://developer.atlassian.com/",
+      icon: "user-circle",
+    }
+  ]}
+>
+  - Use Atlassian to authenticate users with OAuth
+</TutorialHero>
 
-## Overview
+Enabling OAuth with Atlassian allows your users to sign up and sign in to your Clerk app with their Atlassian account.
 
-Adding social connection with Atlassian to your app with Clerk is done in a few steps - you will need to populate the **Client ID**, **Client Secret** and **Redirect URI** in your instance settings.
+## Configure for your development instance
 
-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.
+For _development instances_, Clerk uses preconfigured shared OAuth credentials and redirect URIs—no other configuration is needed.
 
-For production instances, you will need to generate your own Client ID and Client Secret using your Atlassian 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 select **For all users**.
+1. In the **Choose provider** dropdown, select **Atlassian**.
+1. Select **Add connection**.
 
-> [!NOTE]
-> The purpose of this guide is to help you create an Atlassian account and an Atlassian OAuth 2.0 Integration - 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).
+## Configure for your production instance
 
-## Before you start
+For _production instances_, you must provide custom credentials.
 
-- You need to create a Clerk Application in the [Clerk Dashboard](https://dashboard.clerk.com/). For more information, see the [setup guide](/docs/quickstarts/setup-clerk).
-- You need to have a Atlassian developer account. To create one, [click here](https://developer.atlassian.com/).
+To make the setup process easier, it's recommended to keep two browser tabs open: one for the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) and one for your [Atlassian Developer console](https://developer.atlassian.com/console/myapps/).
 
-## Configuring an Atlassian OAuth 2.0 Integration
+<Steps>
+  ### Enable Atlassian as a social connection
 
-You can navigate to the [list of all your apps](https://developer.atlassian.com/console/myapps/) to select an existing app or create a new one:
+  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 **Atlassian**.
+  1. Ensure that both **Enable for sign-up and sign-in** and **Use custom credentials** are toggled on.
+  1. Save the **Callback URL** somewhere secure. Keep this modal and page open.
 
-![Atlassian app listing](/docs/images/authentication-providers/atlassian/37ec3daaa6d6eaa060ad7fecb112ae6d1ef46597-3456x1844.png)
+  ### Create an Atlassian workspace
 
-From there, click on the desired existing app or create a new one, which will take you to the app page.
+  > [!TIP]
+  > If you already have an Atlassian workspace you'd like to connect to Clerk, select your workspace from the [Atlassian Developer console](https://developer.atlassian.com/console/myapps/) and skip to [the next step in this tutorial](#configure-your-atlassian-app).
 
-![Atlassian OAuth 2.0 app page](/docs/images/authentication-providers/atlassian/597e9bdc5a6b521bcbf8223c04a1102683bf9231-3456x1730.png)
+  1. In the [Atlassian Developer console](https://developer.atlassian.com/console/myapps/), next to **My apps**, select **Create**. Then, select **OAuth 2.0 integration**. You'll be redirected to the **Create a new OAuth 2.0 (3LO) integration** page.
+  1. Fill out the necessary information. Then, select **Create**. Once the integration is created, you'll be redirected to the app's **Overview** page.
 
-While not necessary for the integration to work, you can edit your app name, description and set a logo for it in the **Settings** tab.
+  ### Configure your Atlassian app
 
-![Atlassian OAuth 2.0 settings page](/docs/images/authentication-providers/atlassian/b2762ea10eebe6f05f39aa9ed33c54ca41bc2f3d-3456x1730.png)
+  1. In the left sidebar of your app's **Overview** page, select **Permissions**. Configure the OAuth 2.0 scopes to request from your users when they connect with Atlassian. At a minimum, next to **User identity API**, select **Add**.
+  1. In the left sidebar, select **Authorization**.
+  1. Next to **OAuth 2.0 (3LO)**, select **Add**.
+  1. In the **Callback URL** field, paste the **Callback URL** you saved from the Clerk Dashboard.
+  1. Select **Save changes**.
+  1. In the left sidebar, select **Settings**.
+  1. Under **Authentication details**, save the **Client ID** and **Secret** somewhere secure.
+  1. In the left sidebar, select **Distribution**.
+  1. Select **Edit**.
+  1. Set the **Distribution Status** to **Sharing**.
+  1. Complete the required fields. For **Does your app store personal data?**, select **Yes**, as Clerk uses the user's personal data to authenticate them.
+  1. Select **Save changes**.
 
-From the app page, click on the **Permissions** tab in the sidebar menu.
+  ### Set the Client ID and Secret in the Clerk Dashboard
 
-![Atlassian OAuth 2.0 Integration permissions](/docs/images/authentication-providers/atlassian/04fa49b7d9ba58c0faf2c2b97f85b5ea17a9ebe6-3456x1730.png)
+  <Include src="_partials/authentication/set-client-id-secret" />
 
-Here, you will need to configure the OAuth 2.0 scopes that should be requested from your users when they attempt to connect with Atlassian.
+  ### Test your connection
 
-At the very minimum, you will need to enable the **User identity API**, which corresponds to the `read:me` OAuth 2.0 scope. This enables Clerk to retrieve basic user profile info when creating users for your app.
+  > [!WARNING]
+  > To be able to connect, the user must have access to at least one Atlassian site (e.g. JIRA, Confluence). Currently, the user can authorize access only to a single Atlassian site.
 
-Afterwards, you will need to set up the Callback URL so that Atlassian can redirect back to your Clerk app upon successful connection.
-
-This is done by navigating to the Authorization section and clicking on Add.
-
-![Atlassian OAuth 2.0 Authorization page](/docs/images/authentication-providers/atlassian/3d60a54bb48c03257afbf769f1f50cf45f18871c-3456x1730.png)
-
-In this section, you will need to paste the Redirect URI that Clerk has provided for you.
-
-![Atlassian OAuth 2.0 App callback URL settings](/docs/images/authentication-providers/atlassian/a6dc9bd0902359cad9c94de1bdcbd4c9112bff1d-3456x1730.png)
-
-After entering the callback URL, the Client ID & Client Secret will now be available in the **Settings** tab:
-
-![Atlassian OAuth 2.0 settings page with Client ID & Client Secret](/docs/images/authentication-providers/atlassian/fdc89459cdc6450c4dbde713e7b840d93b01c862-3456x1730.png)
-
-You will need to copy these values and paste:
-
-- The Atlassian Client ID to the **Client ID** input on Clerk
-- The Atlassian Client Secret to the **Client Secret** input on Clerk
-
-![Client ID and Client Secret inputs for Atlassian connection](/docs/images/authentication-providers/atlassian/6ef7100945fb68a379b35a5c295a76405a2cf10e-1156x1354.png)
-
-If you have enabled further scopes on Atlassian, you can add them in the  Clerk Atlassian configuration settings as well. This will affect the  tokens that Atlassian issues to you, so that you can access the intended Atlassian resources.
-
-Finally, you will need to make your Atlassian app publicly accessible, since it  starts out as private by default. This is done from the **Distribution** tab:
-
-![Atlassian OAuth 2.0 app distribution settings](/docs/images/authentication-providers/atlassian/83d5498c454f5ba0b92a76c4a1942e9a07cde48d-3456x1730.png)
-
-After clicking on **Edit**, you will need to provide the following information and save the form:
-
-- Set the distribution status to **Sharing**
-- Enter your vendor name
-- Enter a link to your privacy policy page
-- Enter a link to yout terms page
-- Add a contact page link (optional)
-- Indicate that your data _does_ store data, since at the very least the user profile info is used to create users on the Clerk end
-
-![Atlassian OAuth2 distribution sharing form](/docs/images/authentication-providers/atlassian/07c724b9a66773c94c169cc2a199a549c45d8fdd-3456x1730.png)
-
-Notes:
-
-- To be able to connect, the user must have access to at least one Atlassian site (e.g. JIRA, Confluence)
-- Currently the user can authorize access only to a single Atlassian site
-
-Congratulations! Social connection with Atlassian is now configured for your instance.
+  <Include src="_partials/authentication/test-your-connection" />
+</Steps>