feat: Unauthorized sign-in (#1668)

Co-authored-by: victoria <[email protected]>
Co-authored-by: Alexis Aguilar <[email protected]>

docs/customization/account-portal/getting-started.mdx

@@ -20,6 +20,7 @@ For development environments, Clerk will issue you a randomly generated domain o
 https://accounts.<your-domain>.com/sign-in
 https://accounts.<your-domain>.com/sign-up
 https://accounts.<your-domain>.com/user
+https://accounts.<your-domain>.com/unauthorized-sign-in
 https://accounts.<your-domain>.com/organization
 https://accounts.<your-domain>.com/create-organization
 ```

docs/customization/account-portal/overview.mdx

@@ -52,6 +52,14 @@ The user profile page hosts the prebuilt [`<UserProfile />`](/docs/components/us
 
 Redirect your authenticated users to their user profile page using the [`<RedirectToUserProfile />`](/docs/components/control/redirect-to-userprofile) control component.
 
+### Unauthorized sign-in
+
+The unauthorized sign-in page doesn't host any prebuilt Clerk component. It displays a UI confirming that a session from an unrecognized device was successfully revoked. For more information, see the [Unauthorized sign-in](/docs/security/unauthorized-sign-in) feature.
+
+The unauthorized sign-in page displays a UI confirming that a session from an unrecognized device was successfully revoked. For more information, refer to [the reference.](/docs/security/unauthorized-sign-in)
+
+![Clerk's Account Portal unauthorized sign-in page](/docs/images/account-portal/unauthorized-sign-in.png)
+
 ### Create organization
 
 The create organization page hosts the prebuilt [`<CreateOrganization />`](/docs/components/organization/create-organization) component, which provides a streamlined interface for users to create new organizations within your application.

docs/manifest.json

@@ -1616,6 +1616,10 @@
                         {
                           "title": "Protect email link sign-ins and sign-ups",
                           "href": "/docs/security/email-link-protection"
+                        },
+                        {
+                          "title": "Unauthorized sign-in",
+                          "href": "/docs/security/unauthorized-sign-in"
                         }
                       ]
                     ]

docs/security/unauthorized-sign-in.mdx

@@ -0,0 +1,41 @@
+---
+title: Unauthorized sign-in
+description: Notify users of unauthorized sign-ins to their accounts
+---
+
+Clerk detects sign-in attempts from unrecognized devices to protect users from unauthorized access to their accounts. This security feature helps identify potentially malicious sign-in activity.
+
+## Email notification for unauthorized access
+
+When a sign-in attempt is made from an unfamiliar device, Clerk notifies the account owner by email with details about the newly created session. The email notification varies depending on the instance's configuration and the application's billing plan.
+
+By default, the email includes information about the unauthorized sign-in attempt, such as device type, operating system, IP address, location, and the sign-in method used. If you've set a support email for your app, Clerk will add instructions for the user to contact the app administrator.
+
+For supported instances, the email might also include a button that allows users to sign out from the unrecognized device. Selecting this button immediately revokes the session.
+
+To customize the unauthorized sign-in email notification:
+
+1. In the Clerk Dashboard, navigate to the [**Emails**](https://dashboard.clerk.com/last-active?path=customization/email) page.
+1. Select **Sign in from new device**. You'll be redirected to the template settings page.
+1. Edit the email template.
+1. Select **Apply changes**.
+
+## Revoke sessions for unauthorized sign-ins
+
+> [!WARNING]
+> This feature isn't available in production for free plans but can be tested for free in development mode. For more information, see the [pricing](/pricing){{ target: '_blank' }} page.
+
+For apps that support this feature, users can immediately revoke unauthorized sign-ins directly from the email notification. With a single click, the suspicious session is revoked and the user is redirected to a confirmation page.
+
+The confirmation page depends on the instance configuration:
+
+- [Account Portal](/docs/customization/account-portal/overview) enabled: The user is redirected to the [unauthorized sign-in](/docs/customization/account-portal/overview#unauthorized-sign-in) page, where content can be customized based on the app's theme.
+- Account Portal disabled: The user sees a plain text confirmation of the successful session revocation.
+
+In either case, after revoking the session, users must sign in again unless they have an active session on their device.
+
+To customize the URL path of the unauthorized sign-in page:
+
+1. In the Clerk Dashboard, navigate to the [**Paths**](https://dashboard.clerk.com/last-active?path=paths) page.
+1. Under **Application paths**, enter the **Unauthorized sign in URL** path.
+1. Select **Save**.