Why

We require support for the Webauthn protocol in our Woo, WordPress and Jetpack apps. This PR introduces integration with the FluxC Webauthn events and calls in order to successfully login using a Security Key.

How

The Webauthn authentication happens in three steps.

First Step

When we submit the user WordPress.com e-mail and password to FluxC, instead of only expecting the bearer token availability, a 2FA error, or a generic error, we now shall also expect the OnSecurityKeyAuthStarted event. If this event is triggered, FluxC signals that we should open the 2FA scenario with the Security Key option. The nonce provided by FluxC shall also be used not only for the Security key, but for the standard 2FA code authentication too.

When the WPLogin receives this event, it will trigger the needs2faSecurityKey function from the LoginListener interface, with the following parameters:

String email
String password 
String userId
String webauthnNonce

The client app should override the needs2faSecurityKey function by calling the Login2FAFragment from the LoginActivity. You can check this implementation from the Woo scenario at https://github.com/woocommerce/woocommerce-android/pull/9988. Here's the example:

override fun needs2faSecurityKey(email: String?, password: String?, userId: String?, webauthnNonce: String?) {
    val login2FaFragment = Login2FaFragment.newInstanceSecurityKey(email, password, userId, webauthnNonce)
    changeFragment(login2FaFragment, true, Login2FaFragment.TAG)
}

The Login2FAFragment is now updated to be started with those parameters. When this happens, the fragment will start offering the Use a security key button in the UI.

Second Step

Suppose the user handles the 2FA step by hitting the use a security key button. In that case, the WPLogin requests FluxC a Security Key challenge so we can verify if the current device contains a Security Key registered with that WordPress.com account.

FluxC will return the challenge data through the WebauthnChallengeReceived. This data is what we need to communicate with the Android SDK FIDO2 API, which will retrieve the Security Key if the user previously registered one with that device. If yes, the security key data will be returned by the FIDO2 API through an Activity Result response, and we move to the third step triggering the FinishWebauthnChallengePayload payload with the Security Key data.

Third and Final step

If FluxC successfully validates the Security Key data with the WordPress.com auth API, it will return the WebauthnPasskeyAuthenticated event, which allow us to finish the login and move forward from the Login2faFragment.

This is all coded to the spec defined in pe5pgL-3Nh-p2

Testing

Testing this code requires multiple setup steps in your app. It is only viable through the https://github.com/wordpress-mobile/WordPress-FluxC-Android/pull/2874 PR alongside your client app (Woo/WordPress/Jetpack) integrated with FluxC. Update both the FluxC and WPLogin in your client app and follow the instructions described in to configure everything.

For the Woo app case, the implementation is available in https://github.com/woocommerce/woocommerce-android/pull/9988.

Steps

1. Security Key initial setup

Login in your WordPress.com account in the device browser (use a personal one, not your A8C account), go to the Profile menu > Security > Two-steps Authentication and scroll to the Security Key section, add a Security Key with your device there.

Demo:

https://github.com/wordpress-mobile/WordPress-FluxC-Android/assets/5920403/a72d2457-fc8e-4059-b67f-b9ff11b882ac

2. Client app login steps

Launch the login app from your client app using this WPLogin version alongside the https://github.com/wordpress-mobile/WordPress-FluxC-Android/pull/2874 version.
Continue with user name/password with a non-A8C email.
See that the two-factor screen presents a "Use a security key" CTA
Select that option and select your passkey stored in the Android credentials.
See that you are correctly authenticated.

⚠️ THE SECURITY KEY AUTH WON'T WORK IN EMULATORS, A REAL DEVICE IS REQUIRED ⚠️ # 2 LOGIN WITH GOOGLE NOT AVAILABLE WITH SECURITY KEYS YET, WILL BE AVAILABLE IN THE UPCOMING PRS

[] Please check here if your pull request includes additional test coverage.
[x] I have considered if this change warrants release notes and have added them to the appropriate section in the CHANGELOG.md if necessary.

wordpress-mobile / WordPress-Login-Flow-Android

[Passkey] Add Security Key auth support #123

Why

How