Lambdas Overview

In FusionAuth, a lambda is a JavaScript function that can augment or modify behavior during authentication or authorization. For example, the following lambda adds additional claims to a JWT:

function populate(jwt, user, registration) {
  jwt.favoriteColor = user.data.favoriteColor;
  jwt.applicationBackgroundColor = registration.data.backgroundColor;
}

FusionAuth uses lambdas to react to events as well as to customize tokens and messages such as JWTs or SAML responses. You can also invoke your own lambdas to further customize behavior.

Lambdas do not have full access to JavaScript modules and libraries. They also cannot import, require or load other libraries. This page explains the objects and methods that FusionAuth provides access to.

This brief video provides an overview of lambdas:

Console#

The console object creates entries in the Event Log during a lambda invocation. Unlike the browser console object, lambda console methods only accept one argument.

The console object provides the following log methods:

info() - Create an event log of type Information
log() - alias to the info method
error() - Create an event log of type Error
debug() - Create an event log of type Debug only when the Lambda has debugging enabled
Debug messages only appear in the Event Log when you have enabled Debug in your lambda configuration.

Messages accumulate during lambda invocation, creating a maximum of one event log of each type. For instance, multiple requests to console.info in the lambda function body results in a single event log of type Information that combines all of the request contents.

To see object data in the Event Log, stringify objects with JSON.stringify(<object>):

function populate(jwt, user, registration) {
  //...
  console.log(user); // doesn't log any data other than the fact a user is an object. Probably not what you want.
  console.log(JSON.stringify(user)); // outputs all the properties of the user object.
  console.log(JSON.stringify(user, null, ' ')); // pretty prints the user object.
  //...
}

HTTP Connect#

This feature is only available in an Essentials or Enterprise plan. Please visit our pricing page to learn more.

Lambda HTTP Connect makes HTTP requests from within a lambda.

For instance, the following lambda adds additional claims to a JWT based on an HTTP request:

function populate(jwt, user, registration) {
  var response = fetch("https://api.example.com/api/status?" + user.id, {
    method: "GET",
    headers: {
      "Content-Type": "application/json"
    }
  });

  if (response.status === 200) {
    // assuming successful response looks like:
    // {"status":"statusValue"}
    var jsonResponse = JSON.parse(response.body);
    jwt.status = jsonResponse.status;
  } else {
    jwt.status = "basic";
  }
}

For more information, see the Lambda HTTP Connect documentation.

Exceptions#

Throwing an exception in a lambda has the following effect:

writes an event log entry
exits the lambda code path

The impact on the user experience depends on the type of lambda. For example, for a JWT populate lambda, the JWT will not be modified. For a reconcile lambda, the user will not be created or linked.

Don’t use exceptions should for flow control; reserve them for exceptional situations.

To view exception details, enable debugging on the lambda via the Debug enabled toggle in the administrative user interface or the API.

Managing Lambdas#

Use the FusionAuth APIs, client libraries or the CLI tool to manage lambdas.

Always test your lambdas and use version control to track changes to lambdas. They are part of your authentication and authorization logic.

Engine#

GraalJS#

GraalJS is built on top of the Java virtual machine. For security reasons, FusionAuth restricts access to various GraalJS features within lambdas.

The GraalJS Engine supports ECMAScript 2021.

For more information, see the GraalJS engine documentation.

This engine has been available since FusionAuth version 1.35.0.

Nashorn#

FusionAuth removed the Nashorn engine in version 1.49.0; at or above this version, lambdas use GraalJS.

Nashorn is built on top of the Java virtual machine. While Nashorn permits access to the Java API, for security reasons FusionAuth restricts access to all Java objects within lambdas.

The Nashorn engine supports ECMAScript version 5.1.

Lambda Types#

Lambdas are typed according to their intended purpose. Different lambda types have different signatures.

FusionAuth currently supports the following lambdas; for examples and details, see the linked documentation pages:

Results

Recent