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 Essentials or Enterprise editions of FusionAuth. Please visit our pricing page to learn more about paid editions.

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 if you have a valid API key:

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

  if (response.status === 200) {
    // assuming successful response as defined here:
    // https://fusionauth.io/docs/v1/tech/apis/groups#retrieve-a-group
    var jsonResponse = JSON.parse(response.body);
    jwt.groups = jsonResponse.groups;
  } else {
    jwt.groups = [];
  }
}

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

When an exception is thrown, further processing ceases. Whatever operation the lambda was part of (login, Identity Provider user reconciliation, etc) will not complete.

function populate(jwt, user, registration) {
  if (user.data.isNoLongerWelcome == true) {
    throw "Stop!";
  }
}

If using the hosted login pages, FusionAuth will display a customizable error message.

To learn about an exception, 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 Essentials or Enterprise editions of FusionAuth. Please visit our pricing page to learn more about paid editions.

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