Skip to content

Add conditional authentication

With conditional authentication, the login flow in an application is dependent on the risk factors associated with the user's login request. This allows you to strengthen the authentication flow when the risk is higher. In WSO2 Identity Server, conditional authentication is configured using a script.

what is conditional authentication

Authentication script

The authentication script for configuring dynamic authentication flows in WSO2 Identity Server uses a functional language similar to Javascript. You can configure the script using the script editor in the WSO2 Identity Server Console. You can either use a template or write a custom script.

This scripting language supports a set of inbuilt functions and objects. A simple conditional authentication script will look like the following:

var onLoginRequest = function(context) {
    // Some possible initializations...
    executeStep(1);
        if (doStepUp(context) === true) { 
            executeStep(2);
        }
};

function doStepUp(context) {
    // A function that decides whether to enforce second step based on the request context.
    return true;
}

Note

Find out more about the scripting language in the Conditional Authentication API Reference.

Script templates

The script editor in WSO2 Identity Server comes with a set of predefined templates to get you started with some of the most common conditional authentication scenarios. These scripts contain inline comments explaining the conditions that are applied.

conditional-auth-templates-view

The available templates are categorized as follows:

  • User
  • Request
  • Environment
  • Analytics
  • IdP

The pre-defined templates are listed below.

Template Description
Role-Based This login flow prompts two-factor authentication (2FA) for users who are assigned to any of the given set of roles.
User-Age-Based This configures a login flow where users can log in only if their age is over the configured value. The user's age is calculated using the date of birth attribute.
User Store-Based This login flow prompts two-factor authentication (2FA) for users who are from to any of the given set of user stores.
Login Attempt-Based This login flow prompts two-factor authentication (2FA) for users who are from to any of the given set of user stores.
Group-Based This login flow prompts two-factor authentication (2FA) for users who belong to any of the given set of groups.
Concurrent Session-Based This login flow prompts adaptive authentication for users who have exceeded the maximum number of allowed sessions.
New-Device-Based This login flow sends an email notification and/or prompts two-factor authentication for users who are logged in from a previously unused device.
IP-Based This login flow prompts two-factor authentication for users who log in from outside the given IP range.
Passkey-Progressive-Enrollment-Based This login flow permits users to seamlessly enroll their passkey on-the-fly, when Passkey is designated as the first authentication factor.

If required, you can also use the script editor to introduce new functions and fields to an authentication script based on your requirement. See the instructions on writing a custom authentication script.

What's next