# Token Exchange Populate Lambda

Reference for the Token Exchange Populate lambda, which adds or narrows claims in tokens issued through token exchange.

> For the index of this section of the site, see [llms.txt](https://fusionauth.io/docs/llms.txt)

> **PLAN:** This feature requires [an Enterprise plan](https://fusionauth.io/docs/get-started/core-concepts/plans-features.md#enterprise-features).

Available since `1.70.0`

A Token Exchange Populate lambda modifies the claims of an access token issued through [token exchange](https://fusionauth.io/docs/lifecycle/authenticate-users/oauth/token-exchange.md). FusionAuth runs this lambda after the policy engine allows an exchange and before it signs the token. The lambda is optional.

## Lambda Structure

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

```javascript
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](https://fusionauth.io/docs/extend/code/lambdas.md#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`, `exp`, and `tid`. The lambda can add claims, change claims, and remove claims by setting them to `null`, with the following restrictions.

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`

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.
*   `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.
*   `exp`: FusionAuth ignores a value later than the original expiration.

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 it 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](https://fusionauth.io/docs/apis/entities/entities.md) 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

`services.secrets`

*   Type: `Object`

Provides access to [secrets](https://fusionauth.io/docs/extend/code/lambdas.md#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 edit on the Tenant.
2.  Select the OAuth tab.
3.  In the Token exchange settings section, select the lambda in **Token exchange populate lambda**.
4.  Click save.

To assign the lambda with the [Tenant API](https://fusionauth.io/docs/apis/tenants.md), set **`tenant.tokenExchangeConfiguration.populateLambdaId`** to the lambda's Id.

## Examples

### Add Claims From the Exchanger Entity

This lambda copies values from the exchanger Entity's `data` into the token:

```javascript
function populate(jwt, exchange, context) {
  const data = exchange.entity.data || {};
  if (data.department) {
    jwt['https://example.com/department'] = data.department;
  }
  if (exchange.intent) {
    jwt['https://example.com/intent'] = exchange.intent;
  }
}
```

### Copy a Claim From the Subject Token

This lambda carries a custom claim from the subject token into the issued token:

```javascript
function populate(jwt, exchange, context) {
  const orgId = exchange.subjectToken['https://example.com/org_id'];
  if (orgId) {
    jwt['https://example.com/org_id'] = orgId;
  }
}
```

### Narrow the Scope and Lifetime

This lambda removes write access and shortens the lifetime of tokens exchanged for a reporting service:

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

  const readOnly = (exchange.scopes || []).filter(scope => scope.indexOf(':write') === -1);
  if (readOnly.length > 0) {
    jwt.scope = readOnly.join(' ');
  }
  var maxExp = jwt.iat + 300;
  if (jwt.exp > maxExp) {
    jwt.exp = maxExp;
  }
}
```

Related

[Extend Lambdas An overview of FusionAuth's lambdas, which are pluggable JavaScript code that run at various points in the user lifecycle. custom claimstoken customization](https://fusionauth.io/docs/extend/code/lambdas.md)

[Extend JWT Populate Lambda An overview of the JWT populate lambda. custom claimstoken customization](https://fusionauth.io/docs/extend/code/lambdas/jwt-populate.md)

[APIs Vend a JWT API API documentation for the FusionAuth Vend a JWT API. custom claims](https://fusionauth.io/docs/apis/jwt/vend-a-jwt.md)

[APIs Retrieve a Token Exchange Chain API API documentation for the FusionAuth Retrieve a Token Exchange Chain API. rfc 8693](https://fusionauth.io/docs/apis/system/retrieve-a-token-exchange-chain.md)
---

## Other pages in Lambdas

> For the full index of this section, see [Extend](https://fusionauth.io/docs/llms-extend.txt).

- [CIMD Client Registration Lambda](https://fusionauth.io/docs/extend/code/lambdas/cimd-client-registration.md): An overview of the CIMD client registration lambda.
- [Client Credentials JWT Populate Lambda](https://fusionauth.io/docs/extend/code/lambdas/client-credentials-jwt-populate.md): An overview of the Client Credentials JWT Populate lambda.
- [Lambdas](https://fusionauth.io/docs/extend/code/lambdas.md): An overview of FusionAuth's lambdas, which are pluggable JavaScript code that run at various points in the user lifecycle.
- [JWT Populate Lambda](https://fusionauth.io/docs/extend/code/lambdas/jwt-populate.md): An overview of the JWT populate lambda.
- [Call an API from a Lambda](https://fusionauth.io/docs/extend/code/lambdas/lambda-remote-api-calls.md): An overview of how to make API calls from Lambdas.
- [Login Validation Lambda](https://fusionauth.io/docs/extend/code/lambdas/login-validation.md): An overview of the login validation lambda.
- [MFA Requirement Lambda](https://fusionauth.io/docs/extend/code/lambdas/mfa-requirement.md): An overview of the MFA requirement lambda.
- [Apple Reconcile Lambda](https://fusionauth.io/docs/extend/code/lambdas/reconcile/apple-reconcile.md): An overview of the Apple Reconcile lambda.
- [Epic Games Reconcile Lambda](https://fusionauth.io/docs/extend/code/lambdas/reconcile/epic-games-reconcile.md): An overview of the Epic Games Reconcile lambda.
- [External JWT Reconcile Lambda](https://fusionauth.io/docs/extend/code/lambdas/reconcile/external-jwt-reconcile.md): An overview of the External JWT Reconcile lambda.
- [Facebook Reconcile Lambda](https://fusionauth.io/docs/extend/code/lambdas/reconcile/facebook-reconcile.md): An overview of the Facebook Reconcile lambda.
- [Google Reconcile Lambda](https://fusionauth.io/docs/extend/code/lambdas/reconcile/google-reconcile.md): An overview of the Google Reconcile lambda.
- [HYPR Reconcile Lambda](https://fusionauth.io/docs/extend/code/lambdas/reconcile/hypr-reconcile.md): An overview of the HYPR Reconcile lambda.
- [LDAP Connector Reconcile Lambda](https://fusionauth.io/docs/extend/code/lambdas/reconcile/ldap-connector-reconcile.md): An overview of the LDAP Connector Reconcile lambda.
- [LinkedIn Reconcile Lambda](https://fusionauth.io/docs/extend/code/lambdas/reconcile/linkedin-reconcile.md): An overview of the LinkedIn Reconcile lambda.
- [Nintendo Reconcile Lambda](https://fusionauth.io/docs/extend/code/lambdas/reconcile/nintendo-reconcile.md): An overview of the Nintendo Reconcile lambda.
- [OpenID Connect Reconcile Lambda](https://fusionauth.io/docs/extend/code/lambdas/reconcile/openid-connect-response-reconcile.md): An overview of the OpenID Connect Response Reconcile lambda.
- [SAML v2 Reconcile Lambda](https://fusionauth.io/docs/extend/code/lambdas/reconcile/samlv2-response-reconcile.md): An overview of the SAML v2 Response Reconcile lambda.
- [Sony PlayStation Network Reconcile Lambda](https://fusionauth.io/docs/extend/code/lambdas/reconcile/sony-playstation-network-reconcile.md): An overview of the Sony PlayStation Network Reconcile lambda.
- [Steam Reconcile Lambda](https://fusionauth.io/docs/extend/code/lambdas/reconcile/steam-reconcile.md): An overview of the Steam Reconcile lambda.
- [Twitch Reconcile Lambda](https://fusionauth.io/docs/extend/code/lambdas/reconcile/twitch-reconcile.md): An overview of the Twitch Reconcile lambda.
- [Twitter Reconcile Lambda](https://fusionauth.io/docs/extend/code/lambdas/reconcile/twitter-reconcile.md): An overview of the Twitter Reconcile lambda.
- [Xbox Reconcile Lambda](https://fusionauth.io/docs/extend/code/lambdas/reconcile/xbox-reconcile.md): An overview of the Xbox Reconcile lambda.
- [SAML v2 Populate Lambda](https://fusionauth.io/docs/extend/code/lambdas/samlv2-response-populate.md): An overview of the SAML v2 populate lambda.
- [SCIM Group Request Converter Lambda](https://fusionauth.io/docs/extend/code/lambdas/scim-group-request-converter.md): An overview of the SCIM Group Request Converter lambda.
- [SCIM Group Response Converter Lambda](https://fusionauth.io/docs/extend/code/lambdas/scim-group-response-converter.md): An overview of the SCIM Group Response Converter lambda.
- [SCIM User Request Converter Lambda](https://fusionauth.io/docs/extend/code/lambdas/scim-user-request-converter.md): An overview of the SCIM User Request Converter lambda.
- [SCIM User Response Converter Lambda](https://fusionauth.io/docs/extend/code/lambdas/scim-user-response-converter.md): An overview of the SCIM User Response Converter lambda.
- [Self-Service Registration Validation Lambda](https://fusionauth.io/docs/extend/code/lambdas/self-service-registration.md): An overview of the Self-Service Registration Validation lambda.
- [Test Lambdas](https://fusionauth.io/docs/extend/code/lambdas/testing.md): A guide on how to create and test lambdas with FusionAuth.
- [Token Exchange Policy Lambda](https://fusionauth.io/docs/extend/code/lambdas/token-exchange-policy.md): Reference for the Token Exchange Policy lambda, which decides whether FusionAuth allows a token exchange request.
- [UserInfo Populate Lambda](https://fusionauth.io/docs/extend/code/lambdas/userinfo-populate.md): An overview of the UserInfo populate lambda.