Logo / Docs

JWT Populate Lambda

If you would like to augment the claims provided in the JWT before it has been signed you can specify a lambda in the JWT configuration. This lambda will be invoked prior to the token being signed and issued to a user.

Here’s a brief video showing how to set up a JWT populate lambda:

Play

When you create a new lambda using the FusionAuth UI we will provide you an empty function for you to implement.

This lambda is not executed if you call the Login API directly and omit the applicationId request parameter.

Lambda Structure

If you are using the API to create the lambda you will need to ensure your function has the following signature:

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

This lambda must contain a function named populate that takes up to 4 parameters. The following parameters are passed to the lambda:

  • jwt - the claims object to be signed and return as the JWT payload. You can modify this object.
  • user - the FusionAuth User object. This object is read-only.
  • registration - the FusionAuth UserRegistration object. This parameter will be undefined when the user is not registered for the application. This object is read-only.
  • context - Available since 1.59.0 - an object containing the context of the request. This object is read-only.

jwt object

You may add or modify anything in the jwt object. However, you may not modify the header keys or values of the JWT. FusionAuth also protects certain reserved claims. The following claims are considered reserved and modifications or removal will not be reflected in the final JWT payload:

  • exp - prior to version 1.59.0, the exp claim was reserved and could not be removed or modified. Since version 1.59.0, the exp claim can be modified but the value must be less than or equal to the original exp value.
  • iat
  • sub
  • tid

The tid claim was added in version 1.36.0 which means prior to that version it was not considered a reserved claim.

Prior to version 1.14.0 the following claims were considered reserved.

  • applicationId
  • aud
  • authenticationType
  • email
  • email_verified
  • exp
  • iat
  • iss
  • preferred_username
  • roles
  • sub

user and registration objects

The two FusionAuth objects are well documented in the User API and Registration API documentation. The JWT object is a JavaScript object containing the JWT payload. See OpenID Connect & OAuth 2.0 Token.

context object

The context object includes the following:

  • scopes - Available since 1.59.0 - array of scopes that were requested for the token.

Assigning The Lambda

Once a lambda is created, you must assign it to an Application. See the JWT tab in the Application configuration.

Example Lambda

Here is an example of a simple Lambda that adds a few extra claims to the JWT issued to the User.

function populate(jwt, user, registration) {
  // Add a new claim named 'favoriteColor' from a custom data attribute on the user
  jwt.favoriteColor = user.data.favoriteColor;
  // Add a new claim named 'dept' using a custom data attribute on the registration
  jwt.dept = registration.data.departmentName;

  // Create an event log of type 'Debug' when the lambda has Debug enabled
  console.debug('Added custom claims to the JSON web token');
}