Skip to main content

IO Scripts

The Script feature enables customers to define and execute custom code that responds to specific LoginRadius events, including user login, password reset, and other relevant actions. This code can be executed synchronously or asynchronously. This feature provides serverless computing capabilities integrated directly within the LoginRadius platform, enabling businesses to extend identity workflows without managing separate infrastructure.

Key Features

  • Custom Logic Execution: Trigger and run tailored code during specific events.
  • Synchronous and Asynchronous Execution: Choose between real-time execution or background processing based on workflow needs.
  • Third-Party Integration: Seamlessly interact with external APIs or services during specific events.
  • Security Enhancements: Implement additional validation or compliance checks during authentication flows.
  • Personalized User Experiences: Dynamically modify workflows based on user behavior or attributes.

This scripting capability offers greater flexibility and control, helping businesses create smarter, more adaptive CIAM solutions.

Key Things to Know Before You Start Writing a Script

Supported NPM Packages

When writing scripts, please use the set of supported npm packages to ensure optimal performance and compatibility within the scripting environment. These pre-approved modules are fully supported and thoroughly tested to ensure the smooth execution of your scripts:

  • underscore@1.13.6
  • axios@1.7.2
  • moment@2.30.1
  • async@3.2.5
  • @slack/webhook@7.0.2

The script must export a function named execute. Example:

exports.execute = async (lrObject, hook) => {
  // Your logic here
};

Script Input Parameters

Your script will receive two parameters:

  1. lrObject: Contains all relevant data about the current event. Use this object to read inputs and understand the state of the operation.
    lrObject includes the following:

  • lrObject.Request: Provides details about the incoming request

    • IP

    • Language

    • UserAgent

  • lrObject.Identity: Provides identity details of the user

    • Email

    • PhoneId

    • UserName

    • EmailVerified

    • PhoneIdVerified

    • NoOfLogins

    • Uid

    • BirthDate

    • LastPasswordChangeDate

  • lrObject.IsAuthenticated: Indicates whether the user is authenticated.
    Example:

     if (lrObject.Identity.Email.endsWith("yopmail.com"))
     
      {      
          console.log("User is using a yopmail email address."); 
      }

    Note: For user-facing output, please use appropriate return mechanisms instead of console.log. The example above uses console.log only to illustrate how to access values from the object.

  1. hook: These are functions that allow you to modify or set access token claims, custom fields, and user metadata. Provides setter functions that allow you to update claims in the access token, custom fields, and metadata.

Methods Available in hook:

  1. hook.accessToken.setCustomClaim(claim, value):

    • Adds custom claims to the user's access token.
    • Both claim and value must be strings.
      Example: hook.accessToken.setCustomClaim("role", "admin");

  2. hook.identity.setCustomField(key, value):

    Sets custom fields for the user. The custom field should be present in the user’s profile.
    Example: hook.identity.setCustomField("LastLoginDate", new Date().toISOString());

  3. hook.identity.setMetaData(key, value):

    You can set metadata fields to manage user status and access. The following fields are available for use:

  • EmailVerified
  • IsLoginLocked
  • DisableLogin
  • IsActive

    Example: hook.identity.setMetaData("Region", "US");
  1. hook.setError(code, message, description):
    Sets an error with a specific code, message, and description.

    Example: hook.setError(400, "Invalid Email", "The email domain is not allowed.");

Best Practices

  1. Always Validate Input:

    • Ensure that fields like lrObject.Identity.Email exist before accessing them to avoid runtime errors`.

  2. Handle Errors Gracefully:

    • Use hook.setError to handle validation or execution errors`.

  3. Avoid Blocking Modules:

    • The worker blocks certain Node.js modules—os (system info), fs (file system access), cluster (worker processes), and child_process (system commands)—for security reasons, as they access system-level resources.. Allowing such access could lead to unintended behavior, performance issues, or security vulnerabilities. To avoid such issues, do not attempt to use these modules in your script..

  4. Keep Scripts Simple:

    • Focus on a single responsibility per script to simplify debugging and maintenance.

Example:

Here is an example showing best practices by using error handling, ensuring function singularity, and avoiding blocked (system-level) modules

const axios = require("axios");

exports.execute = async (lrObject, hook) => {
  try {
    const response = await axios.get("https://api.example.com/user-data", {
      params: { email: lrObject.Identity.Email },
    });

    if (response.data.isAdmin) {
      hook.accessToken.setCustomClaim("role", "admin");
    }
  } catch (error) {
    console.error("Error fetching user data:", error.message);
    hook.setError(500, "Internal Server Error", "Failed to fetch user data.");
  }
};