Integrate authenticator app policies

Applies to:

Ping SDK for Android
Ping SDK for iOS
Ping SDK for JavaScript

You can build and distribute your own authenticator app to your users so that they can participate in multi-factor authentication journeys. To help ensure the security of your app—and therefore your system—you can enable authenticator app policies.

This topic explains how to integrate support for authenticator app policies into your projects that use the Ping (ForgeRock) Authenticator module.

Prerequisites

To integrate app policies into your application that uses the Ping (ForgeRock) Authenticator module, ensure you have completed the following tasks first:

Configure your server to apply app policies.

Refer to Secure the Authenticator app using policies.
Integrate the Ping (ForgeRock) Authenticator module into your app.

Refer to Set up your Ping (ForgeRock) Authenticator module project.
Start the Ping (ForgeRock) Authenticator module in your app.

Refer to Initialize the Ping (ForgeRock) Authenticator module.

Step 1. Handle policies on the client

Policies are associated with an account registered in your authenticator app.

The Account class has the following attributes for handling app policies:

Attribute Type Visibility Description

Attribute	Type	Visibility	Description
`lockingPolicy`	String	Public	The policy that caused the account to become locked. Only the first policy that was breached is listed.
`policies`	String	Public	A JSON string containing the policy names to apply, as configured in the combined MFA node.
`lock`	Boolean	Private ¹	Whether the account is currently locked or not.

lockingPolicy

String

Public

The policy that caused the account to become locked. Only the first policy that was breached is listed.

policies

String

Public

A JSON string containing the policy names to apply, as configured in the combined MFA node.

lock

Boolean

Private ¹

Whether the account is currently locked or not.

¹ Use the public isLocked method to determine whether the account is currently locked or not

You can use the lockAccount and unlockAccount methods to manage registered accounts. To lock an account, you need to provide the policy that has been breached, as follows:

Android
iOS

// Reference to the authenticator object:
FRAClient fraClient = FRAClient.builder()
    .withContext(context)
    .start();

// Reference to the "Device tampering detection" policy:
FRAPolicy policy = new DeviceTamperingPolicy();

// Lock the account:
boolean result = fraClient.lockAccount(account, policy);

// Create the authenticator object:
FRAClient.start()

// Reference to the "Device tampering detection" policy:
let policy = DeviceTamperingPolicy()

// Lock the account:
let result = try FRAClient.lockAccount(account: account, policy: policy)

Step 2. Create custom policies

You can extend the new abstract class FRAPolicy to create new policies that you can attach to accounts.

In the class, implement the evaluate method which returns true when policy conditions are met or false if the conditions are breached. For example, if the tampered score exceeds the specified value, the evaluator would return false.

Android
iOS

static class AppIsUpToDatePolicy extends FRAPolicy {
    @Override
    public String getName() {
        return "appIsUpToDate";
    }

    @Override
    public boolean evaluate(Context context) {
        // Policy condition logic here
        return true; // policy conditions met
        // return false; // policy conditions breached - lock account
    }
}

class AppIsUpToDatePolicy: FRAPolicy {

    public var name: String = "appIsUpToDate"

    public var data: Any?

    public func evaluate() -> Bool {
        // Policy condition logic here
        return true // policy conditions met
        // return false // policy conditions breached - lock account
    }
}

To have the SDK evaluate your new policy, create a policy evaluator, as follows:

Android
iOS

Use FRAPolicyEvaluator.FRAPolicyEvaluatorBuilder and its methods withPolicies and withPolicy to pass policies to the evaluator:

FRAPolicyEvaluator policyEvaluator = new FRAPolicyEvaluator.FRAPolicyEvaluatorBuilder()
    .withPolicies(FRAPolicyEvaluator.DEFAULT_POLICIES)
    .withPolicy(new AppIsUpToDatePolicy())
    .build();

Use the FRAPolicyEvaluator.registerPolicies() method to pass policies to the evaluator.

Note that the default built-in policies are always evaluated.

To keep any existing registered policies on the account, specify the shouldOverride: false parameter:

let policyEvaluator = FRAPolicyEvaluator()
try policyEvaluator.registerPolicies(policies: [AppIsUpToDatePolicy()], shouldOverride: false)

FRAPolicyEvaluator.DEFAULT_POLICIES includes both of the default built-in policies BiometricAvailablePolicy and DeviceTamperingPolicy.

Pass the policy evaluator when building your authenticator client:

Android
iOS

FRAClient.builder()
    .withContext(context.getApplicationContext())
    .withPolicyEvaluator(policyEvaluator)
    .start();

try FRAClient.setPolicyEvaluator(policyEvaluator: policyEvaluator)
FRAClient.start()

If the policy evaluator fails, the SDK automatically locks the account.

Locked accounts block certain methods, including FRAClient.updateAccount, PushMechanism.accept and OATHMechanism.getNextOathToken. Calling these methods on a locked account throws an AccountLockException.

Ping SDKs

Integrate authenticator app policies

Prerequisites

Step 1. Handle policies on the client

Step 2. Create custom policies