Step 3. Create FIDO policies

Introduction

FIDO policies enforce your organization's choice of valid FIDO authenticators when a user registers and authenticates. When you specify the name of a FIDO policy in the using policy field of a sequence of adaptive rules, the Auth Server limits the authenticators that can be used to those that conform to that FIDO policy.

You have at least one active FIDO policy for each of the following operations: registration, authentication, and transaction confirmation. The same set of authenticators can be used for both registration and authentication and most customers use a single policy for both operations. If you create multiple tenants, each of those tenants have their own FIDO policies.

When you specify UAF authenticators to include in a FIDO policy, you create groups of allowed authenticators. Digipass S3 Software supplies 5 predefined authenticator groups and a sample policy that you can review. When you specify FIDO2 authenticators to include in a FIDO policy, you specify desired characteristics instead. This article first describes how to create a FIDO policy to specify UAF authenticators and then describes how to create a FIDO policy for FIDO2 authenticators.

You can optionally add a Post Operation Rule to a FIDO policy to check various signals that may be present when a user attempts to register or authenticate. If the user’s choice of authenticator satisfies the FIDO policy, then the Authentication server applies a Post Operation rule. A Post Operation rule checks various risk signals and either i) denies the operation, ii) allows the operation, or iii) increments the FIDO policy risk score. This article contains detailed instructions to create Post Operation Rules.  

The adaptive ruleset that you configure for your app specifies which FIDO policy the Authentication Server applies for registration, authentication, and transaction operations. This article concludes with instructions for configuring a policy for situations when an adaptive ruleset is not in effect.  

Step 3.a. Create a FIDO policy for UAF authenticators

Create a list of desired characteristics for the authenticators your client app will use during registration and authentication. For example, you want to support fingerprint authenticators on Android and iOS devices.

Digipass S3 Authentication Software includes a set of authenticators for your use. If there are included authenticators that satisfy your needs, the next step is to select specific Authenticator Attestation IDs (AAIDs). Each authenticator has several associated AAIDs. Select a specific UAF authenticator, by selecting a specific AAID. For assistance selecting among the AAIDs, request the Authenticator Selection and Special Considerations Technical Note from Customer Support.

Your organization may wish to use authenticators from a third-party that are not included with the Digipass S3 Server. You can add third-party authenticators provided you have the authenticator metadata. Authenticator metadata encapsulates the technical characteristics of an authenticator such as the verification methods it supports.

You can add metadata for authenticators that includes their specific description to help distinguish each listed authenticator. See Add a New Authenticator.

Create an authenticator group

1. In the Admin Console, login and, if needed, switch to the desired tenant. Navigate to Authentication > Authenticator Groups.

2. Click Add to add a new authenticator group. The Authenticator Group page appears.

3. Name your Authenticator Group. In addition to letters and digits, only the following characters are allowed in an authenticator group name: hyphen (-), forward slash (/), underscore (_) and space ( ).

4. Click Add Authenticators, the Select Authenticators dialog appears. Click each desired ID. Selected IDs have a blue background. Click OK when you are finished.
   

   

5. Drag and drop to order your authenticator IDs from most preferred to least preferred in the Authenticator Group page.

6. Click Save.

Create a policy that uses those UAF authenticators

1. In the Admin Console, login and, if needed, switch to the desired tenant. Navigate to Authentication > FIDO Policies.

2. On the Policies page, add a new policy or edit an existing draft policy.
   If you are adding a new policy, name your policy. In addition to letters and digits, only the following characters are allowed in a policy name: hyphen (-), forward slash (/), underscore (_) and space ( ).

3. On the Policy Details page, find the FIDO UAF Authenticators panel. Make the following changes:
   

   

   1. Select the Allow FIDO UAF authenticators checkbox.

   2. Optional: If you are using the Apple App Attest service, you must configure this in your policy. Select the Request App Attest Credential. To ensure that the App Attest credential is required, see Support app integrity.

   3. Optional: If you are using the Google Play Integrity service, you must configure this in your policy. Select the Request Google Play Integrity Extension. To ensure that the integrity token and its verification are required, see Support app integrity.

   4. To add an Authenticator Group, click Add Authenticator Group. The Select Authenticator Group dialog appears. The dialog displays a list of defined authenticator groups. Click the groups you want to include and then click OK.

4. Optional: To take advantage of Conditional Passkey Creation, then from the Policy Details page open the Additional Features panel. Click Allow next to Automatically create passkey. This feature applies to both FIDO2 and UAF authenticators. Note that an application can override this setting. See Automatically Create a Passkey in the iOS, or Android Developer Guides.

5. Scroll down and click Save to save your policy.

6. A policy must be activated in order to be used by the Authentication Server. Once activated, you cannot edit it but you can copy it. To activate your policy, on the Policies page, look for the row containing your policy. Click (activate) in the Actions column.

Step 3.b. Create a FIDO policy for FIDO2 authenticators

FIDO policies enforce your organization's choice of valid FIDO2 authenticators when a user registers and authenticates. If you create multiple tenants, each of those tenants have their own FIDO policies.

Unlike UAF policies, FIDO2 policies do not require a list of valid authenticators. Instead, your policy specifies the authenticator attributes that you want. Digipass S3 Software supplies sample policies you can review.

You have at least one policy for each of the following FIDO operations: registration, authentication, and transaction confirmation. The same set of authenticators can be used for both registration and authentication and most customers use a single policy for both operations.

FIDO policies also support post operations rules. Each post operation rule contains a series of post operation checks where you can assess the degree of threat indicated by a set of risk signals.

The sections below cover how to specify FIDO2 authenticator attributes, configure Digipass S3 Software to use a policy, and customize policy selection. For authenticator-specific descriptions, you can optionally add the metadata for that authenticator.

Specify desired FIDO2 attributes

1. In the Admin Console, login and, if needed, switch to the desired tenant. Navigate to Authentication > FIDO Policies.

2. On the Policy page, click Add Policy.

3. On the Policy Details page, find the FIDO2/WebAuthn Authenticators panel.

   

4. Select the Allow FIDO2/WebAuthn authenticators checkbox so you can edit the attributes.

   To create a policy that uses platform authenticators and excludes other authenticators, refer to Create a Policy to Use Platform Authenticators. Refer to FIDO2 Attribute Table for a description of the attribute and what the values mean.

5. Optional: Choose the order that the server presents registrations to the end user’s FIDO2 platform by checking your choices - in order - next to Public Key Credential Hints. This streamlines the user experience. If you check one choice and leave another choice unchecked, the server does not send the unchecked choice to the user.

   4. Security Key is a small, external hardware device like a Digipass FX7 or a YubiKey.

   5. Client Device is a passkey.

   6. Hybrid is a passkey on a different device.

6. Optional: If you are using the Apple App Attest service, you must configure this in your policy. Select the Request App Attest Credential. To ensure that the App Attest credential is required, see Support app integrity.

7. Optional: If you are using the Google Play Integrity service, you must configure this in your policy. Select the Request Google Play Integrity Extension checkbox. To ensure that the integrity token and its verification are required, see Support app integrity.

8. Optional: To take advantage of Conditional Passkey Creation, then from the Policy Details page open the Additional Features panel. Click Allow next to Automatically create passkey. This feature applies to both FIDO2 and UAF authenticators. Note that an application can override this setting. See Automatically Create a Passkey in the iOS or Web Developer Guides to see how.

9. Scroll down and click Save. Activate your policy by clicking (activate) in the Actions column next to your new policy on the Policies page.

Create a policy to use platform authenticators

Because very few end users possess a security key, it makes sense to exclude security keys as an authenticator for FIDO2. Assign the listed values to the following attributes:

• Public Key Credential Hints: Hybrid, Client Device

• User Verification: Required

• Reject if user wasn't verified checkbox: Checked

The attribute Attestation Preference specifies the level of security and trust in the authenticator and have no effect on enforcing the use of platform authenticators.

The web browser and OS must fully support FIDO2 to enforce this policy. Unfortunately, FIDO2 support in browsers running on Apple platforms is variable and changing over time. Verify that the OS and browser combination that you want to use supports FIDO2.

FIDO2 attribute table

Post operation rules

Add a Post Operation Rule to check signals and other context data after a user has registered or authenticated on their device but before finalizing the outcome of registration or authentication. The Auth Server executes each Post Operation Rule in the FIDO policy until one of them returns a failure or they all succeed. If a Post Operation Rule matches then the Auth Server can allow the operation, deny the operation, or increment the FIDO policy risk score. On the Policy Details page you can define the final requirement by specifying the highest FIDO policy risk score that a user’s authenticator can accumulate and still have the operation allowed by this policy. After the Auth Server is finished evaluating the FIDO policy it returns its response to the App SDK.

One Post Operation Rule can consist of multiple Post Operation Checks. You define the Action that takes place when all of the Post Operation Checks in a Post Operation Rule pass. The Action can be Allow, Deny, or Increment the FIDO policy risk score.

The checks that you can configure in an Adaptive registration rule’s Supplemental check, an Adaptive authentication rule’s Post operation check, and a FIDO policy’s Post operation check are similar. The difference is that the Auth server applies them at different points during the registration or authentication process and they can have different results. The following table compares the Post operation or Supplemental checks in an Adaptive rule with the Post operation checks in a FIDO policy:

Supported risk signals

Below are examples of signals that a post operation rule can check:

• Authenticator characteristics: For example, the authenticator’s AAGUID, attestation type, FIDO and FIPS certification level.

• App integrity: Provide assurance that clients connecting to the Auth Server are valid instances of your app. An Android app uses the Google Play Integrity service to determine if the signal is acceptable, and an iOS app uses the Apple App Attest service. For more information, see Support app integrity.

• Device health: Examines the device to see if it has been rooted, may also check if the OS was modified or running malware.
  A post operation rule checks if device health fails or if device health information is unavailable.
  The Auth Server determines device health using the jailbreak signal. A device's jailbreak status detects if it has been altered to provide root access. The App SDK must be configured to send this signal to the Auth Server. See Configuring Signal Generation in the Android or iOS App SDK Guides.

• Friendly fraud detected: Present if the user didn't utilize the correct biometric verification or the state of the biometric enrollments on the user’s device has changed. This signal is only available for UAF authentication methods and it is not applicable for fingerprint authenticators that support automatic key deletion. A Post Operation rule's check can tell if friendly fraud is present.

• User count on device: The number of users registered on the user’s device.
  A rule's condition specifies the maximum number of allowed registered users on a single device.

• Registered device count: The number of different devices registered to the user.
  A rule's condition specifies the maximum number of registered devices that a user can have.

For a complete list, see Data used by Adaptive rules and FIDO policies:

Configure a FIDO policy for non-adaptive registration

Your adaptive rulesets specify which FIDO policy the Auth Server should use when applying that ruleset. But there are some circumstances when there is no adaptive ruleset that applies. For example, when a user is managing their registrations and chooses to register a new authenticator. By default in these cases the Auth Server enforces the FIDO policy named "default". If you want your Auth Server to enforce a different FIDO policy when deciding whether to approve or deny this registration, follow the instructions in this section.

Configure the Policy Selector Plugin to specify which FIDO policy to use when a user registers an authenticator outside of an adaptive ruleset. Modify the JSON configuration object called default_config, to assign your chosen FIDO policy to registration_policy_name.

{
    "registration_policy_name": "acmeRegistration",
}

Use the instructions below to update the policy. For reference, you can find a complete description of default_config at Policy selector plugin.

Using the Admin Console

1. In the Admin Console, login and, if needed, switch to the desired tenant. Navigate to Configuration > API Server >Policy Plugin.

2. In the panel, click the Policy Selector label. The Policy Selector dialog appears and displays the current configuration. Copy this into a file.

3. Edit the file. Assign your FIDO policy name to registration_policy_name.

4. Click Import. Navigate to your modified file to upload. If you need to reset back to the default configuration, click Reset.

Using nnl-mgmt.sh

1. Export the Policy plugin's default_config object for the desired tenant. Below is an example exporting this configuration object from the investment tenant into file myconfig.json:

./nnl-mgmt.sh apiserver export -tenant investment -type PolicyPlugin -name default_config -file myconfig.json

2. Edit the configuration object, updating the FIDO policy name for the registration_policy_name.

3. Import your modified file. Below is an example using nnl-mgmt.sh's apiserver import command for the investment tenant.

./nnl-mgmt.sh apiserver import -tenantid investment -type PolicyPlugin -name default_config -file myconfig.json

For details on nnl-mgmt.sh's apiserver import command, see API Server Configuration Commands.

Override the server's configured policy

A client app can specify a FIDO policy to use for a non-adaptive registration operation. When the client app initiates a non-adaptive registration operation and sends in an additional parameter, the policy name in the parameter overrides the Server's configured policy name.

For more information, see the client API docs for:

• Android - IAppSDKPlus.EXTRA_KEY_OPTION_POLICY_NAME

• iOS - ExtrasKeyOptionsPolicyName

• Web - AppSdk.EXTRA_KEY_OPTIONS_POLICY_NAME

Customize policy selection

Policies can be selected dynamically through the use of a custom policy selector plugin on the API Server. Contact OneSpan support if you are interested in creating a custom policy selector plugin.