External JWT Reconcile Lambda

When an External JWT identity provider is used to complete a federated login request, FusionAuth will use the configured linking strategy to reconcile the user. FusionAuth will attempt to match the user information returned from the External JWT identity provider to an existing user account or create a new one.

You may optionally utilize a lambda to customize the user and user registration during the authentication event.

When you create a new lambda using the FusionAuth Admin UI, you will be provided an empty function to implement.

Starting in version 1.65.0, you can use attribute mappings to map IdP claims directly to FusionAuth user and registration fields without writing a lambda. Reconcile lambdas and attribute mappings are mutually exclusive. Attempting to configure both on a given IdP results in a validation error.

Lambda Structure#

When you create the lambda with the API, give the function the following signature:

function reconcile(user, registration, jwt, context)  {
  // Lambda code goes here
}

This lambda must contain a function named reconcile that accepts the following parameters:

• user: the FusionAuth User object. You can modify this object. However, you can't change the email or username attributes after FusionAuth links the user.
• registration: the FusionAuth UserRegistration object. You can modify this object.

• jwt: the JSON payload returned by the external identity provider JWT. This object is read-only.
• context: Available since 1.64.0 an object containing the context of the request, including access to secrets. This object is read-only.

The User API and Registration API documentation describe the user and registration objects. The jwt object can include user claims for the lambda to read.

Assigning The Lambda#

After you create the lambda, assign the lambda to the External JWT identity provider.

Navigate to Settings -> Identity Providers . Select your existing External JWT configuration. If you haven't configured External JWT yet, click Add provider and select External JWT.

Example Lambda#

The following lambda copies the name and picture claims to the user, and keeps the saved value when a claim is missing. The lambda stores the iss claim in registration.data.issuer.

The lambda also sets the registration roles from the roles claim, but accepts only the roles in the allowedRoles list. Without the list, the other system could grant any role in your application, including an administrator role. When the JWT has no roles claim, the lambda leaves the roles unchanged.

// fills in the profile from an external JWT and accepts only the roles your application allows
function reconcile(user, registration, jwt, context) {
  user.firstName = jwt.given_name || user.firstName;
  user.lastName = jwt.family_name || user.lastName;
  user.imageUrl = jwt.picture || user.imageUrl;

  registration.data = registration.data || {};
  registration.data.issuer = jwt.iss;

  // a missing roles claim leaves the registration roles unchanged
  if (!jwt.roles) {
    return;
  }

  // never grant a role just because the other system sent it
  var allowedRoles = ['viewer', 'editor'];
  var roles = Array.isArray(jwt.roles) ? jwt.roles : [jwt.roles];
  registration.roles = roles.filter(function (role) {
    return allowedRoles.indexOf(role) !== -1;
  });
}