Lambdas

Adding Claims

Here is an example of a FusionAuth lambda that adds additional claims to a JWT:

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

Using Lambda HTTP Connect

This feature allows you to make HTTP requests from within a lambda.

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

Here is a FusionAuth lambda that 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";
  }
}

You can also call FusionAuth APIs with a valid API key:

function populate(jwt, user, registration) {
  var response = fetch("http://localhost:9012/api/group", {
    method: "GET",
    headers: {
      "Authorization": "bf69486b-4733-4470-a592-f1bfce7af580"
    }
  });

  if (response.status === 200) {
    // a successful response as defined in the Groups API
    var jsonResponse = JSON.parse(response.body);
    jwt.groups = jsonResponse.groups;
  } else {
    jwt.groups = [];
  }
}

Use port 9012, or the configured value for fusionauth-app.http-local.port, whenever making a FusionAuth API call in a lambda. Doing so minimizes network traffic contention and improves performance.

Here’s a video showing more details about Lambda HTTP Connect:

headers: {
  "Content-Type": "application/json"
}

headers: new Headers({
   "Content-Type": "application/json"
})

headers: new Headers([
    ["Content-Type", "application/json"]
])

Engine

As of FusionAuth 1.35, you have the choice of JavaScript engine:

• Nashorn

• GraalJS

Versions previous to 1.35 only have access to the Nashorn engine.

Console

In addition to the standard JavaScript objects and constructs, FusionAuth provides the console object to allow you to create entries in the Event Log during a lambda invocation.

Available methods:

• info - Create an event log of type Information

• log - alias to the info method

• debug - Create an event log of type Debug (only when the Lambda has enabled Debug)

• error - Create an event log of type Error

The log, info and error will always cause Event Log entries to be created as a result of the lambda invocation. The log method is an alias to the info method. Messages created using the debug method will only be added to the Event Log when you have enabled Debug in your lambda configuration.

Messages of each type are accumulated during the lambda invocation and a maximum of one event log of each type will be created as a result of the lambda invocation. This means making multiple requests to console.info in the lambda function body will result in a single event log of type Information.

When logging objects, you’ll need to stringify them to see their data.

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.
  //...
}

Exceptions

Any exception thrown in a lambda does two things:

• write an event log entry

• exit the lambda code path

What that means for the overall 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.

In general, exceptions should not be used for flow control and should instead be used 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.

Lambda HTTP Connect Limitations

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

When using Lambda HTTP Connect to make HTTP requests, do not call a FusionAuth API which invokes the calling lambda, because it will fail. For example, in a JWT Populate lambda, do not invoke the Login API.

Requests from a lambda require the lambda to use the GraalJS engine. HTTP requests will time out after two seconds.

The fetch method in a lambda does not implement the entire fetch API as implemented in a browser. The first argument to fetch must always be a string URL. Only the following options are supported:

• method, which defaults to GET

• headers, which defaults to null

• body, which must be a string