Configuring your UAF authenticators

You need to select a small set of authenticators that your end users can use to register and authenticate on their devices. Use the steps below to help lead you through this process.

Step 1. Select appropriate 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.

The Nok Nok S3 Authentication Suite includes a set of authenticators for your use. If there are Nok Nok UAF 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 Support.

Step 2. Create FIDO policies

FIDO policies enforce your organization's choice of valid UAF authenticators when a user registers and authenticates. If you create multiple tenants, each of those tenants have their own FIDO policies. For ease of management, you add UAF authenticators to an authenticator group. Add one or more authenticator groups to create a FIDO policy. The S3 Suite supplies 5 predefined authenticator groups and a sample policy that you can review.

You have at least one active 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 Create FIDO Policy Risk Rules.

The sections below cover how to create an authenticator group, add that group to a policy, configure the S3 Suite to use a policy, and customize policy selection.

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 Authenticator, the Select Authenticators dialog appears. Click each desired ID. Current and previously 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 UAF authenticators

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

Step 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 ( ).

Step 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 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 about App Attest, see Supporting App Attest.

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

Step 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.

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

Step 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.

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.

Step 3. I need authenticators that Nok Nok doesn’t provide

Your organization may wish to use authenticators from a third-party that are not included with the Nok Nok 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 (for example, fingerprint or faceprint), the type of key protection it uses, and so on. Follow the steps below.

1. Work with the vendor or Nok Nok to identify a specific set of AAIDs that you want to use.

2. Obtain the metadata for those authenticators from the vendor. Follow the instructions in Add a New Authenticator to upload the metadata into the Auth Server’s database.

3. Edit your authenticator group and add the new AAIDs. For more information, see Create an Authenticator Group in the previous step.