FusionAuth developer image
FusionAuth developer logo
  • Back to site
  • Expert Advice
  • Blog
  • Developers
  • Downloads
  • Account
  • Contact sales
Navigate to...
  • Welcome
  • Getting Started
    • Getting Started
    • 5-minute Setup Guide
      • Overview
      • Docker
      • Fast Path
      • Sandbox
    • Setup Wizard & First Login
    • Register a User and Login
    • Self-service Registration
    • Start and Stop FusionAuth
    • Core Concepts
      • Overview
      • Users
      • Roles
      • Groups
      • Registrations
      • Applications
      • Tenants
      • Identity Providers
      • Authentication/Authorization
      • Integration Points
    • Example Apps
      • Overview
      • Dart
      • Go
      • Java
      • JavaScript
      • .NET Core
      • PHP
      • Python
      • Ruby
    • Tutorials
  • Installation Guide
    • Overview
    • System Requirements
    • Server Layout
    • Cloud
    • Cluster
    • Docker
    • Fast Path
    • Kubernetes
      • Overview
      • Deployment Guide
      • Minikube Setup
      • Amazon EKS Setup
      • Google GKE Setup
      • Microsoft AKS Setup
    • Kickstart™
    • Homebrew
    • Marketplaces
    • Packages
    • Database
    • FusionAuth App
    • FusionAuth Search
    • Common Configuration
  • Migration Guide
    • Overview
    • General
    • Auth0
    • Keycloak
    • Amazon Cognito
    • Firebase
    • Microsoft Azure AD B2C
    • Tutorial
  • Admin Guide
    • Overview
    • Account Portal
    • Config Management
    • Editions and Features
    • Key Rotation
    • Licensing
    • Monitoring
    • Prometheus Setup
    • Proxy Setup
    • Reference
      • Overview
      • Configuration
      • CORS
      • Data Types
      • Hosted Login Pages Cookies
      • Known Limitations
      • Password Hashes
    • Releases
    • Roadmap
    • Search And FusionAuth
    • Securing
    • Switch Search Engines
    • Technical Support
    • Troubleshooting
    • Upgrading
    • WebAuthn
  • Login Methods
    • Identity Providers
      • Overview
      • Apple
      • Epic Games
      • External JWT
        • Overview
        • Example
      • Facebook
      • Google
      • HYPR
      • LinkedIn
      • Nintendo
      • OpenID Connect
        • Overview
        • Amazon Cognito
        • Azure AD
        • Discord
        • Github
      • Sony PlayStation Network
      • Steam
      • Twitch
      • Twitter
      • SAML v2
        • Overview
        • ADFS
        • Azure AD
      • SAML v2 IdP Initiated
        • Overview
        • Okta
      • Xbox
    • OIDC & OAuth 2.0
      • Overview
      • Endpoints
      • Tokens
      • OAuth Modes
    • Passwordless
      • Overview
      • Magic Links
      • WebAuthn & Passkeys
    • SAML v2 IdP
      • Overview
      • Google
      • Zendesk
  • Developer Guide
    • Overview
    • API Gateways
      • Overview
      • ngrok Cloud Edge
    • Client Libraries & SDKs
      • Overview
      • Dart
      • Go
      • Java
      • JavaScript
      • .NET Core
      • Node
      • OpenAPI
      • PHP
      • Python
      • React
      • Ruby
      • Typescript
    • Events & Webhooks
      • Overview
      • Writing a Webhook
      • Securing Webhooks
      • Events
        • Overview
        • Audit Log Create
        • Event Log Create
        • JWT Public Key Update
        • JWT Refresh
        • JWT Refresh Token Revoke
        • Kickstart Success
        • Group Create
        • Group Create Complete
        • Group Delete
        • Group Delete Complete
        • Group Update
        • Group Update Complete
        • Group Member Add
        • Group Member Add Complete
        • Group Member Remove
        • Group Member Remove Complete
        • Group Member Update
        • Group Member Update Complete
        • User Action
        • User Bulk Create
        • User Create
        • User Create Complete
        • User Deactivate
        • User Delete
        • User Delete Complete
        • User Email Update
        • User Email Verified
        • User IdP Link
        • User IdP Unlink
        • User Login Failed
        • User Login Id Dup. Create
        • User Login Id Dup. Update
        • User Login New Device
        • User Login Success
        • User Login Suspicious
        • User Password Breach
        • User Password Reset Send
        • User Password Reset Start
        • User Password Reset Success
        • User Password Update
        • User Reactivate
        • User Reg. Create
        • User Reg. Create Complete
        • User Reg. Delete
        • User Reg. Delete Complete
        • User Registration Update
        • User Reg. Update Complete
        • User Reg. Verified
        • User 2FA Method Add
        • User 2FA Method Remove
        • User Update
        • User Update Complete
    • Guides
      • Overview
      • Authentication Tokens
      • Exposing A Local Instance
      • JSON Web Tokens
      • Key Master
      • Localization and Internationalization
      • Multi-Factor Authentication
      • Multi-Tenant
      • Passwordless
      • Registration-based Email Verification
      • Searching With Elasticsearch
      • Securing Your APIs
      • Silent Mode
      • Single Sign-on
      • Two Factor (pre 1.26)
    • Integrations
      • Overview
      • CleanSpeak
      • Kafka
      • Twilio
    • Plugins
      • Overview
      • Writing a Plugin
      • Custom Password Hashing
    • User Control & Gating
      • Overview
      • Gate Unverified Users
      • Gate Unverified Registrations
      • User Account Lockout
  • Customization
    • Email & Templates
      • Overview
      • Configure Email
      • Email Templates
      • Email Variables
      • Message Templates
    • Lambdas
      • Overview
      • Apple Reconcile
      • Client Cred. JWT Populate
      • Epic Games Reconcile
      • External JWT Reconcile
      • Facebook Reconcile
      • Google Reconcile
      • HYPR Reconcile
      • JWT Populate
      • LDAP Connector Reconcile
      • LinkedIn Reconcile
      • Nintendo Reconcile
      • OpenID Connect Reconcile
      • SAML v2 Populate
      • SAML v2 Reconcile
      • SCIM Group Req. Converter
      • SCIM Group Resp. Convtr.
      • SCIM User Req. Converter
      • SCIM User Resp. Converter
      • Sony PSN Reconcile
      • Steam Reconcile
      • Twitch Reconcile
      • Twitter Reconcile
      • Xbox Reconcile
    • Messengers
      • Overview
      • Generic Messenger
      • Twilio Messenger
    • Themes
      • Overview
      • Examples
      • Helpers
      • Localization
      • Template Variables
  • Premium Features
    • Overview
    • Advanced Registration Forms
    • Advanced Threat Detection
    • Application Specific Themes
    • Breached Password Detection
    • Connectors
      • Overview
      • Generic Connector
      • LDAP Connector
      • FusionAuth Connector
    • Entity Management
    • SCIM
      • Overview
      • Azure AD Client
      • Okta Client
      • SCIM-SDK
    • Self Service Account Mgmt
      • Overview
      • Updating User Data & Password
      • Add Two-Factor Authenticator
      • Add Two-Factor Email
      • Add Two-Factor SMS
      • Add WebAuthn Passkey
      • Customizing
      • Troubleshooting
    • WebAuthn
  • APIs
    • Overview
    • Authentication
    • Errors
    • API Explorer
    • Actioning Users
    • API Keys
    • Applications
    • Audit Logs
    • Connectors
      • Overview
      • Generic
      • LDAP
    • Consents
    • Emails
    • Entity Management
      • Overview
      • Entities
      • Entity Types
      • Grants
    • Event Logs
    • Families
    • Forms
    • Form Fields
    • Groups
    • Identity Providers
      • Overview
      • Links
      • Apple
      • External JWT
      • Epic Games
      • Facebook
      • Google
      • HYPR
      • LinkedIn
      • Nintendo
      • OpenID Connect
      • SAML v2
      • SAML v2 IdP Initiated
      • Sony PlayStation Network
      • Steam
      • Twitch
      • Twitter
      • Xbox
    • Integrations
    • IP Access Control Lists
    • JWT
    • Keys
    • Lambdas
    • Login
    • Message Templates
    • Messengers
      • Overview
      • Generic
      • Twilio
    • Multi-Factor/Two Factor
    • Passwordless
    • Reactor
    • Registrations
    • Reports
    • SCIM
      • Overview
      • SCIM User
      • SCIM Group
      • SCIM EnterpriseUser
      • SCIM Service Provider Config.
    • System
    • Tenants
    • Themes
    • Users
    • User Actions
    • User Action Reasons
    • User Comments
    • WebAuthn
    • Webhooks
  • Release Notes

    Lambdas

    Overview

    A FusionAuth lambda is a JavaScript function that can be used to augment or modify runtime behavior, typically during a login flow.

    FusionAuth leverages lambdas to handle different events that occur inside it as well as customize tokens and messages that FusionAuth sends such as JWTs or SAML responses. A lambda may optionally be invoked when these events occur. Developers can write lambdas in the FusionAuth UI or can upload lambdas via the API.

    • Lambda Types

    • Example Lambdas

      • Adding Claims

      • Using Lambda HTTP Connect

    • JavaScript

      • Engine

      • Console

      • Exceptions

    • Limitations

      • Lambda HTTP Connect Limitations

    • Future Engines

    Here’s a brief video covering some aspects of lambdas:

    Lambda Types

    Lambdas are typed according to their intended purpose. You cannot use a lambda intended for one situation in another.

    The following lambdas are currently supported:

    • Apple Reconcile

    • Client Credentials JWT Populate

    • Epic Games Reconcile

    • External JWT Reconcile

    • Facebook Reconcile

    • Google Reconcile

    • HYPR Reconcile

    • JWT Populate

    • LDAP Connector Reconcile

    • LinkedIn Reconcile

    • Nintendo Reconcile

    • OpenID Connect Reconcile

    • SAML v2 Populate

    • SAML v2 Reconcile

    • SCIM Group Req. Converter

    • SCIM Group Resp. Convtr.

    • SCIM User Req. Converter

    • SCIM User Resp. Converter

    • Sony PSN Reconcile

    • Steam Reconcile

    • Twitch Reconcile

    • Twitter Reconcile

    • Xbox Reconcile

    Example Lambdas

    Each lambda documentation page will have an example lambda implementation specific to that functionality. The signature of each lambda function differs for different types of 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.

    FusionAuth Reactor logo

    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:

    A lambda which adds claims based on an external API.
    
    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:

    A lambda which adds claims based on a FusionAuth API.
    
    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

    You can provide request header values in a number of different ways:

    An anonymous object
    
    headers: {
      "Content-Type": "application/json"
    }
    A hash or map
    
    headers: new Headers({
       "Content-Type": "application/json"
    })
    An array
    
    headers: new Headers([
        ["Content-Type", "application/json"]
    ])

    Response

    A response object will be returned. It will have the following fields:

    headers [Object]

    The headers returned by the response. The keys of this object are the header names. All header keys are lower cased.

    status [Integer]

    The HTTP status code.

    body [String]

    The body of the response.

    JavaScript

    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.

    Nashorn

    Nashorn is built on top of the Java virtual machine and while Nashorn permits access to the Java API, for security reasons FusionAuth restricts access to all Java objects during a lambda invocation. Here is the documentation provided by Oracle for the Nashorn engine:

    https://docs.oracle.com/javase/8/docs/technotes/guides/scripting/nashorn/

    The Nashorn engine supports ECMAScript version 5.1.

    GraalJS

    GraalJS is built on top of the Java virtual machine. For security reasons, FusionAuth restricts access to various GraalJS features during a lambda invocation.

    Here is documentation for the GraalJS engine:

    https://github.com/oracle/graaljs

    The GraalJS Engine supports ECMAScript 2021.

    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.

    Limitations

    If the Identity Provider linking strategy is set to Link Anonymously, no lambdas will be used by FusionAuth. More information about the Identity Provider linking strategies is available here.

    The FusionAuth lambdas do not have full access to JavaScript modules and libraries. They also cannot import, require or load other libraries currently. These features might be added to our lambda support in the future.

    console.log and other console methods only take one argument; this differs from the console method available in web browsers.

    Lambda HTTP Connect Limitations

    FusionAuth Reactor logo

    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

    Future Engines

    The Nashorn engine is being phased out of Java in favor of more robust and advanced engines.

    As of 1.35, FusionAuth supports the GraalJS engine. You can choose between either engine. Eventually Nashorn support will be deprecated and removed, but there is no timeline for that now. Please review the tracking issue for more details.

    Feedback

    How helpful was this page?

    See a problem?

    File an issue in our docs repo

    Have a question or comment to share?

    Visit the FusionAuth community forum.

    © 2023 FusionAuth
    Subscribe for developer updates