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 Curity Identity Server, and thus we use the word device.

Use Cases#

The Curity website has some design articles and tutorials that you can use to learn more about ways to use passkeys:

Creating a Passkeys authenticator#

The most common way to get started is to create a Passkeys authenticator in the Admin UI. To do so, navigate to Profiles → Authentication Service → Authenticators and select the + New Authenticator option. Then select the passkeys option to see the following user interface.

Default settings for the passkeys authenticatorDefault settings for the passkeys authenticator

When you edit settings, you can select the View XML option to see a serialized representation of the authenticator’s settings.

 <authenticator>
  <id>passkeys</id>
  <authentication-actions>
    <login>passkeys_claims</login>
  </authentication-actions>
  <description>Sign in with a passkey</description>
  <required-authenticator-for-registration>email</required-authenticator-for-registration>
  <passkeys xmlns="https://curity.se/ns/conf/authenticators/passkeys">
    <allow-registration-during-login>true</allow-registration-during-login>
    <enable-discoverable-credentials>true</enable-discoverable-credentials>
    <account-manager>
      <id>default-account-manager</id>
    </account-manager>
  </passkeys>
</authenticator>

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 details for new devices, like public keys.

  • enable-discoverable-credentials

    • Toggle to enable user authentication without explicitly providing the username, relying on credentials known to the browser or operating system.

  • require-user-to-set-alias

    • Require users to set a device alias every time they register a new device. This may help users to identify their devices later.

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

Was this helpful?