PingAM 7.5.0

MFA: Web authentication (WebAuthn)

WebAuthn lets users authenticate with an authenticator device, such as the fingerprint scanner on their laptop or phone. The user’s browser communicates with the authenticator device.

AM can request the browser to activate the authenticator device with certain criteria; for example:

  • The authenticator device must be built-in, not a USB device that the user can eject

  • The device must verify the user’s identity, not just the user’s presence

To use WebAuthn with AM, users must first register their authenticators. If recovery codes are enabled, users should copy their codes on successful registration.

Registration involves the selected authenticator creating, or minting, a key pair. The public key of the pair is returned to AM and stored in the user’s profile. The private key is stored securely in the authenticator itself or in the platform that manages the authenticators. The private key does not leave the client at any time.

When authenticating with WebAuthn, the authenticator device locks data with its stored private key and sends it to AM. AM verifies the data using the public key stored in the user’s profile. If the data verification succeeds and passes any attestation checks, AM considers the authentication successful.

The user must connect over HTTPS to use WebAuthn.

AM supports WebAuthn for the following user agents on the specified platforms:

Browsers and platforms supported for WebAuthn
Browser(1) Platform

Google Chrome

Desktop

Android

Safari

Desktop

iOS

Microsoft Edge

Desktop

Mozilla Firefox

Desktop

(1) Latest stable versions are supported.

Create trees for WebAuthn

The example tree that follows registers the user’s device if necessary, and authenticates the user with the device. If the user has already registered their device, they only need to enter their username, and then perform the authorization gesture with their registered device to complete authentication.

If the user does not have a registered device, they must provide both their username and their password. The Data Store Decision node confirms their identity before allowing them to register their device. The user then authenticates with the new device to complete authentication.

The tree created here does not include user-friendly features, such as letting the user retry their password if they mistype it.

Configure the WebAuthn Profile Encryption service

In the AM admin UI, configure the WebAuthn Profile Encryption service for the realm where you create the tree.

This service configures how AM stores registered device metadata.

  1. In the AM admin UI for the realm, click Services > Add a Service.

  2. Select WebAuthn Profile Encryption Service in the service type drop-down list, and create the new service configuration.

  3. Accept the default configuration unless you must encrypt the device metadata in user profiles:

    Profile Storage Attribute

    webauthnDeviceProfiles (default)

    Device Profile Encryption Scheme

    If you choose an encryption scheme, also edit the settings to access the keys.

    For details, read Secrets, certificates, and keys.

    Default: No encryption of device settings.

    For detailed information about the available properties, refer to WebAuthn profile encryption service.

Create the WebAuthn tree

  1. Configure the WebAuthn Profile Encryption service for the realm if you have not already done so.

  2. In the AM admin UI, create a tree for WebAuthn under Realms > Realm Name > Authentication > Trees.

  3. Add the following nodes to your tree:

  4. Connect the nodes as demonstrated in the following figure:

    A tree for WebAuthn authentication.

  5. On the WebAuthn Authentication node, select Allow recovery codes.

  6. On the WebAuthn Registration node, select Generate recovery codes.

  7. Save your changes.

Test the WebAuthn tree

  1. Register a test user account unless you have already done so.

  2. In an incognito browser window, browse to the WebAuthn tree.

    The URL looks something like:
    https://openam.example.com:8443/openam/XUI/?realm=/alpha&service=myWebAuthnTree#login

    A login screen prompts for the username.

  3. Enter the username for the test user account.

  4. If the user does not have a registered device:

    1. Enter the test user’s password when prompted.

    2. Register a WebAuthn authenticator by performing an authorization gesture.

      For example, press the button on a connected YubiKey or scan your fingerprint.

      WebAuthn registration waiting for an authenticator

      The browser may present a consent pop-up to allow access to the available authenticators.

      When you grant consent, the browser activates the relevant authenticators, ready for registration.

      If the device registration is successful, the tree returns to the WebAuthn Authentication node.

  5. When prompted, authenticate by performing an authorization gesture with a registered device.

    The UI displays the user profile page.

    The dashboard page lists the registered devices that you can rename or delete.

    The default name for a new WebAuthn device is New Security Key.

Configure usernameless authentication with ForgeRock Go

With ForgeRock Go, you can create a secure and seamless login experience by authenticating with any credential on the user’s device that supports FIDO2 WebAuthn.

You can also extend passwordless authentication to include usernameless authentication with popular authenticators that support resident keys; for example, Windows Hello (biometric authenticators).

To use usernameless authentication, you must register an authenticator that supports resident keys to the user’s profile, and enable the option to associate a certificate on the device with the user’s username.

Once registered, that device can be used to authenticate the user without them having to provide their credentials; they need to select the appropriate entry to use from the list their device provides.

To configure usernameless authentication with ForgeRock Go, create a web authentication registration tree to associate a device that supports resident keys with a user. The registration tree is similar to that described in Create trees for WebAuthn.

Create a second tree that lets users authenticate to AM without entering their username or password, by using ForgeRock Go.

The trees created here do not include user-friendly features, such as allowing retries or redirecting for further help on failures.

Create the ForgeRock Go registration tree

  1. Configure the WebAuthn Profile Encryption service for the realm if you have not already done so.

  2. In the AM admin UI, create a tree for ForgeRock Go registration under Realms > Realm Name > Authentication > Trees.

  3. Add the following nodes to your tree:

    • Data Store Decision node

    • Page node

    • Username Collector node

    • Password Collector node

    • WebAuthn Registration node

    • (Optional) Scripted Decision node

      When configured for ForgeRock Go, by default the WebAuthn Registration node stores the tree’s shared state variable username on the device. During authentication, this value later identifies the user.

      Use a Scripted Decision node to customize the display name or string to be saved in the shared state.

      Script to set the display name

      • Next-generation

      • Legacy

      var user = nodeState.get('username');
var identity = idRepository.getIdentity(user);

var displayName = '';

var givenName = identity.getAttributeValues('givenName')[0];
var surname = identity.getAttributeValues('sn')[0];
var email = identity.getAttributeValues('mail')[0];

if (givenName) {
  displayName += givenName;
}

if (surname) {
  displayName += ' ' + surname;
}

if (email) {
  displayName += ' (' + email + ')';
}

if (displayName) {
  nodeState.putShared('displayName', displayName);
} else {
  nodeState.putShared('displayName', user);
}
action.goTo("true");
      var fr = JavaImporter(org.forgerock.openam.auth.node.api.Action);

var user = nodeState.get('username').asString();
var displayName = '';

var givenName = idRepository.getAttribute(user, 'givenName');
var surname = idRepository.getAttribute(user, 'sn');
var email = idRepository.getAttribute(user, 'mail');

if (givenName) {
  displayName += givenName.toArray()[0];
}

if (surname) {
  displayName += ' ' + surname.toArray()[0];
}

if (email) {
  displayName += ' (' + email.toArray()[0] + ')';
}

if (displayName) {
  nodeState.putShared('displayName', displayName.toString());
} else {
  nodeState.putShared('displayName', user.toString());
}
action = fr.Action.goTo("true").build();

  4. Connect the nodes as demonstrated in the following figure:

    A tree for ForgeRock Go device registration.

    If you do not use the Scripted Decision node, connect the Data Store Decision node True output directly to the WebAuthn Registration node.

  5. If you use the Scripted Decision node:

    1. Select your script in the Script dropdown.

    2. Add the outcome of your script, true in this example, in the Outcomes field.

  6. On the WebAuthn Registration node:

    1. Select Username to device.

    2. If you do not use the Scripted Decision node, add userName in the Shared state attribute for display name field.

    3. If you use the Scripted Decision node, add the shared state variable name, such as displayName, in the Shared state attribute for display name field.

  7. Save your changes.

Create the ForgeRock Go authentication tree

  1. Configure the WebAuthn Profile Encryption service for the realm if you have not already done so.

  2. In the AM admin UI, create a tree for ForgeRock Go authentication under Realms > Realm Name > Authentication > Trees.

  3. Add a WebAuthn Authentication node to your tree.

  4. Connect the nodes as demonstrated in the following figure:

    A tree for ForgeRock Go device authentication.

  5. On the WebAuthn Authentication node, ensure Username from device is enabled.

  6. Save your changes.

Register with ForgeRock Go

Follow these steps to register a device for usernameless authentication, and then authenticate with no username or password, only an authorization gesture.

  1. Register a test user account unless you have already done so.

  2. In an incognito browser window, browse to the ForgeRock Go registration tree.

    The URL looks something like:
    https://openam.example.com:8443/openam/XUI/?realm=/alpha&service=myForgeRockGoRegistrationTree#login

    A login screen prompts for your credentials.

  3. Sign in with the username and password of the test user.

  4. If you are authenticating from a FIDO2-enabled device, it prompts you for the method to verify your identity.

    For example, you might use a USB security key or a built-in biometric sensor.

    Select the option to associate with the user.

  5. Perform the authorization gesture of the chosen option when asked to do so.

    For example, press the button on your USB security key or scan your fingerprint.

    The UI displays the user profile page.

    The dashboard page lists the registered devices that you can rename or delete.

Authenticate with ForgeRock Go

After registering, authenticate with ForgeRock Go without your username or password:

  1. Sign out.

  2. In the same browser window, browse to the ForgeRock Go authentication tree.

    The URL looks something like:
    https://openam.example.com:8443/openam/XUI/?realm=/alpha&service=myForgeRockGoAuthenticationTree#login

  3. Perform the authorization gesture of the chosen option when prompted.

    A list of the accounts associated with the authentication device displays:

    Google Chrome presenting the accounts associated with Touch ID on the device.

    In this example, the user’s full name and email address appear. The Scripted Decision node gathered them during registration.

  4. Select the account to sign in.

    The UI displays the user profile page without you having to enter your username or password.

Configure WebAuthn trust anchors

AM 7 added support for a new CA attestation type, whereby the attestation data received from a device can be verified as authentic by using the relevant CA certificates.

If the trust chains defined by the CA certificates have CRL or OCSP entries, AM is also able to check for revocation.

To configure trust anchors in AM, you should obtain the CA-issued certificate chains for the devices you intend to verify, and make them available to AM in a secret store.

When the relevant certificate chains are in place, configure the WebAuthn Registration node with the alias of the secret store, and set Preferred mode of attestation to either DIRECT or INDIRECT.

Perform the following steps to enable trust anchors and achieve CA attestation for trusted devices:

  1. Obtain the CA-issued certificate chains for the devices you want to verify.

    You may need to consult the device manufacturer to obtain the certificate chains.

  2. Import the certificate chains into a keystore:

    $ keytool -import \
  -file /Downloads/vendor-a-ca.crt \
  -alias "vendor-a-devices" \
  -storetype JCEKS \
  -storepass changeit \
  -keystore /path/to/openam/security/keystores/webauthnTrustStore.jceks

    The command above imports a hypothetical trust chain from "Vendor A" into a secret store named webauthnTrustStore.jceks, located in the default AM path for keystores, /path/to/openam/security/keystores.

    If the keystore does not exist, the command creates it and sets the store password to changeit; otherwise, it adds the specified certificate to the secret store.

  3. Repeat the previous step until the webauthnTrustStore.jceks secret store contains all of the CA-issued certificate chains for the devices you want to verify.

  4. Ensure that the password to access the new webauthnTrustStore.jceks secret store is available to your AM instance; for example, by encrypting the password and adding the result to a new file named webauthnStorepass, in /path/to/openam/security/secrets/encrypted.

    For more information, see File System Secret Volumes Secret Stores.

  5. In the AM admin UI, go to the realm containing the web authentication registration tree that will attempt CA-level attestation, go to Authentication > Trees, and click your registration tree.

  6. Select the WebAuthn Registration Node, and in the properties pane:

    • Set the Preferred mode of attestation property to DIRECT or INDIRECT.

    • Set the Trust Store alias property to a string that identifies the trust store, and is the suffix of the secret label used for mappings; for example, webauthnTrustStore.

    • To act upon the attestation type achieved when registering a device; for example, using a script, enable the Store data in transient state property.

      When you enable this property, the WebAuthn Registration Node stores the level of attestation achieved in a variable named webauthnAttestationType, in the tree’s transient state.

      Use code similar to the following JavaScript to read the value of webauthnAttestationType:

      var attestationLevel = transientState.get("webauthnAttestationType");

    • Save your changes.

      For more information on the available properties, see WebAuthn Registration node.

  7. Navigate back to the realm page, select Secret Stores, and click Add Secret Store.

  8. In Secret Store ID, enter the alias you specified in the registration node earlier; for example, webauthnTrustStore.

    Select the store type, specify the path to the store, and click Create.

    Adding a WebAuthn trust store to a realm.

  9. Set the Store password secret label to the name of the file you created earlier with the encrypted value of the store password in; for example, webauthnStorepass.

    Save your changes.

  10. On the Mappings tab, click Add Mapping.

  11. In Secret Label, select the secret label that begins with am.authentication.nodes.webauthn.truststore, and has the alias you specified earlier as the suffix.

    For example, am.authentication.nodes.webauthn.truststore.webauthnTrustStore.

  12. Enter the alias of the certificate chains you want to use for verification, and click Add.

    Repeat this step to add all the aliases of certificate chains you want to use for CA-level attestation:

    Adding a WebAuthn trust store mapping.

  13. Save your changes.

    Your registration tree is now ready to verify the attestation data against the list of configured certificate chains.