@auth0/auth0-server-js 1.8.0 → 1.9.0

package/dist/index.d.cts

@@ -26,6 +26,12 @@ interface ServerClientOptions<TStoreOptions = unknown> {
     clientAssertionSigningKey?: string | CryptoKey;
     clientAssertionSigningAlg?: string;
     authorizationParams?: AuthorizationParameters;
+    /**
+     * Default organization for all interactive login flows from this client.
+     * Can be an organization ID (e.g. `org_abc123`) or an organization name (e.g. `acme-corp`).
+     * A per-login value in {@link StartInteractiveLoginOptions} overrides this.
+     */
+    organization?: string;
     discoveryCache?: DiscoveryCacheOptions;
     transactionIdentifier?: string;
     stateIdentifier?: string;
@@ -57,12 +63,19 @@ interface UserClaims {
     email?: string;
     email_verified?: boolean;
     org_id?: string;
+    org_name?: string;
     [key: string]: unknown;
 }
 interface AuthorizationParameters {
     scope?: string;
     audience?: string;
     redirect_uri?: string;
+    /**
+     * The organization to log the user into. Prefer the first-class `organization`
+     * option on {@link StartInteractiveLoginOptions} / {@link ServerClientOptions};
+     * this is supported for backwards compatibility.
+     */
+    organization?: string;
     [key: string]: unknown;
 }
 interface TokenSet {
@@ -112,6 +125,11 @@ interface TransactionData {
      */
     codeVerifier?: string;
     domain?: string;
+    /**
+     * The organization requested at login, carried across the redirect so the
+     * returned ID token's organization claim can be validated at callback.
+     */
+    organization?: string;
     [key: string]: unknown;
 }
 interface AbstractDataStore<TData, TStoreOptions = unknown> {
@@ -146,6 +164,18 @@ interface StartInteractiveLoginOptions<TAppState = unknown> {
     pushedAuthorizationRequests?: boolean;
     appState?: TAppState;
     authorizationParams?: AuthorizationParameters;
+    /**
+     * The organization to log the user into. Overrides the client-level
+     * `organization` default. Can be an organization ID (`org_abc123`) or name
+     * (`acme-corp`). Also passable via `authorizationParams.organization`.
+     */
+    organization?: string;
+    /**
+     * The organization invitation ticket, when handling an invitation-acceptance flow.
+     * Requires `organization` to be set (per-login, client-level default, or via
+     * `authorizationParams`); providing `invitation` without an organization throws.
+     */
+    invitation?: string;
 }
 interface LoginBackchannelOptions {
     bindingMessage: string;
@@ -612,9 +642,16 @@ declare class ServerClient<TStoreOptions = unknown> {
     constructor(options: ServerClientOptions<TStoreOptions>);
     /**
      * Starts the interactive login process, and returns a URL to redirect the user-agent to to request authorization at Auth0.
+     *
+     * When `organization` is provided (per-login option, client-level default, or via
+     * `authorizationParams.organization`), it is forwarded to `/authorize` and remembered so the
+     * returned ID token's organization claim can be validated in `completeInteractiveLogin`.
+     *
      * @param options Optional options used to configure the interactive login process.
      * @param storeOptions Optional options used to pass to the Transaction and State Store.
      *
+     * @throws {OrganizationValidationError} If the resolved `organization` is blank.
+     * @throws {InvalidConfigurationError} If `invitation` is provided without an `organization`.
      * @throws {BuildAuthorizationUrlError} If there was an issue when building the Authorization URL.
      *
      * @returns A promise resolving to a URL object, representing the URL to redirect the user-agent to to request authorization at Auth0.
@@ -628,6 +665,7 @@ declare class ServerClient<TStoreOptions = unknown> {
      *
      * @throws {MissingTransactionError} When no transaction was found.
      * @throws {TokenByCodeError} If there was an issue requesting the access token.
+     * @throws {OrganizationValidationError} When an organization was requested at login and the returned ID token's organization claim is missing or does not match; nothing is persisted.
      * @throws {SessionExpiredError} When the ID token's `session_expiry` is already in the past at login (the session is born expired); nothing is persisted.
      *
      * @returns A promise resolving to an object, containing the original appState (if present) and the authorizationDetails (when RAR was used).

package/dist/index.d.ts

@@ -26,6 +26,12 @@ interface ServerClientOptions<TStoreOptions = unknown> {
     clientAssertionSigningKey?: string | CryptoKey;
     clientAssertionSigningAlg?: string;
     authorizationParams?: AuthorizationParameters;
+    /**
+     * Default organization for all interactive login flows from this client.
+     * Can be an organization ID (e.g. `org_abc123`) or an organization name (e.g. `acme-corp`).
+     * A per-login value in {@link StartInteractiveLoginOptions} overrides this.
+     */
+    organization?: string;
     discoveryCache?: DiscoveryCacheOptions;
     transactionIdentifier?: string;
     stateIdentifier?: string;
@@ -57,12 +63,19 @@ interface UserClaims {
     email?: string;
     email_verified?: boolean;
     org_id?: string;
+    org_name?: string;
     [key: string]: unknown;
 }
 interface AuthorizationParameters {
     scope?: string;
     audience?: string;
     redirect_uri?: string;
+    /**
+     * The organization to log the user into. Prefer the first-class `organization`
+     * option on {@link StartInteractiveLoginOptions} / {@link ServerClientOptions};
+     * this is supported for backwards compatibility.
+     */
+    organization?: string;
     [key: string]: unknown;
 }
 interface TokenSet {
@@ -112,6 +125,11 @@ interface TransactionData {
      */
     codeVerifier?: string;
     domain?: string;
+    /**
+     * The organization requested at login, carried across the redirect so the
+     * returned ID token's organization claim can be validated at callback.
+     */
+    organization?: string;
     [key: string]: unknown;
 }
 interface AbstractDataStore<TData, TStoreOptions = unknown> {
@@ -146,6 +164,18 @@ interface StartInteractiveLoginOptions<TAppState = unknown> {
     pushedAuthorizationRequests?: boolean;
     appState?: TAppState;
     authorizationParams?: AuthorizationParameters;
+    /**
+     * The organization to log the user into. Overrides the client-level
+     * `organization` default. Can be an organization ID (`org_abc123`) or name
+     * (`acme-corp`). Also passable via `authorizationParams.organization`.
+     */
+    organization?: string;
+    /**
+     * The organization invitation ticket, when handling an invitation-acceptance flow.
+     * Requires `organization` to be set (per-login, client-level default, or via
+     * `authorizationParams`); providing `invitation` without an organization throws.
+     */
+    invitation?: string;
 }
 interface LoginBackchannelOptions {
     bindingMessage: string;
@@ -612,9 +642,16 @@ declare class ServerClient<TStoreOptions = unknown> {
     constructor(options: ServerClientOptions<TStoreOptions>);
     /**
      * Starts the interactive login process, and returns a URL to redirect the user-agent to to request authorization at Auth0.
+     *
+     * When `organization` is provided (per-login option, client-level default, or via
+     * `authorizationParams.organization`), it is forwarded to `/authorize` and remembered so the
+     * returned ID token's organization claim can be validated in `completeInteractiveLogin`.
+     *
      * @param options Optional options used to configure the interactive login process.
      * @param storeOptions Optional options used to pass to the Transaction and State Store.
      *
+     * @throws {OrganizationValidationError} If the resolved `organization` is blank.
+     * @throws {InvalidConfigurationError} If `invitation` is provided without an `organization`.
      * @throws {BuildAuthorizationUrlError} If there was an issue when building the Authorization URL.
      *
      * @returns A promise resolving to a URL object, representing the URL to redirect the user-agent to to request authorization at Auth0.
@@ -628,6 +665,7 @@ declare class ServerClient<TStoreOptions = unknown> {
      *
      * @throws {MissingTransactionError} When no transaction was found.
      * @throws {TokenByCodeError} If there was an issue requesting the access token.
+     * @throws {OrganizationValidationError} When an organization was requested at login and the returned ID token's organization claim is missing or does not match; nothing is persisted.
      * @throws {SessionExpiredError} When the ID token's `session_expiry` is already in the past at login (the session is born expired); nothing is persisted.
      *
      * @returns A promise resolving to an object, containing the original appState (if present) and the authorizationDetails (when RAR was used).

package/dist/index.js

@@ -163,6 +163,7 @@ function updateStateDataForConnectionTokenSet(options, stateData, tokenEndpointR
 import {
   TokenForConnectionError,
   AuthClient,
+  OrganizationValidationError,
   PasswordlessStartError,
   PasswordlessVerifyError,
   TokenByRefreshTokenError
@@ -204,7 +205,7 @@ function getTelemetryConfig(config) {
   return {
     enabled: true,
     name: config?.name ?? "@auth0/auth0-server-js",
-    version: config?.version ?? "1.8.0"
+    version: config?.version ?? "1.9.0"
   };
 }
 
@@ -555,9 +556,16 @@ var ServerClient = class {
   }
   /**
    * Starts the interactive login process, and returns a URL to redirect the user-agent to to request authorization at Auth0.
+   *
+   * When `organization` is provided (per-login option, client-level default, or via
+   * `authorizationParams.organization`), it is forwarded to `/authorize` and remembered so the
+   * returned ID token's organization claim can be validated in `completeInteractiveLogin`.
+   *
    * @param options Optional options used to configure the interactive login process.
    * @param storeOptions Optional options used to pass to the Transaction and State Store.
    *
+   * @throws {OrganizationValidationError} If the resolved `organization` is blank.
+   * @throws {InvalidConfigurationError} If `invitation` is provided without an `organization`.
    * @throws {BuildAuthorizationUrlError} If there was an issue when building the Authorization URL.
    *
    * @returns A promise resolving to a URL object, representing the URL to redirect the user-agent to to request authorization at Auth0.
@@ -568,6 +576,16 @@ var ServerClient = class {
       throw new MissingRequiredArgumentError("authorizationParams.redirect_uri");
     }
     const scope = ensureOpenIdScope(options?.authorizationParams?.scope ?? this.#options.authorizationParams?.scope);
+    const perLoginAuthParamsOrganization = typeof options?.authorizationParams?.organization === "string" ? options.authorizationParams.organization : void 0;
+    const clientAuthParamsOrganization = typeof this.#options.authorizationParams?.organization === "string" ? this.#options.authorizationParams.organization : void 0;
+    const resolvedOrganization = options?.organization ?? perLoginAuthParamsOrganization ?? this.#options.organization ?? clientAuthParamsOrganization;
+    if (resolvedOrganization !== void 0 && !resolvedOrganization.trim()) {
+      throw new OrganizationValidationError("organization must not be blank");
+    }
+    const hasInvitation = !!(options?.invitation || options?.authorizationParams?.invitation);
+    if (hasInvitation && !resolvedOrganization) {
+      throw new InvalidConfigurationError("organization is required when invitation is provided.");
+    }
     const domain = await this.#resolveDomain(storeOptions);
     const authClient = this.#getAuthClient(domain);
     const { codeVerifier, authorizationUrl } = await authClient.buildAuthorizationUrl({
@@ -575,7 +593,9 @@ var ServerClient = class {
       authorizationParams: {
         ...options?.authorizationParams,
         redirect_uri: redirectUri,
-        scope
+        scope,
+        ...resolvedOrganization ? { organization: resolvedOrganization } : {},
+        ...options?.invitation ? { invitation: options.invitation } : {}
       }
     });
     const transactionState = {
@@ -583,6 +603,9 @@ var ServerClient = class {
       codeVerifier,
       domain
     };
+    if (resolvedOrganization) {
+      transactionState.organization = resolvedOrganization;
+    }
     if (options?.appState) {
       transactionState.appState = options.appState;
     }
@@ -597,6 +620,7 @@ var ServerClient = class {
    *
    * @throws {MissingTransactionError} When no transaction was found.
    * @throws {TokenByCodeError} If there was an issue requesting the access token.
+   * @throws {OrganizationValidationError} When an organization was requested at login and the returned ID token's organization claim is missing or does not match; nothing is persisted.
    * @throws {SessionExpiredError} When the ID token's `session_expiry` is already in the past at login (the session is born expired); nothing is persisted.
    *
    * @returns A promise resolving to an object, containing the original appState (if present) and the authorizationDetails (when RAR was used).
@@ -610,7 +634,8 @@ var ServerClient = class {
     const authClient = this.#getAuthClient(domain);
     const tokenEndpointResponse = await authClient.getTokenByCode(url, {
       // TransactionData.codeVerifier is optional only to accommodate magic-link transactions.
-      codeVerifier: transactionData.codeVerifier
+      codeVerifier: transactionData.codeVerifier,
+      organization: transactionData.organization
     });
     await this.#transactionStore.delete(this.#transactionStoreIdentifier, storeOptions);
     const existingStateData = await this.#stateStore.get(this.#stateStoreIdentifier, storeOptions);
@@ -1381,7 +1406,7 @@ var AbstractTransactionStore = class extends AbstractStore {
 };
 
 // src/index.ts
-import { TokenExchangeError, MissingClientAuthError } from "@auth0/auth0-auth-js";
+import { TokenExchangeError, MissingClientAuthError, OrganizationValidationError as OrganizationValidationError3 } from "@auth0/auth0-auth-js";
 
 // src/store/cookie-transaction-store.ts
 var CookieTransactionStore = class extends AbstractTransactionStore {
@@ -1591,7 +1616,7 @@ import {
   PasskeyRegisterError,
   PasskeyChallengeError,
   PasskeyGetTokenError,
-  OrganizationValidationError
+  OrganizationValidationError as OrganizationValidationError2
 } from "@auth0/auth0-auth-js";
 export {
   AbstractStateStore,
@@ -1608,7 +1633,7 @@ export {
   MissingRequiredArgumentError,
   MissingSessionError,
   MissingTransactionError,
-  OrganizationValidationError,
+  OrganizationValidationError3 as OrganizationValidationError,
   PasskeyChallengeError,
   PasskeyGetTokenError,
   PasskeyRegisterError,