@auth0/auth0-spa-js 2.1.3 → 2.2.0

package/dist/typings/Auth0Client.d.ts

@@ -1,4 +1,5 @@
-import { Auth0ClientOptions, RedirectLoginOptions, PopupLoginOptions, PopupConfigOptions, RedirectLoginResult, GetTokenSilentlyOptions, GetTokenWithPopupOptions, LogoutOptions, User, IdToken, GetTokenSilentlyVerboseResponse } from './global';
+import { Auth0ClientOptions, RedirectLoginOptions, PopupLoginOptions, PopupConfigOptions, RedirectLoginResult, GetTokenSilentlyOptions, GetTokenWithPopupOptions, LogoutOptions, User, IdToken, GetTokenSilentlyVerboseResponse, TokenEndpointResponse } from './global';
+import { CustomTokenExchangeOptions } from './TokenExchange';
 /**
  * Auth0 SDK for Single Page Applications using [Authorization Code Grant Flow with PKCE](https://auth0.com/docs/api-auth/tutorials/authorization-code-grant-pkce).
  */
@@ -186,4 +187,43 @@ export declare class Auth0Client {
      */
     private _releaseLockOnPageHide;
     private _requestToken;
+    /**
+     * Exchanges an external subject token for an Auth0 token via a token exchange request.
+     *
+     * @param {CustomTokenExchangeOptions} options - The options required to perform the token exchange.
+     *
+     * @returns {Promise<TokenEndpointResponse>} A promise that resolves to the token endpoint response,
+     * which contains the issued Auth0 tokens.
+     *
+     * This method implements the token exchange grant as specified in RFC 8693 by first validating
+     * the provided subject token type and then constructing a token request to the /oauth/token endpoint.
+     * The request includes the following parameters:
+     *
+     * - `grant_type`: Hard-coded to "urn:ietf:params:oauth:grant-type:token-exchange".
+     * - `subject_token`: The external token provided via the options.
+     * - `subject_token_type`: The type of the external token (validated by this function).
+     * - `scope`: A unique set of scopes, generated by merging the scopes supplied in the options
+     *            with the SDK’s default scopes.
+     * - `audience`: The target audience, as determined by the SDK's authorization configuration.
+     *
+     * **Example Usage:**
+     *
+     * ```
+     * // Define the token exchange options
+     * const options: CustomTokenExchangeOptions = {
+     *   subject_token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6Ikp...',
+     *   subject_token_type: 'urn:acme:legacy-system-token',
+     *   scope: ['openid', 'profile']
+     * };
+     *
+     * // Exchange the external token for Auth0 tokens
+     * try {
+     *   const tokenResponse = await instance.exchangeToken(options);
+     *   console.log('Token response:', tokenResponse);
+     * } catch (error) {
+     *   console.error('Token exchange failed:', error);
+     * }
+     * ```
+     */
+    exchangeToken(options: CustomTokenExchangeOptions): Promise<TokenEndpointResponse>;
 }

package/dist/typings/TokenExchange.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Represents the configuration options required for initiating a Custom Token Exchange request
+ * following RFC 8693 specifications.
+ *
+ * @see {@link https://www.rfc-editor.org/rfc/rfc8693 | RFC 8693: OAuth 2.0 Token Exchange}
+ */
+export type CustomTokenExchangeOptions = {
+    /**
+     * The type identifier for the subject token being exchanged
+     *
+     * @pattern
+     * - Must be a namespaced URI under your organization's control
+     * - Forbidden patterns:
+     *   - `^urn:ietf:params:oauth:*` (IETF reserved)
+     *   - `^https:\/\/auth0\.com/*` (Auth0 reserved)
+     *   - `^urn:auth0:*` (Auth0 reserved)
+     *
+     * @example
+     * "urn:acme:legacy-system-token"
+     * "https://api.yourcompany.com/token-type/v1"
+     */
+    subject_token_type: string;
+    /**
+     * The opaque token value being exchanged for Auth0 tokens
+     *
+     * @security
+     * - Must be validated in Auth0 Actions using strong cryptographic verification
+     * - Implement replay attack protection
+     * - Recommended validation libraries: `jose`, `jsonwebtoken`
+     *
+     * @example
+     * "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
+     */
+    subject_token: string;
+    /**
+     * The target audience for the requested Auth0 token
+     *
+     * @remarks
+     * Must match exactly with an API identifier configured in your Auth0 tenant
+     *
+     * @example
+     * "https://api.your-service.com/v1"
+     */
+    audience: string;
+    /**
+     * Space-separated list of OAuth 2.0 scopes being requested
+     *
+     * @remarks
+     * Subject to API authorization policies configured in Auth0
+     *
+     * @example
+     * "openid profile email read:data write:data"
+     */
+    scope?: string;
+    /**
+     * Additional custom parameters for Auth0 Action processing
+     *
+     * @remarks
+     * Accessible in Action code via `event.request.body`
+     *
+     * @example
+     * ```typescript
+     * {
+     *   custom_parameter: "session_context",
+     *   device_fingerprint: "a3d8f7...",
+     * }
+     * ```
+     */
+    [key: string]: unknown;
+};

package/dist/typings/scope.d.ts

@@ -1,4 +1,10 @@
 /**
  * @ignore
  */
+/**
+ * Returns a string of unique scopes by removing duplicates and unnecessary whitespace.
+ *
+ * @param {...(string | undefined)[]} scopes - A list of scope strings or undefined values.
+ * @returns {string} A string containing unique scopes separated by a single space.
+ */
 export declare const getUniqueScopes: (...scopes: (string | undefined)[]) => string;

package/dist/typings/version.d.ts

@@ -1,2 +1,2 @@
-declare const _default: "2.1.3";
+declare const _default: "2.2.0";
 export default _default;

package/package.json

@@ -3,7 +3,7 @@
   "name": "@auth0/auth0-spa-js",
   "description": "Auth0 SDK for Single Page Applications using Authorization Code Grant Flow with PKCE",
   "license": "MIT",
-  "version": "2.1.3",
+  "version": "2.2.0",
   "main": "dist/lib/auth0-spa-js.cjs.js",
   "types": "dist/typings/index.d.ts",
   "module": "dist/auth0-spa-js.production.esm.js",
@@ -39,7 +39,7 @@
     "@typescript-eslint/eslint-plugin-tslint": "^5.33.1",
     "@typescript-eslint/parser": "^5.33.1",
     "browser-tabs-lock": "^1.2.15",
-    "browserstack-cypress-cli": "1.27.0",
+    "browserstack-cypress-cli": "1.28.0",
     "cli-table": "^0.3.6",
     "concurrently": "^7.3.0",
     "cypress": "13.6.1",

package/src/Auth0Client.ts

@@ -92,6 +92,7 @@ import {
   OLD_IS_AUTHENTICATED_COOKIE_NAME,
   patchOpenUrlWithOnRedirect
 } from './Auth0Client.utils';
+import { CustomTokenExchangeOptions } from './TokenExchange';
 
 /**
  * @ignore
@@ -1097,7 +1098,10 @@ export class Auth0Client {
   };
 
   private async _requestToken(
-    options: PKCERequestTokenOptions | RefreshTokenRequestTokenOptions,
+    options:
+      | PKCERequestTokenOptions
+      | RefreshTokenRequestTokenOptions
+      | TokenExchangeRequestOptions,
     additionalParameters?: RequestTokenAdditionalParameters
   ) {
     const { nonceIn, organization } = additionalParameters || {};
@@ -1137,6 +1141,68 @@ export class Auth0Client {
 
     return { ...authResult, decodedToken };
   }
+
+  /*
+  Custom Token Exchange
+  * **Implementation Notes:**
+  * - Ensure that the `subject_token` provided has been securely obtained and is valid according
+  *   to your external identity provider's policies before invoking this function.
+  * - The function leverages internal helper methods:
+  *   - `validateTokenType` confirms that the `subject_token_type` is supported.
+  *   - `getUniqueScopes` merges and de-duplicates scopes between the provided options and
+  *     the instance's default scopes.
+  *   - `_requestToken` performs the actual HTTP request to the token endpoint.
+  */
+
+  /**
+   * Exchanges an external subject token for an Auth0 token via a token exchange request.
+   *
+   * @param {CustomTokenExchangeOptions} options - The options required to perform the token exchange.
+   *
+   * @returns {Promise<TokenEndpointResponse>} A promise that resolves to the token endpoint response,
+   * which contains the issued Auth0 tokens.
+   *
+   * This method implements the token exchange grant as specified in RFC 8693 by first validating
+   * the provided subject token type and then constructing a token request to the /oauth/token endpoint.
+   * The request includes the following parameters:
+   *
+   * - `grant_type`: Hard-coded to "urn:ietf:params:oauth:grant-type:token-exchange".
+   * - `subject_token`: The external token provided via the options.
+   * - `subject_token_type`: The type of the external token (validated by this function).
+   * - `scope`: A unique set of scopes, generated by merging the scopes supplied in the options
+   *            with the SDK’s default scopes.
+   * - `audience`: The target audience, as determined by the SDK's authorization configuration.
+   *
+   * **Example Usage:**
+   *
+   * ```
+   * // Define the token exchange options
+   * const options: CustomTokenExchangeOptions = {
+   *   subject_token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6Ikp...',
+   *   subject_token_type: 'urn:acme:legacy-system-token',
+   *   scope: ['openid', 'profile']
+   * };
+   *
+   * // Exchange the external token for Auth0 tokens
+   * try {
+   *   const tokenResponse = await instance.exchangeToken(options);
+   *   console.log('Token response:', tokenResponse);
+   * } catch (error) {
+   *   console.error('Token exchange failed:', error);
+   * }
+   * ```
+   */
+  async exchangeToken(
+    options: CustomTokenExchangeOptions
+  ): Promise<TokenEndpointResponse> {
+    return this._requestToken({
+      grant_type: 'urn:ietf:params:oauth:grant-type:token-exchange',
+      subject_token: options.subject_token,
+      subject_token_type: options.subject_token_type,
+      scope: getUniqueScopes(options.scope, this.scope),
+      audience: this.options.authorizationParams.audience
+    });
+  }
 }
 
 interface BaseRequestTokenOptions {
@@ -1157,6 +1223,14 @@ interface RefreshTokenRequestTokenOptions extends BaseRequestTokenOptions {
   refresh_token?: string;
 }
 
+interface TokenExchangeRequestOptions extends BaseRequestTokenOptions {
+  grant_type: 'urn:ietf:params:oauth:grant-type:token-exchange';
+  subject_token: string;
+  subject_token_type: string;
+  actor_token?: string;
+  actor_token_type?: string;
+}
+
 interface RequestTokenAdditionalParameters {
   nonceIn?: string;
   organization?: string;

package/src/TokenExchange.ts

@@ -0,0 +1,74 @@
+/**
+ * Represents the configuration options required for initiating a Custom Token Exchange request
+ * following RFC 8693 specifications.
+ *
+ * @see {@link https://www.rfc-editor.org/rfc/rfc8693 | RFC 8693: OAuth 2.0 Token Exchange}
+ */
+export type CustomTokenExchangeOptions = {
+  /**
+   * The type identifier for the subject token being exchanged
+   *
+   * @pattern
+   * - Must be a namespaced URI under your organization's control
+   * - Forbidden patterns:
+   *   - `^urn:ietf:params:oauth:*` (IETF reserved)
+   *   - `^https:\/\/auth0\.com/*` (Auth0 reserved)
+   *   - `^urn:auth0:*` (Auth0 reserved)
+   *
+   * @example
+   * "urn:acme:legacy-system-token"
+   * "https://api.yourcompany.com/token-type/v1"
+   */
+  subject_token_type: string;
+
+  /**
+   * The opaque token value being exchanged for Auth0 tokens
+   *
+   * @security
+   * - Must be validated in Auth0 Actions using strong cryptographic verification
+   * - Implement replay attack protection
+   * - Recommended validation libraries: `jose`, `jsonwebtoken`
+   *
+   * @example
+   * "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
+   */
+  subject_token: string;
+
+  /**
+   * The target audience for the requested Auth0 token
+   *
+   * @remarks
+   * Must match exactly with an API identifier configured in your Auth0 tenant
+   *
+   * @example
+   * "https://api.your-service.com/v1"
+   */
+  audience: string;
+
+  /**
+   * Space-separated list of OAuth 2.0 scopes being requested
+   *
+   * @remarks
+   * Subject to API authorization policies configured in Auth0
+   *
+   * @example
+   * "openid profile email read:data write:data"
+   */
+  scope?: string;
+
+  /**
+   * Additional custom parameters for Auth0 Action processing
+   *
+   * @remarks
+   * Accessible in Action code via `event.request.body`
+   *
+   * @example
+   * ```typescript
+   * {
+   *   custom_parameter: "session_context",
+   *   device_fingerprint: "a3d8f7...",
+   * }
+   * ```
+   */
+  [key: string]: unknown;
+};

package/src/scope.ts

@@ -6,6 +6,12 @@ const dedupe = (arr: string[]) => Array.from(new Set(arr));
 /**
  * @ignore
  */
+/**
+ * Returns a string of unique scopes by removing duplicates and unnecessary whitespace.
+ *
+ * @param {...(string | undefined)[]} scopes - A list of scope strings or undefined values.
+ * @returns {string} A string containing unique scopes separated by a single space.
+ */
 export const getUniqueScopes = (...scopes: (string | undefined)[]) => {
   return dedupe(scopes.filter(Boolean).join(' ').trim().split(/\s+/)).join(' ');
 };

package/src/version.ts

@@ -1 +1 @@
-export default '2.1.3';
+export default '2.2.0';