Token exchange

Token exchange (RFC 8693) lets an API that received a person's access token get a new token for a different API, for the same person. The invoices API, handling Ada's request, needs Ada's reports. Forwarding Ada's token does not work: it was issued for the invoices API only, and the reports API refuses it. Calling with the invoices API's own service identity loses track of who the request is for. Token exchange gives the invoices API a token for the reports API that still names Ada as the subject (sub) and names the invoices API as the actor (act).

Use it for service-to-service calls that act for a person, when each API accepts only tokens issued for it (resource indicators). Token exchange is part of the OAuth/OIDC provider and always available; a client may use it only when it is registered for the urn:ietf:params:oauth:grant-type:token-exchange grant type.

How it works

Setup

import { createOAuthProvider } from 'better-iam/oauth';
import { iam } from './iam';

const keys = JSON.parse(process.env.OIDC_KEYS!); // { jwks, cookieKeys, encryptionKey }

export const issuer = createOAuthProvider({
  ...iam.protocolHost,
  issuer: 'https://identity.example/oidc',
  jwks: keys.jwks,
  cookieKeys: keys.cookieKeys,
  encryptionKey: keys.encryptionKey,
  trustedOrigins: ['https://identity.example'],
  interactionUrl: (uid) => `https://identity.example/interactions/${uid}`,
  renderDevicePage: ({ form }) => `<main>${form}</main>`,
  renderLogoutPage: ({ form }) => `<main>${form}</main>`,
  resourceServers: {
    'https://invoices.example': { scopes: ['invoices:read'] },
    'https://reports.example': { scopes: ['reports:read', 'reports:admin'] },
  },
  // Optional: your own rule, checked after the built-in ones.
  authorizeTokenExchange: ({ clientId, subjectClientId, scopes }) =>
    clientId === 'invoices-api' && subjectClientId === 'invoices-web' && !scopes.includes('reports:admin'),
});
iam.useProtocol(issuer);

import { issuer } from '../oauth';

const { clientSecret } = await issuer.registerClient(adminCredential, {
  tenantId: 'acme',
  clientId: 'invoices-api',
  name: 'Invoices API',
  redirectUris: [],
  grantTypes: ['urn:ietf:params:oauth:grant-type:token-exchange'],
  scopes: ['reports:read'],
  resources: ['https://reports.example'],
});
// Store clientSecret in the invoices API's secret store. It is shown once.

import { createAccessTokenVerifier } from 'better-iam/oauth';

export const verifier = createAccessTokenVerifier({
  issuer: 'https://identity.example/oidc',
  audience: 'https://reports.example',
});

Usage

Exchange a token

The calling API posts the person's access token to the token endpoint, authenticated as itself:

const tokenEndpoint = 'https://identity.example/oidc/token';
const basic = Buffer.from(`invoices-api:${process.env.INVOICES_API_SECRET}`).toString('base64');

export async function exchangeForReports(subjectToken: string) {
  const response = await fetch(tokenEndpoint, {
    method: 'POST',
    headers: {
      authorization: `Basic ${basic}`,
      'content-type': 'application/x-www-form-urlencoded',
    },
    body: new URLSearchParams({
      grant_type: 'urn:ietf:params:oauth:grant-type:token-exchange',
      subject_token: subjectToken,
      subject_token_type: 'urn:ietf:params:oauth:token-type:access_token',
      resource: 'https://reports.example',
      scope: 'reports:read',
    }),
  });
  const body = (await response.json()) as Record<string, string | number>;
  if (!response.ok) throw new Error(`Token exchange failed: ${body.error}`);
  return body as {
    access_token: string;
    issued_token_type: 'urn:ietf:params:oauth:token-type:access_token';
    token_type: 'Bearer';
    expires_in: number;
    scope: string;
  };
}

Endpoint: POST {issuer}/token with grant_type=urn:ietf:params:oauth:grant-type:token-exchange

Each parameter may appear once. The client authenticates the way it was registered: client_secret_basic (above), client_secret_post, or private_key_jwt.

Call the downstream API

import { exchangeForReports } from '../reports-client';

export async function GET(request: Request) {
  const subjectToken = request.headers.get('authorization')!.replace(/^Bearer /, '');
  const { access_token } = await exchangeForReports(subjectToken);
  const reports = await fetch('https://reports.example/reports', {
    headers: { authorization: `Bearer ${access_token}` },
  });
  return new Response(reports.body, { status: reports.status });
}

Verify the incoming token with the invoices API's own verifier before exchanging it. The exchange checks it again, but your API should not act on a request it has not authenticated.

Read the actor in the downstream API

import { IamError } from 'better-iam';
import { verifier } from '../auth';

export async function GET(request: Request) {
  try {
    const token = await verifier.verifyRequest(
      {
        authorization: request.headers.get('authorization'),
        dpop: request.headers.get('dpop'),
        method: request.method,
        url: request.url,
      },
      { scopes: ['reports:read'] },
    );
    // token.subject: the person. token.clientId and token.actor.sub: 'invoices-api'.
    return Response.json({ person: token.subject, via: token.actor?.sub, tenant: token.tenantId });
  } catch (error) {
    if (!(error instanceof IamError)) throw error;
    return new Response(null, { status: error.status, headers: { 'www-authenticate': verifier.challenge(error) } });
  }
}

What the issued token contains

The format is the target resource server's accessTokenFormat (JWT by default). Each exchange is appended to the tenant's audit chain as iam:oauth:TokenExchange, with the subject account as actor and the exchanging client as resource.

Rules the provider enforces

• The subject token is a JWT access token signed by this issuer (typ: at+jwt) or an opaque access token the provider stores. ID tokens and refresh tokens are refused.
• It must not be DPoP-bound: the exchanging client cannot prove the original client's key.
• It must have been issued to a client that is not revoked and is in the exchanging client's tenant. For a person's JWT token, the person's consent to that client must still exist, so disconnecting the app stops its tokens from being exchanged.
• The account it names must be active, in the same tenant, and the tenant must be active.
• The target must be both a declared resource server and one of the exchanging client's resources.
• Granted scopes are the requested ones, each allowed by the client's scopes and the target's scopes. One refused scope fails the whole request.
• authorizeTokenExchange, when set, runs last and can refuse with access_denied.

Add your own policy

Without authorizeTokenExchange, any client registered for the grant may exchange for its own resources and scopes. Add it to restrict which apps' tokens an API may exchange, or which scopes it may delegate. It receives a TokenExchangeRequest and returns true to allow:

Endpoints

The token exchange grant type is listed in the discovery document's grant_types_supported.

Options

Errors

The token endpoint answers with standard OAuth error codes in a JSON body:

Registering the client can fail with INVALID_INPUT (a public client, an unknown resource indicator, or an unsupported scope) or CONFLICT (the client ID exists). In the downstream API, the verifier fails with INVALID_TOKEN (401) or INSUFFICIENT_SCOPE (403).

Related