Passkeys

The Passkeys authenticator enables strong, public key-based credentials for user authentication. Passkeys are WebAuthn credentials that require user verification and are available across different contexts/devices. Authenticating using a Passkey usually requires a user to perform a biometric gesture in the device or enter a device’s PIN. The Passkeys specification refers to an authentication device as authenticator. An authenticator has a different meaning in the Curity Identity Server, and thus we use the word device.

Configuring a Passkeys authenticator

When creating a Passkeys authenticator, there are some configuration options that can be used.

  • allow-registration-during-login
    • Toggle to enable registration for the authenticator. If disabled, none of the registration possibilities will be available, and the authenticator device will have to be registered out of band.
  • account-manager
    • An account manager holding the accounts that have the devices, and if registration is allowed, where to store new devices.
  • enable-discoverable-credentials
    • Toggle to enable user authentication without explicitly providing the username, relying on credentials known to the browser or operating system.

Registering devices

When allowing for a device registration for this authenticator, a prerequisite authenticator is mandatory to configure. This prerequisite authenticator is used to establish a subject by which to lookup an account using the configured Account Manager.

Hypermedia Authentication API

The Passkeys authenticator supports the Hypermedia Authentication API on iOS devices. HAAPI model utilises the following two client-operation - webauthn-registration and webauthn-authentication. Android and web clients should utilize the fallback mechanism triggering an external browser flow in the form of an error action.

Discoverable Credentials

When Discoverable Credentials are enabled, the username prompt is omitted during the authentication flow and instead the browser presents to the user a list of known credentials or displays a QR code to be used with credentials stored on a mobile device. Use of discoverable credentials requires a database structure update, please refer to the product’s upgrade guides for details.

iOS Domain Association

The iOS domain association allows for the creation of a connection between the Identity Server and mobile application for passkey generation. To serve the apple-app-site-association (association) file from Identity Server, application details need to be configured in environments/environment/service/zones/{appropriate zone}/mobile-app-association/ios-app-configuration. Alternatively the file can be placed in dist/usr/share/webroot/.well-known/ directory.

Android Domain Association

The Android domain association allows for the creation of a connection between Identity Server and android application for WebAuthn key generation. To serve the assetlinks.json file from Identity Server, application details needs to be configured in environments/environment/service/zones/{appropriate zone}/mobile-app-association/android-app-configuration alternatively the file can be placed in $IDSVR_HOME/usr/share/webroot/.well-known/ directory and file generation disabled by configuring environment/services/service-role/<service-role>/disable-android-assetlinks-generation.

Known limitations

The following limitations are known about the Passkeys authenticator

  • Native HAAPI support is limited to iOS and Android clients. Web clients are currently not supported using HAAPI, and should use the external browser flow as a fallback mechanism.