feat(clerk-js,backend,types): Add enterprise_sso for session reverification

.changeset/plenty-shirts-tease.md

@@ -0,0 +1,5 @@
+---
+'@clerk/backend': patch
+---
+
+Add `last_authenticated_at` to `SAMLAccount` resource, which represents the date when the SAML account was last authenticated

.changeset/thick-jokes-talk.md

@@ -0,0 +1,7 @@
+---
+'@clerk/clerk-js': patch
+'@clerk/types': patch
+---
+
+- Add experimental property `last_authenticated_at` to `SamlAccount` resource, which represents the date when the SAML account was last authenticated
+- Add experimental support for `enterprise_sso` as a `strategy` param for `session.prepareFirstFactorVerification`

packages/backend/src/api/resources/JSON.ts

@@ -246,6 +246,7 @@ export interface SamlAccountJSON extends ClerkResourceJSON {
   last_name: string;
   verification: VerificationJSON | null;
   saml_connection: SamlAccountConnectionJSON | null;
+  last_authenticated_at: number | null;
 }
 
 export interface IdentificationLinkJSON extends ClerkResourceJSON {

packages/backend/src/api/resources/SamlAccount.ts

@@ -43,6 +43,10 @@ export class SamlAccount {
      * The SAML connection of the SAML account.
      */
     readonly samlConnection: SamlAccountConnection | null,
+    /**
+     * The date when the SAML account was last authenticated.
+     */
+    readonly lastAuthenticatedAt: number | null,
   ) {}
 
   static fromJSON(data: SamlAccountJSON): SamlAccount {
@@ -56,6 +60,7 @@ export class SamlAccount {
       data.last_name,
       data.verification && Verification.fromJSON(data.verification),
       data.saml_connection && SamlAccountConnection.fromJSON(data.saml_connection),
+      data.last_authenticated_at ?? null,
     );
   }
 }

packages/clerk-js/src/core/resources/EnterpriseAccount.ts

@@ -24,6 +24,7 @@ export class EnterpriseAccount extends BaseResource implements EnterpriseAccount
   publicMetadata = {};
   verification: VerificationResource | null = null;
   enterpriseConnection: EnterpriseAccountConnectionResource | null = null;
+  lastAuthenticatedAt: Date | null = null;
 
   public constructor(data: Partial<EnterpriseAccountJSON | EnterpriseAccountJSONSnapshot>, pathRoot: string);
   public constructor(data: EnterpriseAccountJSON | EnterpriseAccountJSONSnapshot, pathRoot: string) {
@@ -46,7 +47,7 @@ export class EnterpriseAccount extends BaseResource implements EnterpriseAccount
     this.firstName = data.first_name;
     this.lastName = data.last_name;
     this.publicMetadata = data.public_metadata;
-
+    this.lastAuthenticatedAt = data.last_authenticated_at ? unixEpochToDate(data.last_authenticated_at) : null;
     if (data.verification) {
       this.verification = new Verification(data.verification);
     }
@@ -72,6 +73,7 @@ export class EnterpriseAccount extends BaseResource implements EnterpriseAccount
       public_metadata: this.publicMetadata,
       verification: this.verification?.__internal_toSnapshot() || null,
       enterprise_connection: this.enterpriseConnection?.__internal_toSnapshot() || null,
+      last_authenticated_at: this.lastAuthenticatedAt ? this.lastAuthenticatedAt.getTime() : null,
     };
   }
 }

packages/clerk-js/src/core/resources/SamlAccount.ts

@@ -23,6 +23,7 @@ export class SamlAccount extends BaseResource implements SamlAccountResource {
   lastName = '';
   verification: VerificationResource | null = null;
   samlConnection: SamlAccountConnectionResource | null = null;
+  lastAuthenticatedAt: Date | null = null;
 
   public constructor(data: Partial<SamlAccountJSON | SamlAccountJSONSnapshot>, pathRoot: string);
   public constructor(data: SamlAccountJSON | SamlAccountJSONSnapshot, pathRoot: string) {
@@ -52,6 +53,8 @@ export class SamlAccount extends BaseResource implements SamlAccountResource {
       this.samlConnection = new SamlAccountConnection(data.saml_connection);
     }
 
+    this.lastAuthenticatedAt = data.last_authenticated_at ? unixEpochToDate(data.last_authenticated_at) : null;
+
     return this;
   }
 
@@ -67,6 +70,7 @@ export class SamlAccount extends BaseResource implements SamlAccountResource {
       last_name: this.lastName,
       verification: this.verification?.__internal_toSnapshot() || null,
       saml_connection: this.samlConnection?.__internal_toSnapshot(),
+      last_authenticated_at: this.lastAuthenticatedAt ? this.lastAuthenticatedAt.getTime() : null,
     };
   }
 }

packages/clerk-js/src/core/resources/Session.ts

@@ -6,6 +6,7 @@ import type {
   ActClaim,
   CheckAuthorization,
   EmailCodeConfig,
+  EnterpriseSSOConfig,
   GetToken,
   GetTokenOptions,
   PhoneCodeConfig,
@@ -179,6 +180,13 @@ export class Session extends BaseResource implements SessionResource {
       case 'passkey':
         config = {};
         break;
+      case 'enterprise_sso':
+        config = {
+          emailAddressId: factor.emailAddressId,
+          enterpriseConnectionId: factor.enterpriseConnectionId,
+          redirectUrl: factor.redirectUrl,
+        } as EnterpriseSSOConfig;
+        break;
       default:
         clerkInvalidStrategy('Session.prepareFirstFactorVerification', (factor as any).strategy);
     }

packages/clerk-js/src/ui/components/UserVerification/AlternativeMethods.tsx

@@ -10,7 +10,7 @@ import { formatSafeIdentifier } from '@/ui/utils/formatSafeIdentifier';
 import type { LocalizationKey } from '../../customizables';
 import { Col, descriptors, Flex, Flow, localizationKeys } from '../../customizables';
 import { useCardState } from '../../elements/contexts';
-import { ChatAltIcon, Email, Fingerprint, LockClosedIcon } from '../../icons';
+import { ChatAltIcon, Email, Fingerprint, LockClosedIcon, Organization } from '../../icons';
 import { useReverificationAlternativeStrategies } from './useReverificationAlternativeStrategies';
 import { useUserVerificationSession } from './useUserVerificationSession';
 import { withHavingTrouble } from './withHavingTrouble';
@@ -128,6 +128,7 @@ export function getButtonIcon(factor: SessionVerificationFirstFactor) {
     phone_code: ChatAltIcon,
     password: LockClosedIcon,
     passkey: Fingerprint,
+    enterprise_sso: Organization,
   } as const;
 
   return icons[factor.strategy];

packages/types/src/factors.ts

@@ -124,6 +124,10 @@ export type EnterpriseSSOConfig = EnterpriseSSOFactor & {
   redirectUrl: string;
   actionCompleteRedirectUrl: string;
   oidcPrompt?: string;
+  /**
+   * @experimental
+   */
+  emailAddressId?: string;
   /**
    * @experimental
    */

packages/types/src/json.ts

@@ -252,6 +252,7 @@ export interface EnterpriseAccountJSON extends ClerkResourceJSON {
   provider_user_id: string | null;
   public_metadata: Record<string, unknown>;
   verification: VerificationJSON | null;
+  last_authenticated_at: number | null;
 }
 
 export interface EnterpriseAccountConnectionJSON extends ClerkResourceJSON {
@@ -279,6 +280,7 @@ export interface SamlAccountJSON extends ClerkResourceJSON {
   last_name: string;
   verification?: VerificationJSON;
   saml_connection?: SamlAccountConnectionJSON;
+  last_authenticated_at: number | null;
 }
 
 export interface UserJSON extends ClerkResourceJSON {

packages/types/src/session.ts

@@ -2,6 +2,7 @@ import type {
   BackupCodeAttempt,
   EmailCodeAttempt,
   EmailCodeConfig,
+  EnterpriseSSOConfig,
   PasskeyAttempt,
   PassKeyConfig,
   PasswordAttempt,
@@ -351,7 +352,14 @@ export type SessionVerifyCreateParams = {
   level: SessionVerificationLevel;
 };
 
-export type SessionVerifyPrepareFirstFactorParams = EmailCodeConfig | PhoneCodeConfig | PassKeyConfig;
+export type SessionVerifyPrepareFirstFactorParams =
+  | EmailCodeConfig
+  | PhoneCodeConfig
+  | PassKeyConfig
+  /**
+   * @experimental
+   */
+  | Omit<EnterpriseSSOConfig, 'actionCompleteRedirectUrl'>;
 export type SessionVerifyAttemptFirstFactorParams =
   | EmailCodeAttempt
   | PhoneCodeAttempt

packages/types/src/sessionVerification.ts

@@ -1,6 +1,7 @@
 import type {
   BackupCodeFactor,
   EmailCodeFactor,
+  EnterpriseSSOFactor,
   PasskeyFactor,
   PasswordFactor,
   PhoneCodeFactor,
@@ -49,5 +50,13 @@ export type ReverificationConfig =
 export type SessionVerificationLevel = 'first_factor' | 'second_factor' | 'multi_factor';
 export type SessionVerificationAfterMinutes = number;
 
-export type SessionVerificationFirstFactor = EmailCodeFactor | PhoneCodeFactor | PasswordFactor | PasskeyFactor;
+export type SessionVerificationFirstFactor =
+  | EmailCodeFactor
+  | PhoneCodeFactor
+  | PasswordFactor
+  | PasskeyFactor
+  /**
+   * @experimental
+   */
+  | EnterpriseSSOFactor;
 export type SessionVerificationSecondFactor = PhoneCodeFactor | TOTPFactor | BackupCodeFactor;