Skip to content

Reference: Sift functions and parameters

This reference describes the functions and parameters you can use in conditional authentication scripts to interact with Sift.

Note

  • To use these functions, you must first set up Sift in WSO2 Identity Server.

  • You can find example scripts in the how to use Sift guide.

getSiftRiskScoreForLogin()

This function,

  • returns a value between 0 and 1. Higher the score, greater the risk.

  • returns –1 if an error occurs due to an invalid API key, network issue or a Sift server issue.

  • Takes the following arguments.

    • AuthenticationContext - Current authentication context.

    • LoginStatus - Status of login; LOGIN_SUCCESS for a success status, LOGIN_FAILED for a failed status.

    • AdditionalParameters - Any extra parameters you want to send to Sift as explained in additional parameters.

getSiftWorkflowDecision()

This function,

  • returns the Sift decision ID for a login event. This ID uniquely identifies the decision made during the Sift workflow for that event. Learn more about Sift workflows.

  • returns null if an error occurs due to an invalid API key, network issue or a Sift server issue.

  • takes the following arguments.

    • AuthenticationContext - Current authentication context.

    • LoginStatus - Status of login; LOGIN_SUCCESS for a success status, LOGIN_FAILED for a failed status.

    • AdditionalParameters - Any extra parameters you want to send to Sift as explained in additional parameters.

publishLoginEventInfoToSift()

This function,

  • publishes the status of the current login event to Sift, indicating whether it succeeded or failed.

  • takes the following arguments.

    • AuthenticationContext - Current authentication context.

    • LoginStatus - Status of login; LOGIN_SUCCESS for a success status, LOGIN_FAILED for a failed status.

    • AdditionalParameters - Any extra parameters you want to send to Sift as explained in additional parameters.

Additional parameters

You can configure the following options when creating a conditional authentication script using Sift-related functions.

Customize the data sent to Sift

To assess risk of a login event, WSO2 Identity Server sends the following data to Sift:

  • user ID (mandatory)
  • session ID
  • IP address
  • user agent

You can override the default values that WSO2 Identity Server sends by passing these as additional parameters in the functions. You can also exclude any optional parameter from being sent, by setting the value to an empty string as shown below.

var additionalParams = {
    "$ip": "",
    "$user_agent": "",
    "$session_id": ""
}

Enable logging

You can enable logging by sending "loggingEnabled": true as an additional parameter in the functions.

  • If sent with getSiftRiskScoreForLogin() function, it logs the payload sent to Sift and the risk score that Sift returns.

  • If sent with, publishLoginEventToSift(), it logs the payload sent to Sift.