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
- WSO2 Identity Server 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¶
-
To get started, you need to register an application with WSO2 Identity Server. You can register your own application or use one of the sample applications provided.
-
You need to have a user account in WSO2 Identity Server. If you don't already have one, create a user account in WSO2 Identity Server.
Enable passkey login¶
Follow the steps given below to enable login with passkeys for your application.
-
On the WSO2 Identity Server Console, go to Applications.
-
Select the application to which you wish to add passkey login.
-
Go to the Login Flow tab of the application and add passkey login as follows:
-
Go to Predefined Flows > Basic Flows > Add Passwordless login.
-
Select Passkey.
-
Click Confirm to add passwordless login with passkey to the sign-in flow.
-
-
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.
-
On the WSO2 Identity Server Console, go to Connections.
-
Select the
Passkey
connection and go to its Settings tab. -
Select the Allow passkey progressive enrollment checkbox.
-
Click Update to save your changes.
-
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 WSO2 Identity Server. Follow the steps given below to configure passkey usernameless authentication for your application.
-
On the WSO2 Identity Server Console, go to Connections.
-
Select the Passkey connection.
-
Go to the Settings tab of the connection.
-
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.
-
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.
-
Access the application URL.
-
Click Login to access the WSO2 Identity Server login page.
-
Select Sign In With Passkey.
-
To enroll a new passkey, enter your username and select Create a passkey.
-
Enter the corresponding password for the user and click Sign In.
-
Follow the instructions given by your browser or device to enroll the passkey.
-
Provide a name to uniquely identify your passkey.
-
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.
-
Navigate to the login page of the application.
-
Click Login to access the WSO2 Identity Server login page.
-
Select Sign In With Passkey.
-
Enter your username and select Continue.
-
Follow the browser/device instructions to log in with a passkey.
Note
During passkey progressive enrollment, if a user wishes to use a federated authenticator, they should have their external accounts already provisioned within WSO2 Identity Server. If, for example, a user logs in with Google using an account not provisioned in WSO2 Identity Server, 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.
By following this guide, you enable WSO2 Identity Server to host details about your applications in the following endpoints:
-
For Android -
https://localhost:9443/.well-known/trusted-apps/android
-
For iOS -
https://localhost:9443/.well-known/trusted-apps/ios
The validation services of iOS and Android require application details to be available at the following URLs on your domain,
- For Android -
{your_domain}/.well-known/assetlinks.json
- For iOS -
{your_domain}/.well-known/apple-app-site-association
Therefore, make sure these paths of your domain are mapped to the corresponding local endpoints of WSO2 Identity Server.
Note
While not a security concern, it is still important to note that details about your applications are publicly accessible through the endpoints.
Due to this behavior, you may configure WSO2 Identity Server to display a consent screen for administrators who are attempting to make an application a FIDO trusted app. To do so, add the following configuration to the deployment.toml
file found in the <IS_HOME>/repository/conf/
directory.
[application_mgt]
trusted_app_consent_required=true
To publish app details to the endpoints,
-
On the WSO2 Identity Server Console, go to Applications and select your application.
-
In its Advanced tab, under Trusted App Settings, select Add as a FIDO trusted app.
-
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)
-
-
Click Update to save the changes.