feat: EASIE documentation

docs/authentication/enterprise-connections/account-linking.mdx

@@ -0,0 +1,33 @@
+---
+title: Account linking
+description: Learn how Clerk handles account linking during Enterprise SSO.
+---
+
+Account linking is the process of connecting multiple user accounts from different services or platforms, allowing users to access various services with a single set of credentials. It enables seamless sign-in using Enterprise SSO alongside other authentication methods like username/password. Clerk automatically attempts to link accounts that share the same email address, assuming a single owner for each email.
+
+## How it works
+
+When a user attempts to sign in or up, Clerk checks if the email address from the Identity Provider (IdP) matches an existing account and attempts to link them. Email addresses from IdPs are considered verified by default.
+
+The following sections explain the different scenarios that can occur during this process and how Clerk handles each one.
+
+![Flow chart of the SAML SSO account linking process in various scenarios.](/docs/images/authentication/account-linking-flow-saml.webp)
+
+### Email is verified in Clerk
+
+When a user signs into your app using an IdP that returns a matching verified email address, Clerk automatically links the Enterprise SSO account to the existing account and completes the sign-in process. This includes accounts protected by passwords, as the Enterprise SSO sign-in flow automatically bypasses password verification.
+
+### Email is not verified and verification isn't required
+
+By default, Clerk requires email verification at sign-up. For instances that have disabled this behavior, there's a possibility that an account may be created using an unverified email address.
+
+To configure email verification at sign-up:
+
+1. In the Clerk Dashboard, navigate to the [**Email, Phone, Username**](https://dashboard.clerk.com/last-active?path=user-authentication/email-phone-username) page.
+1. Next to **Email address**, select the settings icon and disable the **Verify at sign-up** toggle.
+
+When a user signs into your app using an IdP, Clerk automatically links the Enterprise SSO account to the existing account by **also verifying the existing email address** and signing the user in. This includes accounts protected by passwords, as the Enterprise SSO sign-in flow automatically bypasses password verification.
+
+### Email is not verified
+
+When a user signs into your app using an IdP that returns a matching unverified email address, Clerk doesn't link the Enterprise SSO account to the existing account, but instead signs the user up and creates a completely new account.

docs/authentication/enterprise-connections/authentication-flows.mdx

@@ -0,0 +1,58 @@
+---
+title: Enterprise SSO authentication flows
+description: Learn about the Enterprise SSO authentication flows.
+---
+
+There are two types of Enterprise SSO connections: [EASIE](#easie) and [SAML](#saml).
+
+## EASIE
+
+EASIE connections support the authentication flows described at [easie.dev](https://easie.dev).
+
+## SAML
+
+The SAML protocol supports two methods to start an SSO flow: [Service Provider-initiated (SP-initiated)](#service-provider-initiated-flow-recommended) and [Identity Provider-initiated (IdP-initiated)](#identity-provider-initiated-flow).
+
+For the best security practices, it's recommended to use the SP-initiated flow wherever possible. If you decide to enable IdP-initiated flows, ensure that proper [security measures](#clerks-security-measures), such as MFA and short validation periods, are in place to mitigate the associated risks.
+
+### Service Provider-initiated flow (recommended)
+
+In an SP-initiated flow:
+
+- The user starts the authentication process from your application (Service Provider, or SP), by providing their email address.
+- The user is redirected to the SAML provider (Identity Provider, or IdP) where they must authenticate.
+- After successful authentication, the user is redirected back to your app, gaining access to their account.
+
+### Identity Provider-initiated flow
+
+In an IdP-initiated flow:
+
+- The user starts the authentication flow from the SAML provider (IdP) by selecting which app (SP) they want to access.
+- The user is redirected to the app of their choice, gaining access to their account.
+
+> [!NOTE]
+> IdP-Initiated flow carries a [security risk](#risks-of-id-p-initiated-flow). It is recommended to use an SP-Initiated flow whenever possible.
+
+To allow IdP-initiated flows for your SAML 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 specific domains**.
+1. Select your **Identity Provider**. Complete the fields and select **Add connection**. You'll be redirected to the SAML connection's configuration page.
+1. Select the **Advanced** tab.
+1. In **Advanced Settings**, enable **Allow IdP-Initiated flow**. A modal will open. Select **Enable** to confirm.
+1. Select **Save**.
+
+#### Risks of IdP-initiated flow
+
+While IdP-initiated flows might offer convenience, they are also susceptible to security risks, such as [meddler-in-the-middle (MITM) attacks](https://en.wikipedia.org/wiki/Man-in-the-middle_attack). A bad actor might hijack the IdP response to gain access to a compromised account.
+
+When enabling an IdP-initiated flow, it's possible for Clerk to receive unsolicited authentication requests, which neither the SP nor IdP can verify were initiated by the specified user. Additionally, a bad actor could intercept the IdP response and replace it, performing a CSRF attack to sign in as the attacker.
+
+#### Clerk's security measures
+
+To mitigate the risks associated with IdP-initiated flows, Clerk implements several security measures:
+
+- **Unsolicited `InResponseTo` attribute**: Clerk ensures that unsolicited responses don't contain an `InResponseTo` attribute, in accordance with the [SAML 2.0 profiles specification](https://docs.oasis-open.org/security/saml/v2.0/saml-profiles-2.0-os.pdf). This prevents bad actors from stealing a response used in an SP-initiated flow and using it in an IdP-initiated flow.
+- **Replay detection**: Clerk consumes and remembers each response to prevent re-use. This ensures that bad actors cannot steal and reuse a response to gain access to a user's account.
+- **Multi-factor authentication**: Clerk supports [multi-factor authentication (MFA)](/docs/authentication/configuration/sign-up-sign-in-options#multi-factor-authentication) for SAML IdP-initiated flows. MFA requires users to provide two or more forms of verification, which significantly enhances security by reducing the risk of unauthorized access.
+- **Use small validation periods**: Each SAML response contains a timestamp indicating when it was issued and when it will expire. Since IdP-initiated flows are expected to be completed within seconds, validation periods must be as small as possible to prevent attacks. Common IdP providers such as Azure, Google, and Okta handle this by default. However, if you're using a custom IdP, you must ensure that the validation periods are set correctly.

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

@@ -0,0 +1,76 @@
+---
+title: Add Google as an EASIE connection
+description: Learn how to allow users to sign up and sign in to your Clerk app with their Google account using EASIE SSO.
+---
+
+<TutorialHero
+  beforeYouStart={[
+    {
+      title: "Add the Enhanced authentication add-on to your Pro plan",
+      link: "/pricing",
+      icon: "plus-circle",
+    },
+    {
+      title: "Enable email address as an identifier for your application.",
+      link: "/docs/authentication/configuration/sign-up-sign-in-options#identifiers",
+      icon: "key",
+    },
+    {
+      title: "A Google Developer account is required.",
+      link: "https://console.developers.google.com/",
+      icon: "user-circle",
+    }
+  ]}
+>
+  - Use Google to authenticate users with EASIE SSO.
+</TutorialHero>
+
+Enabling EASIE SSO with Google allows your users to sign up and sign in to your Clerk application with their Google account.
+
+## Configure for your development instance
+
+For _development instances_, Clerk uses preconfigured shared credentials and redirect URIs—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 specific domains**.
+1. Under **EASIE**, select **Google** as the identity provider.
+1. Add the **Specific Domain** that you want to allow this connection for. This is the domain of the users you want to allow to sign in to your app.
+1. Select **Add connection**.
+
+## Configure for your production instance
+
+> [!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.
+
+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 [Google Cloud Console](https://console.cloud.google.com/).
+
+<Steps>
+  ### Enable Google as an EASIE 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 specific domains**.
+  1. Below EASIE, select **Google** as the identity provider.
+  1. Add the **Specific Domain** that you want to allow this connection for. This is the domain of the users you want to allow to sign in to your application.
+  1. Select **Add connection**.
+  1. Ensure that **Use custom credentials** is toggled on.
+  1. Save the **Redirect URI** somewhere secure.
+
+  ### Create a Google Developer project
+
+  1. Navigate to the [Google Cloud Console](https://console.cloud.google.com/).
+  1. Select a project or [create a new one](https://console.cloud.google.com/projectcreate).
+  1. If the **APIs & Services** page isn't already open, open the menu on the left and select **APIs & Services**.
+  1. In the menu on the left, select **Credentials**.
+  1. Select **Create Credentials**. Then, select **OAuth client ID.** You may need to [configure your OAuth consent screen](https://support.google.com/cloud/answer/6158849?hl=en#userconsent\&zippy=%2Cuser-consent).
+  1. Select the appropriate application type for your project. Most likely, you will choose **Web application**.
+  1. In the **Authorized redirect URIs** setting, paste the **Redirect URI** value you saved from the Clerk Dashboard.
+  1. Select **Create**. Keep this page open.
+
+  ### Set the Client ID and Client Secret in your Clerk Dashboard
+
+  Once the OAuth client is created in the Google Cloud Console, a modal will open with your **Client ID** and **Client Secret**. Save these values somewhere secure.
+
+  Go back to the Clerk Dashboard, where the modal should still be open, and paste these values into the respective fields. Then, select **Add connection**.
+</Steps>

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

@@ -0,0 +1,100 @@
+---
+title: Add Microsoft as an EASIE connection
+description: Learn how to allow users to sign up and sign in to your Clerk app with their Microsoft account using EASIE SSO.
+---
+
+<TutorialHero
+  beforeYouStart={[
+    {
+      title: "Add the Enhanced authentication add-on to your Pro plan",
+      link: "/pricing",
+      icon: "plus-circle",
+    },
+    {
+      title: "Enable email address as an identifier for your app.",
+      link: "/docs/authentication/configuration/sign-up-sign-in-options#identifiers",
+      icon: "key",
+    },
+     {
+      title: "A Microsoft Azure account is required.",
+      link: "https://azure.microsoft.com/en-us/free/",
+      icon: "user-circle",
+    }
+  ]}
+>
+  - Use Microsoft to authenticate users with EASIE SSO.
+</TutorialHero>
+
+Enabling EASIE SSO with Microsoft (formerly [Active Directory](https://learn.microsoft.com/en-us/entra/fundamentals/new-name)) allows your users to sign up and sign in to your Clerk application with their Microsoft account.
+
+## Configure for your development instance
+
+For _development instances_, Clerk uses preconfigured shared credentials and redirect URIs—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 the **Add connection** button, and select **For specific domains**.
+1. Under **EASIE**, select **Microsoft** as the identity provider.
+1. Add the **Specific Domain** that you want to allow this connection for. This is the domain of the users you want to allow to sign in to your app.
+1. Select **Add connection**.
+
+## Configure for your production instance
+
+> [!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.
+
+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 [Microsoft Azure portal](https://portal.azure.com).
+
+<Steps>
+  ### Enable Microsoft as an EASIE 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 specific domains**.
+  1. Under **EASIE**, select **Microsoft** as the identity provider.
+  1. Add the **Specific Domain** that you want to allow this connection for. This is the domain of the users you want to allow to sign in to your app.
+  1. Select **Add connection**.
+  1. Ensure that **Use custom credentials** is toggled on.
+  1. Save the **Redirect URI** somewhere secure.
+
+  ### Create a Microsoft Entra ID app
+
+  > [!TIP]
+  > If you already have a Microsoft Entra ID app you'd like to connect to Clerk, select your app from the [Microsoft Azure portal](https://portal.azure.com/#home) and skip to [the next step in this tutorial](#get-your-client-id-and-client-secret).
+
+  1. On the homepage of the [Microsoft Azure portal](https://portal.azure.com/#home), in the **Azure services** section, select **[Microsoft Entra ID](https://portal.azure.com/#view/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/~/Overview)**.
+  1. In the sidebar, open the **Manage** dropdown and select **[App registrations](https://portal.azure.com/#view/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/~/RegisteredApps)**.
+  1. Select **New Registration**. You'll be redirected to the **Register an application** page.
+  1. Complete the form as follows:
+     1. Under **Name**, enter your app name.
+     1. Under **Supported account types**, select **Accounts in any organizational directory (Any Microsoft Entra ID tenant – Multitenant) and personal Microsoft accounts (e.g. Skype, Xbox)**.
+     1. Under **Redirect URI (Optional)**, select **Web**.
+     1. Select **Register** to submit the form.
+
+  ### Get your client ID and client secret
+
+  Once your Microsoft Entra ID app is created, or once you select your app from the Microsoft Azure portal, you'll be redirected to its **Overview**.
+
+  1. From your app's overview, save the **Application (client) ID** somewhere secure. You'll need it to connect your Microsoft Entra ID app to your Clerk app.
+  1. Under **Client credentials**, select **Add a certificate or secret** to generate a Client Secret. You'll be redirected to the **Certificate & secrets** page.
+  1. Select **New client secret**. In the modal that opens, enter a description and set an expiration time for your secret.
+     > [!IMPORTANT]
+     > When your secret expires, your social connection will stop working until you generate a new client secret and add it to your Clerk app.
+  1. Save the new client secret's **Value** somewhere secure. You'll add this and your client ID to your Clerk app later. Keep this page open.
+
+  ### Set the Client ID and Client Secret in your Clerk Dashboard
+
+  Go back to the Clerk Dashboard, where the modal should still be open, and paste the **Client ID** and **Client Secret** values into the respective fields. Then, select **Add connection**.
+
+  ### Enable OpenID
+
+  To connect your Clerk app to your Microsoft app, set the **Redirect URI** in your Microsoft Azure portal.
+
+  1. Navigate back to the Microsoft Azure portal.
+  1. In the sidebar, open the **Manage** dropdown and select **Authentication**.
+  1. Select **Add a platform**.
+  1. Select **Web**.
+  1. In the **Redirect URIs** field and the **Front-channel logout URL** field, paste the **Redirect URI** you copied from the Clerk Dashboard.
+  1. Under **Implicit grant and hybrid flows**, check both **Access tokens** and **ID tokens**.
+  1. Select **Configure** to save the changes.
+</Steps>

docs/authentication/saml/jit-provisioning.mdx → docs/authentication/enterprise-connections/jit-provisioning.mdx

@@ -7,7 +7,7 @@ Just-in-Time (JIT) Provisioning, or automatic account provisioning, is a process
 
 Using JIT Provisioning means your IT department won't have to manually create user accounts for each of the services or apps your employees use to get work done.
 
-Clerk supports JIT account provisioning for all [supported SAML providers](/docs/authentication/saml/overview).
+Clerk supports JIT account provisioning for all [supported SAML providers](/docs/authentication/enterprise-connections/overview).
 
 Check your preferred SAML provider's documentation to enable JIT account provisioning on their side.