(social-connections/atlassian) update guide (#1865)

Co-authored-by: vi <[email protected]>

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-and-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>