Skip to content

Add Passkey login

Based on FIDO concepts, Passkeys are a replacement for traditional passwords that allows users to log in to applications without a password using the following methods.

  • Roaming authenticators - platform-independant FIDO2-supported hardware security keys such as YubiKey.
  • Platform authenticators - built-in biometrics bound to a single device such as fingerprint scanners or facial recognition features.

Passkeys are phishing resistant and they provide an enhanced user experience as users are not required to manage and remember multiple passwords.

What is FIDO2?

The FIDO Alliance, whose mission is to reduce the world's reliance on passwords, introduced its latest specifications, collectively called FIDO2. FIDO2 specifications are the World Wide Web Consortium's (W3C) Web Authentication specification (WebAuthn) and FIDO alliance's corresponding Client to Authenticator Protocol (CTAP). Learn more about FIDO2.

There are two types of passkeys based on how they are synchronized.

  • Single-Device Passkeys

    These passkeys are bound to a single device and are not meant to be shared across multiple devices. Single-device passkeys are useful if you want to reduce the impact of an attack if the credentials are compromised.

  • Multi-Device Passkeys

    These passkeys enable synchronization across multiple devices allowing users to log into an application from any device, even when their credentials are stored on another.

    Major vendors have already introduced their passkey implementations.

    • Apple users will find their passkeys synced across all devices that are signed into the same Apple ID and iCloud Keychain. Refer to the Apple documentation for more information.

    • Android users will have their passkeys synced across all devices linked to their Google account. Refer to the Google documentation for more information.

    If the devices do not sync through the cloud, a user can generate a QR code in the other device and scan it using the device that stores the passkeys to successfully log into the application.

    Refer to the passkeys documentation to stay up-to-date with the device support for FIDO2 passkeys.

Info

  • Asgardeo uses the WebAuthn API to enable FIDO-based authentication for browsers that no longer support the u2f extension.
  • The following browser versions support the WebAuthn API by default:
    • Chrome 67 and above
    • Firefox 60 and above
    • Edge 17723 and above
  • Passkey login with platform authenticators will NOT work on the Firefox browser in macOS Catalina, Big Sur, and Monterey due to browser limitations.
  • Passkey login with roaming authenticators will NOT work on the Firefox browser as the browser doesn't support CTAP2 (Client to Authenticator Protocol 2) with PIN.

The following guide explains how you can enable log in with passkeys in your application.

Prerequisites

Enable passkey login

Follow the steps given below to enable login with passkeys for your application.

  1. On the Asgardeo Console, go to Applications.

  2. Select the application to which you wish to add passkey login.

  3. Go to the Login Flow tab of the application and add passkey login as follows:

    To add passwordless login with passkey using the Visual Editor:

    1. Go to Predefined Flows > Basic Flows > Add Passwordless login.

    2. Select Passkey.

    3. Click Confirm to add passwordless login with passkey to the sign-in flow.

      Configuring passkey login in Asgardeo using the Visual Editor

    To add passwordless login with passkey using the Classic Editor:

    • Select Add Passkey login from the list if you haven't already built a login flow for the application.

      Configuring Passkey login in Asgardeo

    • If you already have a login flow, click Add authentication > Passkey and click Add for the first authentication step.

      Customize the login flow


  4. Click Update to save your changes.

Enable passkey progressive enrollment

With passkey progressive enrollment, users can enroll their passkeys on the fly when logging in, offering a blend of convenience and security.

Follow the steps given below to enable passkey progressive enrollment for your application.

  1. On the Asgardeo Console, go to Connections.

  2. Select the Passkey connection and go to its Settings tab.

  3. Select the Allow passkey progressive enrollment checkbox.

    Enable passkey progressive enrollment in Asgardeo

  4. Click Update to save your changes.

  5. Add the passkey progressive enrollment adaptive script to the login flow of the application.

Note

  • If progressive enrollment is disabled, users need to pre-register their passkeys from the MyAccount portal. Learn how to do so in Register passkeys.

  • Passkey progressive enrollment can only be configured at the organizational level and cannot be modified at the application level.

Configure passkey usernameless authentication

Usernameless authentication enhances user experience by eliminating the need for users to enter a username during login with passkeys. This is the default behavior in Asgardeo. Follow the steps given below to configure passkey usernameless authentication for your application.

  1. On the Asgardeo Console, go to Connections.

  2. Select the Passkey connection.

  3. Go to the Settings tab of the connection.

  4. Select the Allow passkey usernameless authentication checkbox to enable usernameless authentication.

    Note

    If this option is disabled, users are prompted to enter the username during login with passkeys.

    Enable passkey usernameless authentication in Asgardeo

  5. Click Update to save your changes.

Note

Passkey usernameless authentication can only be configured at the organizational level and cannot be modified at the application level.

Try it out

The following guides let you try out a scenario where, passkey progressive enrollment is enabled and passkey usernameless authentication is disabled.

Enroll a passkey

Follow the steps below to enroll a passkey on the fly during login.

  1. Access the application URL.

  2. Click Login to access the Asgardeo login page.

  3. Select Sign In With Passkey.

    Sign In with passkey login in Asgardeo

  4. To enroll a new passkey, enter your username and select Create a passkey.

    Create a passkey in Asgardeo

  5. Enter the corresponding password for the user and click Sign In.

    Basic authenticator in Asgardeo

  6. Follow the instructions given by your browser or device to enroll the passkey.

    Create a passkey browser prompt in Asgardeo

  7. Provide a name to uniquely identify your passkey.

    Rename passkey in Asgardeo

  8. Click Submit to complete the enrollment. You'll be authenticated in the application.

Sign in with passkey

Follow the steps below to use an enrolled passkey to sign in to an application.

  1. Navigate to the login page of the application.

  2. Click Login to access the Asgardeo login page.

  3. Select Sign In With Passkey.

  4. Enter your username and select Continue.

  5. Follow the browser/device instructions to log in with a passkey.

    Sign In with passkey browser prompt Asgardeo

Note

During passkey progressive enrollment, if a user wishes to use a federated authenticator, they should have their external accounts already provisioned within Asgardeo. If, for example, a user logs in with Google using an account not provisioned in Asgardeo, passkey enrolment results in an error and the login flow fails.

Make application a FIDO trusted app

If you wish to integrate passkeys into a mobile application using app-native authentication, you must validate your application through the validation services provided by the respective platform (iOS or Android). This validation involves associating your application with the identity provider's domain. This association verifies that the authentication requests originate from a legitimate application, protecting against malicious attempts to steal credentials.

To learn how to implement this, follow the relevant guide based on whether you use Asgardeo domains or custom domains in your organization

For Asgardeo domains

It is required by the validation services of iOS and Android to have details about the application exposed in a public URL. As an Asgardeo domain user, this guide explains how you may publish details about your app to one of the following endpoints of Asgardeo based on the platform.

  • For Android - https://asgardeo.io/.well-known/assetlinks.json

  • For iOS - https://asgardeo.io/.well-known/apple-app-site-association

Third-party data exposure

Asgardeo publishes app details to URLs which are common to all organizations. This means your app details will reside together with the app details of other organizations. While this is not a security concern, it is important to note that other organization users may learn details about your applications through these URLs.

If this is not desirable for your use case, you may use custom domains for your organization and publish app details to custom endpoints.

To publish app details to an Asgardeo endpoint,

  1. On the Asgardeo Console, go to Applications and select your application.

  2. In its Advanced tab, under Trusted App Settings, select Add as a FIDO trusted app.

  3. Under Platform Settings, enter the following platform-specific details.

    • For an Android app:

      • Provide the package name of the application which takes the reverse domain format (e.g. com.example.myapp)

      • Provide key hashes, which are SHA256 fingerprints of the app's signing certificate.

    • For an iOS app:

      • Provide the app ID of your application which consists of the team ID and the bundle ID separated by a period (.). (e.g. A1B2C3D4E5.com.domainname.applicationname)
  4. Click Update to save the changes.

For custom domains

It is required by the validation services of iOS and Android to have details about the application exposed in a public URL. As a custom domain user, you are required to facilitate this by hosting details about your mobile applications in the following endpoints.

  • For Android - {custom_domain}/.well-known/assetlinks.json

  • For iOS - {custom_domain}/.well-known/apple-app-site-association

Make sure the data is in the format expected by the validation services of iOS and Android.