|
| 1 | +# Usage |
| 2 | + |
| 3 | +Administrators can use the risk score or decision ID returned by Sift to decide whether to allow, deny, or step up authentication for a login attempt. |
| 4 | + |
| 5 | +{{product_name}} supports two mechanisms for Sift fraud detection: |
| 6 | + |
| 7 | +- **Event Publishing** — Passively publishes user events such as registrations, logins, logouts, credential updates, profile updates, and user verifications to Sift. Once configured, events are published automatically with no additional steps required. This is useful for events outside the login flow that conditional authentication cannot cover. |
| 8 | +- **Conditional Authentication** — Actively queries Sift during login and makes real-time authentication decisions based on the risk score or decision ID returned by Sift. |
| 9 | + |
| 10 | +This guide gives examples of how to use the Sift functions in [conditional authentication]({{base_path}}/guides/authentication/conditional-auth/) scripts to customize the login flow based on risk. |
| 11 | + |
| 12 | +## Prerequisites |
| 13 | + |
| 14 | +- If you haven't already, [register your application]({{base_path}}/guides/applications/#register-an-application) in {{product_name}}. |
| 15 | + |
| 16 | +- [Set up conditional authentication]({{base_path}}/guides/authentication/conditional-auth/configure-conditional-auth/) for your application. |
| 17 | + |
| 18 | +!!! note |
| 19 | + |
| 20 | + Learn more about all the elements you can use to create conditional authentication scripts in its [API reference]({{base_path}}/references/conditional-auth/api-reference/). |
| 21 | + |
| 22 | +## Risk score-based scenario |
| 23 | + |
| 24 | +In this example scenario, imagine you want to fulfill the following requirements: |
| 25 | + |
| 26 | +- if the user's risk score exceeds 0.7, fail the login attempt. |
| 27 | + |
| 28 | +- if the risk score falls between 0.5 and 0.7, prompt for an extra login step. |
| 29 | + |
| 30 | +- if authentication fails, publish a login fail event to Sift. |
| 31 | + |
| 32 | +- Enable {{product_name}} to send the user ID, session ID, IP address to Sift for risk evaluation, but prevent sending the user agent information to Sift. |
| 33 | + |
| 34 | +You can implement this using the [getSiftRiskScoreForLogin()]({{base_path}}/connectors/sift/reference/#getsiftriskscoreforlogin) function in a conditional authentication script as shown below. |
| 35 | + |
| 36 | +```javascript |
| 37 | +var additionalParams = { |
| 38 | + "loggingEnabled": true, // enable logging for debugging |
| 39 | + "$user_agent": "" // prevent sending user agent info to Sift |
| 40 | +} |
| 41 | +var errorPage = ''; |
| 42 | +var suspiciousLoginError = { |
| 43 | + 'status': 'Login Restricted', |
| 44 | + 'statusMsg': 'You login attempt was identified as suspicious.' |
| 45 | +}; |
| 46 | + |
| 47 | +var onLoginRequest = function (context) { |
| 48 | + executeStep(1, { |
| 49 | + onSuccess: function (context) { |
| 50 | + var riskScore = getSiftRiskScoreForLogin(context, "LOGIN_SUCCESS", additionalParams); |
| 51 | + if (riskScore == -1) { |
| 52 | + Log.info("Error occured while obtaining Sift score."); |
| 53 | + } |
| 54 | + if (riskScore > 0.7) { |
| 55 | + sendError(errorPage, suspiciousLoginError); |
| 56 | + } else if (riskScore > 0.5) { |
| 57 | + executeStep(2); |
| 58 | + } |
| 59 | + }, |
| 60 | + onFail: function (context) { |
| 61 | + publishLoginEventToSift(context, 'LOGIN_FAILED', additionalParams); |
| 62 | + } |
| 63 | + }); |
| 64 | +}; |
| 65 | +``` |
| 66 | + |
| 67 | +How it works: |
| 68 | + |
| 69 | +- When a user attempts to log in, the script executes step 1 (e.g., username/password authentication). |
| 70 | + |
| 71 | +- If step 1 is successful, it calls the `getSiftRiskScoreForLogin()` function, passing the current authentication context, login status, and additional parameters. This function sends the relevant contextual data to Sift and retrieves the risk score. |
| 72 | + |
| 73 | +- Based on the returned risk score: |
| 74 | + |
| 75 | + - If the score is greater than 0.7, it sends an error response, effectively blocking the login attempt. |
| 76 | + |
| 77 | + - If the score is between 0.5 and 0.7, it executes step 2 (e.g., an additional authentication step like OTP). |
| 78 | + |
| 79 | +- If step 1 fails, it calls the `publishLoginEventToSift()` function to notify Sift of the failed login attempt, which can help improve future risk assessments. |
| 80 | + |
| 81 | +- Additional parameters enable logging and prevent {{product_name}} from sending the user agent information to Sift. |
| 82 | + |
| 83 | +## Decision ID-based scenario |
| 84 | + |
| 85 | +In this example scenario, imagine you want to fulfill the following requirements: |
| 86 | + |
| 87 | +- if the decision ID is `session_looks_bad_account_takeover`, fail the login attempt. |
| 88 | + |
| 89 | +- if the decision ID is `mfa_account_takeover`, prompt for an extra login step. |
| 90 | + |
| 91 | +- if the login fails, publish a login fail event to Sift. |
| 92 | + |
| 93 | +- Enable {{product_name}} to send the user ID, session ID, IP address to Sift for risk evaluation, but prevent sending the user agent information to Sift. |
| 94 | + |
| 95 | +You can implement this using the [getSiftWorkflowDecision()]({{base_path}}/connectors/sift/reference/#getsiftworkflowdecision) function in a conditional authentication script as shown below. |
| 96 | + |
| 97 | +```javascript |
| 98 | +var additionalParams = { |
| 99 | + "loggingEnabled": true, // enable logging for debugging |
| 100 | + "$user_agent": "", // prevent sending user agent info to Sift |
| 101 | +} |
| 102 | +var errorPage = ''; |
| 103 | +var suspiciousLoginError = { |
| 104 | + 'status': 'Login Restricted', |
| 105 | + 'statusMsg': 'You login attempt was identified as suspicious.' |
| 106 | +}; |
| 107 | + |
| 108 | +var onLoginRequest = function (context) { |
| 109 | + executeStep(1, { |
| 110 | + onSuccess: function (context) { |
| 111 | + var workflowDecision = getSiftWorkflowDecision(context, "LOGIN_SUCCESS", additionalParams); |
| 112 | + if (workflowDecision == null) { |
| 113 | + Log.info("Error occured while obtaining Sift score."); |
| 114 | + } |
| 115 | + if (workflowDecision == "session_looks_bad_account_takeover") { |
| 116 | + sendError(errorPage, suspiciousLoginError); |
| 117 | + } else if (workflowDecision == "mfa_account_takeover") { |
| 118 | + executeStep(2); |
| 119 | + } |
| 120 | + }, |
| 121 | + onFail: function (context) { |
| 122 | + publishLoginEventToSift(context, 'LOGIN_FAILED', additionalParams); |
| 123 | + } |
| 124 | + }); |
| 125 | +}; |
| 126 | +``` |
| 127 | + |
| 128 | +How it works: |
| 129 | + |
| 130 | +- When a user attempts to log in, the script executes step 1 (e.g., username/password authentication). |
| 131 | + |
| 132 | +- If step 1 is successful, it calls the `getSiftWorkflowDecision()` function, passing the current authentication context, login status, and additional parameters. This function sends the relevant contextual data to Sift and retrieves the decision ID. |
| 133 | + |
| 134 | +- Based on the returned decision ID: |
| 135 | + |
| 136 | + - If the decision ID is `session_looks_bad_account_takeover`, it sends an error response, effectively blocking the login attempt. |
| 137 | + |
| 138 | + - If the decision ID is `mfa_account_takeover`, it executes step 2 (e.g., an additional authentication step like OTP). |
| 139 | + |
| 140 | +- If step 1 fails, it calls the `publishLoginEventToSift()` function to notify Sift of the failed login attempt, which can help improve future risk assessments. |
| 141 | + |
| 142 | +- Additional parameters enable logging and prevent {{product_name}} from sending the user agent information to Sift. |
0 commit comments