feat: Adds passkey login support (#848)

Author: NandanPrabhu

auth0_flutter/EXAMPLES.md

@@ -35,6 +35,7 @@
   - [Retrieve stored credentials](#retrieve-stored-credentials-1)
 - [📱 Authentication API](#-authentication-api)
   - [Login with database connection](#login-with-database-connection)
+  - [Log in with passkeys](#log-in-with-passkeys)
   - [Sign up with database connection](#sign-up-with-database-connection)
   - [Passwordless Login](#passwordless-login)
   - [Retrieve user information](#retrieve-user-information)
@@ -1031,6 +1032,7 @@ final credentials = await auth0Web.credentials();
 > This feature is mobile/macOS only; the [SPA SDK](https://github.com/auth0/auth0-spa-js) used by auth0_flutter does not include an API client.
 
 - [Login with database connection](#login-with-database-connection)
+- [Log in with passkeys](#log-in-with-passkeys)
 - [Sign up with database connection](#sign-up-with-database-connection)
 - [Retrieve user information](#retrieve-user-information)
 - [Renew credentials](#renew-credentials)
@@ -1088,6 +1090,67 @@ final credentials = await auth0.api.login(
 
 </details>
 
+### Log in with passkeys
+
+> This feature is available on **iOS 16.6+** and **Android 9+ (API 28)** only.
+
+[Passkeys](https://auth0.com/docs/authenticate/database-connections/passkeys) let an existing user log in with a biometric or device PIN instead of a password, using the platform authenticator (Face ID / Touch ID on iOS, the Credential Manager on Android).
+
+> ⚠️ Passkeys require additional configuration on both your Auth0 tenant and your app:
+> - Set up a [custom domain](https://auth0.com/docs/customize/custom-domains) for your tenant. Passkeys will **not** work without one, since the relying-party domain must be a domain you own and can host the associated domain / Digital Asset Links file on.
+> - Enable passkeys for your database connection and the **Passkey** grant type for your application. See [Configure passkeys](https://auth0.com/docs/authenticate/database-connections/passkeys/configure-passkeys).
+> - Configure the [associated domain (iOS/macOS)](README.md#iosmacos-configure-the-associated-domain) and the equivalent [Digital Asset Links file](https://developer.android.com/identity/sign-in/credential-manager#add-support-dal) (Android) so the OS associates your app with the relying-party domain.
+
+The SDK exposes **two** methods for passkey login — `passkeyLoginChallenge` and `passkeyLogin` — and leaves presenting the OS passkey UI to your app. The flow is:
+
+1. Request a login challenge from Auth0 with `passkeyLoginChallenge`.
+2. **In your app**, present the platform authenticator using that challenge and obtain a WebAuthn assertion. The SDK does **not** do this step — call the OS APIs directly (for example, [`ASAuthorizationController`](https://developer.apple.com/documentation/authenticationservices/asauthorizationcontroller) on iOS/macOS or [Credential Manager](https://developer.android.com/identity/sign-in/credential-manager) on Android, typically over your own platform channel), then map the result into a `PasskeyLoginCredential`.
+3. Exchange that credential for Auth0 tokens with `passkeyLogin`.
+
+```dart
+// 1. Request a login challenge from Auth0.
+final challenge = await auth0.api.passkeyLoginChallenge(
+    connection: 'Username-Password-Authentication');
+
+// 2. Present the OS passkey UI in your app (not provided by the SDK) using
+//    `challenge.authParamsPublicKey`, then build a PasskeyLoginCredential from
+//    the resulting WebAuthn assertion. All values are base64url-encoded.
+final credential = PasskeyLoginCredential(
+    id: '<base64url credentialId>',
+    rawId: '<base64url credentialId>',
+    type: 'public-key',
+    authenticatorAttachment: 'platform',
+    response: PasskeyAuthenticatorAssertionResponse(
+        clientDataJSON: '<base64url clientDataJSON>',
+        authenticatorData: '<base64url authenticatorData>',
+        signature: '<base64url signature>',
+        userHandle: '<base64url userHandle>'));
+
+// 3. Exchange the credential for Auth0 tokens.
+final credentials = await auth0.api.passkeyLogin(
+    challenge: challenge,
+    credential: credential,
+    connection: 'Username-Password-Authentication');
+
+// Store the credentials afterward
+final didStore =
+    await auth0.credentialsManager.storeCredentials(credentials);
+```
+
+<details>
+  <summary>Add an audience and scope values</summary>
+
+```dart
+final credentials = await auth0.api.passkeyLogin(
+    challenge: challenge,
+    credential: credential,
+    connection: 'Username-Password-Authentication',
+    audience: 'YOUR_AUTH0_API_IDENTIFIER',
+    scopes: {'profile', 'email', 'offline_access', 'read:todos'});
+```
+
+</details>
+
 ### Sign up with database connection
 
 ```dart

auth0_flutter/README.md

@@ -586,6 +586,7 @@ void dispose() {
 - [Check for stored credentials](EXAMPLES.md#check-for-stored-credentials) - check if the user is already logged in when your app starts up.
 - [Retrieve stored credentials](EXAMPLES.md#retrieve-stored-credentials) - fetch the user's credentials from the storage, automatically renewing them if they have expired.
 - [Retrieve user information](EXAMPLES.md#retrieve-user-information) - fetch the latest user information from the `/userinfo` endpoint.
+- [Log in with passkeys](EXAMPLES.md#log-in-with-passkeys) - authenticate an existing user with a passkey using the platform authenticator (iOS/Android only).
 - [Native to Web SSO](EXAMPLES.md#native-to-web-sso) - obtain a session transfer token to authenticate a WebView without re-prompting the user.
 - [Handle Android process death](#android-handle-process-death-during-login) - recover credentials when the OS kills your app during login.
 

auth0_flutter/android/build.gradle

@@ -74,6 +74,7 @@ android {
 dependencies {
     implementation "org.jetbrains.kotlin:kotlin-stdlib-jdk8:$kotlin_version"
     implementation 'com.auth0.android:auth0:3.18.0'
+    implementation 'com.google.code.gson:gson:2.10.1'
     testImplementation 'junit:junit:4.13.2'
     testImplementation 'org.hamcrest:java-hamcrest:2.0.0.0'
     testImplementation "org.mockito.kotlin:mockito-kotlin:4.1.0"

auth0_flutter/android/src/main/kotlin/com/auth0/auth0_flutter/Auth0FlutterAuthMethodCallHandler.kt

@@ -14,14 +14,14 @@ class Auth0FlutterAuthMethodCallHandler(
     private val apiRequestHandlers: List<ApiRequestHandler>
 ) : MethodCallHandler {
     lateinit var context: Context
-    
+
     override fun onMethodCall(@NonNull call: MethodCall, @NonNull result: Result) {
         val request = MethodCallRequest.fromCall(call)
-        
+
         val apiHandler = apiRequestHandlers.find { it.method == call.method }
         if (apiHandler != null) {
             val api = AuthenticationAPIClient(request.account)
-            
+
             val useDPoP = request.data["useDPoP"] as? Boolean ?: false
             if (useDPoP) {
                 api.useDPoP(context)

auth0_flutter/android/src/main/kotlin/com/auth0/auth0_flutter/Auth0FlutterPlugin.kt

@@ -133,7 +133,9 @@ class Auth0FlutterPlugin: FlutterPlugin, MethodCallHandler, ActivityAware {
         RenewApiRequestHandler(),
         CustomTokenExchangeApiRequestHandler(),
         SSOExchangeApiRequestHandler(),
-        ResetPasswordApiRequestHandler()
+        ResetPasswordApiRequestHandler(),
+        PasskeyLoginChallengeApiRequestHandler(),
+        PasskeyLoginApiRequestHandler()
       )
     )
     authCallHandler.context = context
@@ -182,6 +184,8 @@ class Auth0FlutterPlugin: FlutterPlugin, MethodCallHandler, ActivityAware {
   }
 
   override fun onDetachedFromActivityForConfigChanges() {
+    webAuthCallHandler.activity = null
+    credentialsManagerCallHandler.activity = null
     WebAuthProvider.removeCallback(processDeathCallback)
   }
 
@@ -192,6 +196,8 @@ class Auth0FlutterPlugin: FlutterPlugin, MethodCallHandler, ActivityAware {
   }
 
   override fun onDetachedFromActivity() {
+    webAuthCallHandler.activity = null
+    credentialsManagerCallHandler.activity = null
     WebAuthProvider.removeCallback(processDeathCallback)
   }
 }

auth0_flutter/android/src/main/kotlin/com/auth0/auth0_flutter/Auth0FlutterWebAuthMethodCallHandler.kt

@@ -9,15 +9,17 @@ import io.flutter.plugin.common.MethodChannel.MethodCallHandler
 import io.flutter.plugin.common.MethodChannel.Result
 
 class Auth0FlutterWebAuthMethodCallHandler(private val requestHandlers: List<WebAuthRequestHandler>) : MethodCallHandler {
-    lateinit var activity: Activity
+    // Null while the plugin is detached from an Activity (see ActivityAware
+    // callbacks in Auth0FlutterPlugin).
+    var activity: Activity? = null
 
     override fun onMethodCall(@NonNull call: MethodCall, @NonNull result: Result) {
         val requestHandler = requestHandlers.find { it.method == call.method }
 
         if (requestHandler != null) {
             val request = MethodCallRequest.fromCall(call)
 
-            requestHandler.handle(activity, request, result)
+            requestHandler.handle(activity!!, request, result)
         } else {
             result.notImplemented()
         }

auth0_flutter/android/src/main/kotlin/com/auth0/auth0_flutter/CredentialsManagerMethodCallHandler.kt

@@ -27,7 +27,10 @@ private object BiometricAuthLevel {
 }
 
 class CredentialsManagerMethodCallHandler(private val requestHandlers: List<CredentialsManagerRequestHandler>) : MethodCallHandler {
-    lateinit var activity: Activity
+    // Null while the plugin is detached from an Activity (see ActivityAware
+    // callbacks in Auth0FlutterPlugin). Only required for biometric/local
+    // authentication, which needs a FragmentActivity.
+    var activity: Activity? = null
     lateinit var context: Context
 
     private data class ManagerCacheKey(

auth0_flutter/android/src/main/kotlin/com/auth0/auth0_flutter/request_handlers/api/PasskeyLoginApiRequestHandler.kt

@@ -0,0 +1,93 @@
+package com.auth0.auth0_flutter.request_handlers.api
+
+import com.auth0.android.authentication.AuthenticationAPIClient
+import com.auth0.android.authentication.AuthenticationException
+import com.auth0.android.callback.Callback
+import com.auth0.android.result.Credentials
+import com.auth0.auth0_flutter.request_handlers.MethodCallRequest
+import com.auth0.auth0_flutter.toMap
+import com.auth0.auth0_flutter.utils.assertHasProperties
+import com.google.gson.Gson
+import io.flutter.plugin.common.MethodChannel
+
+private const val AUTH_PASSKEY_LOGIN_METHOD = "auth#passkeyLogin"
+
+/**
+ * Exchanges a passkey credential (presented by the app) and a login challenge
+ * for Auth0 tokens by calling the `/oauth/token` endpoint. This handler does
+ * not present any UI.
+ */
+class PasskeyLoginApiRequestHandler : ApiRequestHandler {
+    override val method: String = AUTH_PASSKEY_LOGIN_METHOD
+
+    private val gson = Gson()
+
+    override fun handle(
+        api: AuthenticationAPIClient,
+        request: MethodCallRequest,
+        result: MethodChannel.Result
+    ) {
+        val args = request.data
+
+        assertHasProperties(listOf("challenge.authSession", "credential"), args)
+
+        val authSession = (args["challenge"] as Map<*, *>)["authSession"] as String
+        val credentialMap = args["credential"] as Map<*, *>
+
+        val connection = args["connection"] as? String
+        val organization = args["organization"] as? String
+        val audience = args["audience"] as? String
+        val scopes = (args["scopes"] as? List<*>)?.filterIsInstance<String>()?.joinToString(" ") ?: ""
+        val parameters = (args["parameters"] as? Map<*, *>)?.mapKeys { it.key.toString() }
+            ?.mapValues { it.value.toString() } ?: emptyMap()
+
+        // signinWithPasskey accepts the WebAuthn authentication response as a
+        // JSON string in the standard format produced by the create-credential
+        // step.
+        val authResponseJson = gson.toJson(credentialMap)
+
+        val loginBuilder = api.signinWithPasskey(
+            authSession,
+            authResponseJson,
+            connection,
+            organization
+        )
+            .validateClaims()
+
+        if (scopes.isNotEmpty()) {
+            loginBuilder.setScope(scopes)
+        }
+        if (audience != null) {
+            loginBuilder.setAudience(audience)
+        }
+        if (parameters.isNotEmpty()) {
+            loginBuilder.addParameters(parameters)
+        }
+
+        loginBuilder.start(object : Callback<Credentials, AuthenticationException> {
+            override fun onFailure(exception: AuthenticationException) {
+                result.error(
+                    exception.getCode(),
+                    exception.getDescription(),
+                    exception.toMap()
+                )
+            }
+
+            override fun onSuccess(credentials: Credentials) {
+                val scope = credentials.scope?.split(" ") ?: listOf()
+                val formattedDate = credentials.expiresAt.toInstant().toString()
+                result.success(
+                    mapOf(
+                        "accessToken" to credentials.accessToken,
+                        "idToken" to credentials.idToken,
+                        "refreshToken" to credentials.refreshToken,
+                        "userProfile" to credentials.user.toMap(),
+                        "expiresAt" to formattedDate,
+                        "scopes" to scope,
+                        "tokenType" to credentials.type
+                    )
+                )
+            }
+        })
+    }
+}

auth0_flutter/android/src/main/kotlin/com/auth0/auth0_flutter/request_handlers/api/PasskeyLoginChallengeApiRequestHandler.kt

@@ -0,0 +1,51 @@
+package com.auth0.auth0_flutter.request_handlers.api
+
+import com.auth0.android.authentication.AuthenticationAPIClient
+import com.auth0.android.authentication.AuthenticationException
+import com.auth0.android.callback.Callback
+import com.auth0.android.result.PasskeyChallenge
+import com.auth0.auth0_flutter.request_handlers.MethodCallRequest
+import com.auth0.auth0_flutter.toMap
+import io.flutter.plugin.common.MethodChannel
+
+private const val AUTH_PASSKEY_LOGIN_CHALLENGE_METHOD = "auth#passkeyLoginChallenge"
+
+class PasskeyLoginChallengeApiRequestHandler : ApiRequestHandler {
+    override val method: String = AUTH_PASSKEY_LOGIN_CHALLENGE_METHOD
+
+    override fun handle(
+        api: AuthenticationAPIClient,
+        request: MethodCallRequest,
+        result: MethodChannel.Result
+    ) {
+        val args = request.data
+        val connection = args["connection"] as? String
+        val organization = args["organization"] as? String
+
+        api.passkeyChallenge(connection, organization)
+            .start(object : Callback<PasskeyChallenge, AuthenticationException> {
+                override fun onFailure(exception: AuthenticationException) {
+                    result.error(
+                        exception.getCode(),
+                        exception.getDescription(),
+                        exception.toMap()
+                    )
+                }
+
+                override fun onSuccess(challenge: PasskeyChallenge) {
+                    val authParamsPublicKey = mapOf(
+                        "challenge" to challenge.authParamsPublicKey.challenge,
+                        "rpId" to challenge.authParamsPublicKey.rpId,
+                        "timeout" to challenge.authParamsPublicKey.timeout,
+                        "userVerification" to challenge.authParamsPublicKey.userVerification
+                    )
+                    result.success(
+                        mapOf(
+                            "authSession" to challenge.authSession,
+                            "authParamsPublicKey" to authParamsPublicKey
+                        )
+                    )
+                }
+            })
+    }
+}