Configure 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 you want. The S3 Suite 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 risk rules which assess the degree of threat indicated by a set of risk signals. To learn more about risk rules, see Creating FIDO Policy Risk Rules.

The sections below cover how to specify FIDO2 authenticator attributes, configure the S3 Suite 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 Creating 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 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 both the Request App Attest Credential and Reject if missing or invalid checkboxes. The latter checkbox ensures that the App Attest credential is required. For more information, see Support App Attest.

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 and Reject if missing or invalid checkboxes. The latter checkbox ensures that the integrity token and its verification are required. For more information, see Support Google Play 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.

Creating 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, Security Key

• 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

Configure a FIDO policy for non-adaptive registration

Your adaptive rulesets specify which FIDO policy the Auth Server should use in different circumstances. But sometimes the Server receives a request to register an authenticator that did not originate from an adaptive rule. 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 plugin on the API Server. Contact Nok Nok Support if you are interested in creating a custom policy plugin.

Add metadata

By default, the Auth Server includes metadata for a generic FIDO2 authenticator. When you register a FIDO2 authenticator, your client app uses the description of "Generic FIDO 2 Authenticator". You can add metadata for authenticators that includes their specific description to help distinguish each listed authenticator. See Add a New Authenticator.