Token Exchange Populate Lambda

On this page
Enterprise plan required

This feature requires an Enterprise plan.

Available since 1.70.0

A Token Exchange Populate lambda modifies the claims of an access token issued through token exchange. FusionAuth runs this lambda after the policy engine allows an exchange and before FusionAuth signs the token. The lambda is optional.

Lambda Structure#

The lambda must contain a function named populate with the following signature:

function populate(jwt, exchange, context) {
  // Lambda code goes here
}

The function accepts the following parameters:

  • jwt: the claims of the token FusionAuth is about to sign. This object is mutable.
  • exchange: information about the exchange. This object is read-only.
  • context: access to secrets. This object is read-only.

The jwt Object#

Before the lambda runs, the jwt object contains the claims FusionAuth built from the policy decision and the subject token, including sub, aud, scope, act, client_id, gty, exp, and tid. The lambda can add and change claims, and remove a claim by setting the claim to null. The following restrictions apply.

FusionAuth discards any changes to the following reserved claims:

  • act
  • amr
  • applicationId
  • auth_time
  • authenticationType
  • client_id
  • cnf
  • gty
  • iat
  • iss
  • jti
  • may_act
  • sid
  • sub
  • tid
  • tty

FusionAuth also removes any fa_uid claim the lambda adds.

The lambda can only narrow the following claims:

  • aud: FusionAuth keeps only the values that the policy engine granted. If no granted values remain, or the lambda removes the claim, FusionAuth restores the granted audiences. When the policy engine granted no audiences, FusionAuth removes aud.
  • scope: FusionAuth keeps only the scopes that the policy engine granted. If no granted scopes remain, or the lambda removes the claim, FusionAuth restores the granted scopes. When the policy engine granted no scopes, FusionAuth removes scope.
  • exp: FusionAuth caps exp at the original expiration, so the lambda can shorten the token lifetime but not extend the lifetime. Setting exp to null keeps the original value.

FusionAuth copies the amr, applicationId, auth_time, authenticationType, and sid claims from the subject token when they are present. FusionAuth doesn't copy any other claims from the subject token. To carry over another claim, copy the claim from exchange.subjectToken.

To avoid conflicts with registered claims and claims FusionAuth adds in the future, give custom claims a namespaced name, such as https://example.com/department.

The exchange Object#

subjectToken
  • Type: Object

The claims of the validated subject token.

entity
  • Type: Object

The exchanger Entity, without its client secret. See the Entity API for the fields of this object.

audiences
  • Type: Array<String>

The audiences the policy engine granted.

scopes
  • Type: Array<String>

The scopes the policy engine granted.

intent
  • Type: String

The value of the intent request parameter. Undefined when the request doesn't include intent.

state
  • Type: String

The value of the state request parameter. Undefined when the request doesn't include state.

The context Object#

The read-only context object has the following fields:

  • services: access to secrets through context.services.secrets.get('<secret-name>').

Errors#

If the lambda throws an exception, FusionAuth rejects the exchange with a 422 status code and a server_error error, and records the attempt in the audit log with the POPULATE_LAMBDA_ERROR outcome. To keep an exchange from failing because of an optional step, such as a call to an external service, catch exceptions in the lambda.

Assigning the Lambda#

To assign the lambda in the Admin UI:

  1. Navigate to Tenants and click on the Tenant.
  2. Select the OAuth tab.
  3. In the Token exchange settings section, turn on Enable token exchange grant.
  4. Select the lambda in Token exchange populate lambda.
  5. Click .

To assign the lambda with the Tenant API, set tenant.tokenExchangeConfiguration.populateLambdaId to the lambda's Id.

Examples#

Add Claims From the Exchange#

This lambda copies the exchanger Entity's department from the Entity's data, and the intent request parameter. The lambda also carries a custom organization claim over from the subject token, because FusionAuth doesn't copy custom claims:

A lambda that adds claims from the exchange.
// adds the exchanger's department, the request intent, and the user's organization to the token
function populate(jwt, exchange, context) {
  var data = exchange.entity.data || {};
  if (data.department) {
    jwt['https://piedpiper.com/department'] = data.department;
  }

  // intent is undefined when the request leaves it out
  if (exchange.intent) {
    jwt['https://piedpiper.com/intent'] = exchange.intent;
  }

  // FusionAuth copies only a few claims from the subject token, so carry custom claims over here
  var orgId = exchange.subjectToken['https://piedpiper.com/org_id'];
  if (orgId) {
    jwt['https://piedpiper.com/org_id'] = orgId;
  }
}

Narrow the Scope and Lifetime#

This lambda removes write access and caps the lifetime at five minutes for tokens exchanged for a reporting service. When the policy engine granted only write scopes, the lambda leaves scope unchanged, because FusionAuth restores the granted scopes when none remain:

A lambda that narrows the scope and lifetime of a token.
// removes write access and shortens the lifetime of tokens for the reporting service
var maxLifetimeInSeconds = 300;

function populate(jwt, exchange, context) {
  if ((exchange.audiences || []).indexOf('reporting-service') === -1) {
    return;
  }

  var readOnly = (exchange.scopes || []).filter(function (scope) {
    return scope.slice(-6) !== ':write';
  });
  // an empty scope makes FusionAuth restore the granted scopes, so leave the claim alone
  if (readOnly.length > 0) {
    jwt.scope = readOnly.join(' ');
  }

  // FusionAuth ignores a later exp, so only shorten the lifetime
  if (jwt.exp > jwt.iat + maxLifetimeInSeconds) {
    jwt.exp = jwt.iat + maxLifetimeInSeconds;
  }
}