Fix: Token Exchange Ignoring Scope and Audience Parameters (#1365)

## Overview This PR fixes a bug in the `exchangeToken()` method where `scope` and `audience` parameters were completely ignored in HTTP requests to the `/oauth/token` endpoint. Impact: Token exchange requests would fail with authorization errors because the Auth0 backend received requests without the required `audience` and `scope` parameters. ## Root Cause The bug was in `src/api.ts` where `audience` and `scope` were removed from the options object even in the case of TokenExchange (where it's needed): ```typescript export async function oauthToken({ baseUrl, timeout, audience, scope, auth0Client, useFormData, ...options }: TokenEndpointOptions) { const body = useFormData ? createQueryParams(options) // Missing audience & scope in case of tokenExchange : JSON.stringify(options); // Missing audience & scope in case of tokenExchange } ``` ## Changes - `src/api.ts`: Now properly includes `audience` and `scope` in request body, if the grant_type of the request is ```urn:ietf:params:oauth:grant-type:token-exchange``` - `src/Auth0Client.ts`: Changed from always using client defaults to respecting user-provided values - `src/TokenExchange.ts`: Changed `audience: string` to `audience?: string` to properly reflect fallback behavior - `EXAMPLES.md`: Added comprehensive token exchange examples showing both default and custom audience usage - Added tests for the original bug and tests to ensure that Access Token Descoping does not happen. ## Reproduction Steps Code: ```typescript const result = await auth0.exchangeToken({ subject_token: 'external-token', subject_token_type: 'urn:custom:token-type', audience: 'https://target-api.com', // Ignored before scope: 'read:data write:data' // Ignored before }); ``` HTTP Request Body (Before): ``` grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Atoken-exchange &subject_token=external-token &subject_token_type=urn%3Acustom%3Atoken-type &client_id=your-client-id // audience and scope completely missing ``` HTTP Request Body (After): ``` grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Atoken-exchange &subject_token=external-token &subject_token_type=urn%3Acustom%3Atoken-type &audience=https%3A//target-api.com &scope=openid%20profile%20read%3Adata%20write%3Adata &client_id=your-client-id ``` ## Breaking Changes **None** - This is a bug fix that restores intended functionality without changing the public API.

Author: tusharpandey13

EXAMPLES.md

@@ -245,10 +245,20 @@ const auth0 = await createAuth0Client({
 // Exchange external token for Auth0 tokens
 async function performTokenExchange() {
  try {
+ // Option 1: Use client's default audience
  const tokenResponse = await auth0.exchangeToken({
  subject_token: 'EXTERNAL_PROVIDER_TOKEN',
  subject_token_type: 'urn:example:external-token',
  scope: 'openid profile email'
+ // audience will default to audience from client config
+ });
+
+ // Option 2: Specify custom audience for this token exchange
+ const customTokenResponse = await auth0.exchangeToken({
+ subject_token: 'EXTERNAL_PROVIDER_TOKEN',
+ subject_token_type: 'urn:example:external-token',
+ audience: 'https://different-api.example.com',
+ scope: 'openid profile read:records'
  });
 
  console.log('Received tokens:', tokenResponse);

__tests__/Auth0Client/exchangeToken.test.ts

@@ -107,11 +107,220 @@ describe('Auth0Client', () => {
  audience: 'https://api.test.com'
  };
  const result = await auth0.exchangeToken(cteOptions);
- console.log(result);
  expect(result.id_token).toEqual('fake_id_token');
  expect(result.access_token).toEqual('fake_access_token');
  expect(result.expires_in).toEqual(3600);
  expect(typeof result.scope).toBe('string');
  });
+
+ it('passes the correct scope and audience parameters to _requestToken', async () => {
+ const auth0 = await localSetup({
+ clientId: 'test-client-id',
+ domain: 'test.auth0.com',
+ authorizationParams: {
+ audience: 'https://default-api.com', // client default audience
+ scope: 'openid profile' // client default scope
+ }
+ });
+
+ // Mock _requestToken to capture the parameters
+ let capturedRequestOptions: any;
+ auth0['_requestToken'] = async function (requestOptions: any) {
+ capturedRequestOptions = requestOptions;
+ return {
+ decodedToken: {
+ encoded: {
+ header: 'fake_header',
+ payload: 'fake_payload',
+ signature: 'fake_signature'
+ },
+ header: {},
+ claims: { __raw: 'fake_raw' },
+ user: {}
+ },
+ id_token: 'fake_id_token',
+ access_token: 'fake_access_token',
+ expires_in: 3600,
+ scope: requestOptions.scope
+ };
+ };
+
+ const cteOptions: CustomTokenExchangeOptions = {
+ subject_token: 'external_token_value',
+ subject_token_type: 'urn:acme:legacy-system-token',
+ scope: 'openid profile email read:records', // custom scope for token exchange
+ audience: 'https://api.custom.com' // custom audience for token exchange
+ };
+
+ await auth0.exchangeToken(cteOptions);
+
+ // Verify the parameters passed to _requestToken
+ expect(capturedRequestOptions).toEqual({
+ grant_type: 'urn:ietf:params:oauth:grant-type:token-exchange',
+ subject_token: 'external_token_value',
+ subject_token_type: 'urn:acme:legacy-system-token',
+ scope: 'openid profile email read:records', // Should use the custom scope
+ audience: 'https://api.custom.com' // Should use the custom audience, NOT the client default
+ });
+ });
+
+ it('handles undefined scope correctly', async () => {
+ const auth0 = await localSetup({
+ clientId: 'test-client-id',
+ domain: 'test.auth0.com',
+ authorizationParams: {
+ audience: 'https://default-api.com',
+ scope: 'openid profile' // client default scope
+ }
+ });
+
+ let capturedRequestOptions: any;
+ auth0['_requestToken'] = async function (requestOptions: any) {
+ capturedRequestOptions = requestOptions;
+ return {
+ decodedToken: {
+ encoded: {
+ header: 'fake_header',
+ payload: 'fake_payload',
+ signature: 'fake_signature'
+ },
+ header: {},
+ claims: { __raw: 'fake_raw' },
+ user: {}
+ },
+ id_token: 'fake_id_token',
+ access_token: 'fake_access_token',
+ expires_in: 3600,
+ scope: requestOptions.scope
+ };
+ };
+
+ const cteOptions: CustomTokenExchangeOptions = {
+ subject_token: 'external_token_value',
+ subject_token_type: 'urn:acme:legacy-system-token',
+ audience: 'https://api.custom.com'
+ // scope is undefined - should use client default
+ };
+
+ await auth0.exchangeToken(cteOptions);
+
+ // When scope is undefined, should fallback to client default scope
+ expect(capturedRequestOptions.scope).toEqual('openid profile');
+ expect(capturedRequestOptions.audience).toEqual('https://api.custom.com');
+ });
+
+ it('handles undefined audience correctly by falling back to client default', async () => {
+ const auth0 = await localSetup({
+ clientId: 'test-client-id',
+ domain: 'test.auth0.com',
+ authorizationParams: {
+ audience: 'https://default-api.com', // client default audience
+ scope: 'openid profile' // client default scope
+ }
+ });
+
+ let capturedRequestOptions: any;
+ auth0['_requestToken'] = async function (requestOptions: any) {
+ capturedRequestOptions = requestOptions;
+ return {
+ decodedToken: {
+ encoded: {
+ header: 'fake_header',
+ payload: 'fake_payload',
+ signature: 'fake_signature'
+ },
+ header: {},
+ claims: { __raw: 'fake_raw' },
+ user: {}
+ },
+ id_token: 'fake_id_token',
+ access_token: 'fake_access_token',
+ expires_in: 3600,
+ scope: requestOptions.scope
+ };
+ };
+
+ const cteOptions: CustomTokenExchangeOptions = {
+ subject_token: 'external_token_value',
+ subject_token_type: 'urn:acme:legacy-system-token',
+ scope: 'openid profile email read:records'
+ // audience is undefined - should use client default
+ };
+
+ await auth0.exchangeToken(cteOptions);
+
+ // When audience is undefined, should fallback to client default audience
+ expect(capturedRequestOptions.scope).toEqual(
+ 'openid profile email read:records'
+ );
+ expect(capturedRequestOptions.audience).toEqual(
+ 'https://default-api.com'
+ );
+ });
+
+ it('demonstrates how wrong audience causes scope-related issues', async () => {
+ const auth0 = await localSetup({
+ clientId: 'test-client-id',
+ domain: 'test.auth0.com',
+ authorizationParams: {
+ audience: 'https://basic-api.com', // API that only supports basic scopes
+ scope: 'openid profile'
+ }
+ });
+
+ // Simulate Auth0's behavior: wrong audience = scope restrictions
+ let capturedRequestOptions: any;
+ auth0['_requestToken'] = async function (requestOptions: any) {
+ capturedRequestOptions = requestOptions;
+
+ // Simulate what happens in Auth0 when audience/scope mismatch:
+ if (
+ requestOptions.audience === 'https://basic-api.com' &&
+ requestOptions.scope.includes('read:sensitive')
+ ) {
+ // Auth0 would return an error like this:
+ throw new Error(
+ 'invalid_scope: Scope "read:sensitive" is not authorized for audience "https://basic-api.com"'
+ );
+ }
+
+ return {
+ decodedToken: {
+ encoded: {
+ header: 'fake_header',
+ payload: 'fake_payload',
+ signature: 'fake_signature'
+ },
+ header: {},
+ claims: { __raw: 'fake_raw' },
+ user: {}
+ },
+ id_token: 'fake_id_token',
+ access_token: 'fake_access_token',
+ expires_in: 3600,
+ scope: requestOptions.scope
+ };
+ };
+
+ const cteOptions: CustomTokenExchangeOptions = {
+ subject_token: 'external_token_value',
+ subject_token_type: 'urn:acme:legacy-system-token',
+ audience: 'https://sensitive-api.com', // This is what user WANTS
+ scope: 'openid profile read:sensitive' // Scope valid for sensitive-api
+ };
+
+ // Before the fix: audience would be wrong (https://basic-api.com)
+ // This would cause scope error because basic-api doesn't support read:sensitive
+
+ await auth0.exchangeToken(cteOptions);
+
+ // After the fix: correct audience is used, avoiding scope errors
+ expect(capturedRequestOptions.audience).toEqual(
+ 'https://sensitive-api.com'
+ );
+ expect(capturedRequestOptions.scope).toEqual(
+ 'openid profile read:sensitive'
+ );
+ });
  });
 });