Integrate authenticator app policies
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 ForgeRock Authenticator module.
Prerequisites
To integrate app policies into your application that uses the ForgeRock Authenticator module, ensure you have completed the following tasks first:
-
Configure your ForgeRock server to apply app policies.
-
Integrate the ForgeRock Authenticator module into your app.
-
Start the ForgeRock Authenticator module in your app.
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 |
---|---|---|---|
|
String |
Public |
The policy that caused the account to become locked. Only the first policy that was breached is listed. |
|
String |
Public |
A JSON string containing the policy names to apply, as configured in the combined MFA node. |
|
Boolean |
Private 1 |
Whether the account is currently locked or not. |
1 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:
// 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
.
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:
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:
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
.