extend / code / lambdas

Login Validation Lambda

During a login request FusionAuth performs various validations such as verifying credentials or verifying a one time code during a multi-factor login. Using this lambda function, you may extend this functionality to include your own validation as part of a login request.

The login validation lambda has access to the user record, the user’s registration for the application they’re trying to authenticate to if applicable and meta-data about the request. While Lambda HTTP Connect may be used in this function in order to utilize external resources to perform validation, please be aware that adding latency to the login request will likely be observable to your end user.

When you create a new lambda using the FusionAuth UI we will provide you an empty function for you to implement.

Lambda Structure

If you are using the API to create the lambda you will need to ensure your function has the following signature:

function validate(result, user, registration, context) {
  // Lambda code goes here
}

This lambda must contain a function named validate that takes four parameters. The parameters that the lambda is passed are:

result - an object used for returning validation errors. You can modify this object.
user - the FusionAuth User object. This object is read-only.
registration - the FusionAuth UserRegistration object. This object is read-only.
context - an object containing context for the current request. This object is read-only.

The result object contains an Errors object. The user and registration objects are well documented in the User API and Registration API documentation. The context object has the following structure:

{
  "authenticationType": "...",
  "identityProvider": {
    "id": "...",
    "name": "...",
    "identityProviderType": "..."
  }
}

authenticationtype is the method used to authenticate the user. The possible values are:

APPLE - The User was authenticated using Apple.
APPLICATION_TOKEN - The User was authenticated using an Application Authentication Token.
EpicGames -The User was authenticated using Epic Games.
FACEBOOK - The User was authenticated using Facebook.
FEDERATED_JWT - The User was authenticated using a JWT from an external Identity Provider.
GENERIC_CONNECTOR - The user was authenticated using a generic connector.
GOOGLE - The User was authenticated using Google.
HYPR - The User was authenticated using the HYPR provider.
JWT_SSO - A valid JWT authorized to one Application was exchanged for another JWT authorized to a different Application.
LDAP_CONNECTOR - The user was authenticated using an LDAP connector.
LINKEDIN - The user was authenticated using LinkedIn.
Nintendo - The User was authenticated using Nintendo.
ONE_TIME_PASSWORD The User was authenticated using a one time password.
OPENID_CONNECT - The User was authenticated using an external OpenID Connect provider.
PASSWORD - The User was authenticated using a loginId and password combination.
PASSWORDLESS - The user was authenticated using a passwordless login link.
PING - The user was authenticated using a PUT request on the Login API. This is used to record a login event without prompting for credentials, such as when the FusionAuth SSO session is used.
REFRESH_TOKEN - The User requested a new JWT using a Refresh Token.
REGISTRATION - The user was created using the Registration API.
SAMLv2 - The User was authenticated using an external SAMLv2 provider.
SAMLv2IdpInitiated - The User was authenticated using an external SAMLv2 provider using an IdP Initiated login.
SonyPSN - The User was authenticated using Sony
Steam - The User was authenticated using Steam
TWITTER - The User was authenticated using Twitter.
Twitch - The User was authenticated using Twitch
USER_CREATE - The user was created using the User API.
Xbox - The User was authenticated using Xbox

The identityProvider object in the context will only be present when the login request is from a 3rd party Identity Provider.

To deny a login attempt, simply add one or more field or general errors to the result. The error schema can be found in the API Errors documentation.

Assigning The Lambda

Once a lambda is created, you must assign it to a Tenant. Using the FusionAuth admin UI, find the Login validation lambda field found on the Security tab in the Tenant configuration.

Or if you using the Tenant API, assign the lambda Id to the tenant.lambdaConfiguration.loginValidationId field.

Example Lambda

Here is an example of a simple Lambda that prevents login attempts by users whose accounts are past due. Note that this is just an example that is assuming you have set the accountStatus in the user’s data using the User API.

function validate(result, user, registration, context) {
  if (user.data.accountStatus === 'pastDue') {
    result.errors.generalErrors = [{
      code: "[LoginRestricted]",
      message: "Account is past due, please contact accounts payable."
    }];
  }
}

Localization

When using any of the Login APIs directly, if the lambda function adds errors to the result, the API will respond with a 400 status code and the JSON response will contain the same errors object returned by the lambda function.

When using the FusionAuth hosted login pages, the messaging may be localized. The order of precedence is as follows.

If the message key returned in the code field is defined in your theme, that localized message will be displayed.
If the message key returned in the code field is not defined in your theme, the message as provided by the lambda function will be displayed.
If the message key returned in the code field is not defined in your theme, and the lambda function did not define a value for the message, the message key returned in the code field will be displayed to the user.

Using the above example, by default the user will be shown the message Account is past due, please contact accounts payable..

To localize this message, or simply modify it to be more user friendly, add the following message to your theme:

[LoginRestricted]=Looks like you forgot to pay your bill. Please call 1-800-555-5555 for assitance.

With this change, the user will be shown Looks like you forgot to pay your bill. Please call 1-800-555-5555 for assitance..

Results

Recent