Enforce a device policy at login¶

Registration decides whether a device is allowed to be registered. Login decides whether a device is allowed in today. These are separate checks on purpose. A phone that was compliant when it registered six months ago may have been rooted since, or may have fallen behind on operating system updates.

Login enforcement is done through a conditional authentication script on the sign-in flow of the application. The script evaluates a device assurance policy against the data reported by the device and decides what to do with the result: allow the sign-in, block it, or step up to an additional factor.

Before you begin¶

Create a device assurance policy.
Make sure your users have registered their devices.
Make sure your application sends a device token when it signs the user in. See Send a device token at login.

How the device presents itself¶

When the application starts a sign-in, it sends a short-lived device token signed with the key of the registered device:

In the X-Device-Token header, when the application uses app-native authentication.
In the device_token parameter of the authorization request, when the application uses a redirect-based sign-in.

WSO2 Identity Platform identifies the registered device from the token, verifies the signature with the device's public key, and checks that the token is recent and hasn't been used before. If the token is valid and the device is Active, the device attributes carried in the token become available to the script. Otherwise, the sign-in continues without device data, and a policy evaluation reports that the device data is unavailable.

Enforcement patterns¶

Because the decision sits in a script, you can be more nuanced than a simple pass or fail. The following patterns are common:

Hard block - The device is non-compliant, so refuse the sign-in and tell the user what to fix.
Step up - The device is non-compliant, so require an additional factor rather than refusing outright.
Sensitive applications only - Add the script only to the applications that need it, for example a finance application but not a cafeteria menu application.
Grace period - Log or warn about non-compliant devices for a period before enforcing, so users have time to bring their devices into line.

Add the script¶

To enforce a policy on the login flow of an application:

On the WSO2 Identity Platform Console, go to Applications.
Select the relevant application and go to its Login Flow tab.

Add the following script in the script editor, replacing Corporate Device Policy with the name of your device assurance policy.

var policyName = "Corporate Device Policy";

var onLoginRequest = function(context) {
    executeStep(1, {
        onSuccess: function(context) {
            var result = evaluateDevicePolicy(context, policyName);
            if (!result.compliant) {
                var reason;
                if (result.status == "NON_COMPLIANT") {
                    reason = "Device does not meet the policy: "
                        + Array.prototype.join.call(result.failedFields, ", ");
                } else if (result.status == "INCOMPLETE_DEVICE_DATA") {
                    reason = "Device did not report: "
                        + Array.prototype.join.call(result.missingFields, ", ");
                } else {
                    reason = "Device could not be verified: " + result.errorCode;
                }
                fail({
                    "errorCode": "device_non_compliant",
                    "errorMessage": reason
                });
            }
        }
    });
};

Click Update to confirm.

To step up instead of blocking, call executeStep for an additional factor in place of fail. For example, executeStep(2); where step 2 is a TOTP or passkey step.

How it works¶

evaluateDevicePolicy(context, policyName) evaluates the named policy against the device that is making the request and returns a result object with the following properties.

Property	Description
`compliant`	`true` only when the status is `COMPLIANT`.
`status`	One of `COMPLIANT`, `NON_COMPLIANT`, `INCOMPLETE_DEVICE_DATA`, or `ERROR`. See How a policy is evaluated.
`failedFields`	The attributes whose values don't meet the rule of the device's platform.
`missingFields`	The attributes that the rule needs but the device didn't report.
`errorCode`	Set only when the status is `ERROR`: `device_data_unavailable` - The request carried no valid device token, or the device isn't registered or isn't active. `policy_not_found` - No policy exists with the given name. `policy_error` - The policy couldn't be evaluated, for example because the device data is invalid. `evaluation_error` - An unexpected error occurred during evaluation.

The example above passes the failed or missing attributes into the error message, so the user is told what to fix rather than being refused without explanation.

The device attributes are also available to the script as context.deviceData, if you want to make decisions on individual attributes, such as context.deviceData.platform.

Note

The policy name in the script must match the name of the policy exactly. Since a policy name cannot be changed after creation, the reference stays valid once you have set it.

For the full list of functions available to conditional authentication scripts, see the Conditional authentication API reference.