feat: add passkey signup support (#849)

Author: NandanPrabhu

.github/workflows/main.yml

@@ -15,7 +15,7 @@ concurrency:
 env:
     ruby: '3.3.1'
     flutter: '3.x'
-    ios-simulator: iPhone 16
+    ios-simulator: iPhone 17
     java: 17
 
 jobs:

auth0_flutter/EXAMPLES.md

@@ -35,8 +35,9 @@
   - [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)
+  - [Log in with passkeys](#log-in-with-passkeys)
+  - [Sign up with passkeys](#sign-up-with-passkeys)
   - [Passwordless Login](#passwordless-login)
   - [Retrieve user information](#retrieve-user-information)
   - [Renew credentials](#renew-credentials)
@@ -1032,8 +1033,9 @@ 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)
+- [Log in with passkeys](#log-in-with-passkeys)
+- [Sign up with passkeys](#sign-up-with-passkeys)
 - [Retrieve user information](#retrieve-user-information)
 - [Renew credentials](#renew-credentials)
 - [API client errors](#api-client-errors)
@@ -1090,6 +1092,18 @@ final credentials = await auth0.api.login(
 
 </details>
 
+### Sign up with database connection
+
+```dart
+final databaseUser = await auth0.api.signup(
+    email: 'jane.smith@example.com',
+    password: 'secret-password',
+    connection: 'Username-Password-Authentication',
+    userMetadata: {'first_name': 'Jane', 'last_name': 'Smith'});
+```
+
+> 💡 You might want to log the user in after signup. See [Login with database connection](#login-with-database-connection) above for an example.
+
 ### Log in with passkeys
 
 > This feature is available on **iOS 16.6+** and **Android 9+ (API 28)** only.
@@ -1101,33 +1115,33 @@ final credentials = await auth0.api.login(
 > - 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:
+The SDK exposes **two** methods for passkey login — `passkeyLoginChallenge` and `passkeyCredentialExchange` — 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`.
+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 `PasskeyCredential`.
+3. Exchange that credential for Auth0 tokens with `passkeyCredentialExchange`.
 
 ```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(
+//    `challenge.authParamsPublicKey`, then build a PasskeyCredential from the
+//    resulting WebAuthn assertion. All values are base64url-encoded.
+final credential = PasskeyCredential(
     id: '<base64url credentialId>',
     rawId: '<base64url credentialId>',
     type: 'public-key',
     authenticatorAttachment: 'platform',
-    response: PasskeyAuthenticatorAssertionResponse(
+    response: PasskeyAuthenticatorResponse(
         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(
+final credentials = await auth0.api.passkeyCredentialExchange(
     challenge: challenge,
     credential: credential,
     connection: 'Username-Password-Authentication');
@@ -1141,7 +1155,7 @@ final didStore =
   <summary>Add an audience and scope values</summary>
 
 ```dart
-final credentials = await auth0.api.passkeyLogin(
+final credentials = await auth0.api.passkeyCredentialExchange(
     challenge: challenge,
     credential: credential,
     connection: 'Username-Password-Authentication',
@@ -1151,17 +1165,72 @@ final credentials = await auth0.api.passkeyLogin(
 
 </details>
 
-### Sign up with database connection
+### Sign up 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 users register 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 signup — `passkeySignupChallenge` and `passkeyCredentialExchange` — and leaves presenting the OS passkey UI to your app. The flow is:
+
+1. Request a registration challenge from Auth0 with `passkeySignupChallenge`.
+2. **In your app**, present the platform authenticator using that challenge and obtain a WebAuthn attestation. 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 `PasskeyCredential`.
+3. Exchange that credential for Auth0 tokens with `passkeyCredentialExchange` — the same method used for login.
+
+You can identify the new user with any combination of `email`, `phoneNumber`, `username`, `name`, `givenName`, `familyName`, `nickname`, and `picture`, depending on how your connection is configured.
 
 ```dart
-final databaseUser = await auth0.api.signup(
+// 1. Request a registration challenge from Auth0. You can identify the new
+//    user with any combination of email, phoneNumber, username, name,
+//    givenName, familyName, nickname, and picture.
+final challenge = await auth0.api.passkeySignupChallenge(
     email: 'jane.smith@example.com',
-    password: 'secret-password',
+    name: 'Jane Smith',
+    givenName: 'Jane',
+    familyName: 'Smith',
+    connection: 'Username-Password-Authentication');
+
+// 2. Present the OS passkey-creation UI in your app (not provided by the SDK)
+//    using `challenge.authParamsPublicKey`, then build a PasskeyCredential from
+//    the resulting WebAuthn attestation. All values are base64url-encoded.
+final credential = PasskeyCredential(
+    id: '<base64url credentialId>',
+    rawId: '<base64url credentialId>',
+    type: 'public-key',
+    authenticatorAttachment: 'platform',
+    response: PasskeyAuthenticatorResponse(
+        clientDataJSON: '<base64url clientDataJSON>',
+        attestationObject: '<base64url attestationObject>'));
+
+// 3. Exchange the credential for Auth0 tokens.
+final credentials = await auth0.api.passkeyCredentialExchange(
+    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.passkeyCredentialExchange(
+    challenge: challenge,
+    credential: credential,
     connection: 'Username-Password-Authentication',
-    userMetadata: {'first_name': 'Jane', 'last_name': 'Smith'});
+    audience: 'YOUR_AUTH0_API_IDENTIFIER',
+    scopes: {'profile', 'email', 'offline_access', 'read:todos'});
 ```
 
-> 💡 You might want to log the user in after signup. See [Login with database connection](#login-with-database-connection) above for an example.
+</details>
 
 ### Passwordless Login
 Passwordless is a two-step authentication flow that requires the **Passwordless OTP** grant to be enabled for your Auth0 application. Check [our documentation](https://auth0.com/docs/get-started/applications/application-grant-types) for more information.

auth0_flutter/README.md

@@ -587,6 +587,7 @@ void dispose() {
 - [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).
+- [Sign up with passkeys](EXAMPLES.md#sign-up-with-passkeys) - register a new 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/src/main/kotlin/com/auth0/auth0_flutter/Auth0FlutterPlugin.kt

@@ -135,7 +135,8 @@ class Auth0FlutterPlugin: FlutterPlugin, MethodCallHandler, ActivityAware {
         SSOExchangeApiRequestHandler(),
         ResetPasswordApiRequestHandler(),
         PasskeyLoginChallengeApiRequestHandler(),
-        PasskeyLoginApiRequestHandler()
+        PasskeySignupChallengeApiRequestHandler(),
+        PasskeyCredentialExchangeApiRequestHandler()
       )
     )
     authCallHandler.context = context

…ers/api/PasskeyLoginApiRequestHandler.kt …eyCredentialExchangeApiRequestHandler.ktauth0_flutter/android/src/main/kotlin/com/auth0/auth0_flutter/request_handlers/api/PasskeyLoginApiRequestHandler.kt renamed to auth0_flutter/android/src/main/kotlin/com/auth0/auth0_flutter/request_handlers/api/PasskeyCredentialExchangeApiRequestHandler.kt auth0_flutter/android/src/main/kotlin/com/auth0/auth0_flutter/request_handlers/api/PasskeyLoginApiRequestHandler.kt renamed to auth0_flutter/android/src/main/kotlin/com/auth0/auth0_flutter/request_handlers/api/PasskeyCredentialExchangeApiRequestHandler.kt

@@ -10,15 +10,20 @@ 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"
+private const val AUTH_PASSKEY_CREDENTIAL_EXCHANGE_METHOD =
+    "auth#passkeyCredentialExchange"
 
 /**
- * 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.
+ * Exchanges an app-supplied passkey credential (a login assertion or a signup
+ * attestation) and its challenge for Auth0 tokens at the `/oauth/token`
+ * endpoint. This handler does not present any UI.
+ *
+ * Both passkey login and signup finish here: Auth0.Android's `signinWithPasskey`
+ * accepts the credential as a JSON string and handles both assertion and
+ * attestation payloads, so a single handler serves both flows.
  */
-class PasskeyLoginApiRequestHandler : ApiRequestHandler {
-    override val method: String = AUTH_PASSKEY_LOGIN_METHOD
+class PasskeyCredentialExchangeApiRequestHandler : ApiRequestHandler {
+    override val method: String = AUTH_PASSKEY_CREDENTIAL_EXCHANGE_METHOD
 
     private val gson = Gson()
 
@@ -37,16 +42,16 @@ class PasskeyLoginApiRequestHandler : ApiRequestHandler {
         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 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.
+        // signinWithPasskey accepts the WebAuthn credential response as a JSON
+        // string in the standard format produced by the platform authenticator.
         val authResponseJson = gson.toJson(credentialMap)
 
-        val loginBuilder = api.signinWithPasskey(
+        val builder = api.signinWithPasskey(
             authSession,
             authResponseJson,
             connection,
@@ -55,16 +60,16 @@ class PasskeyLoginApiRequestHandler : ApiRequestHandler {
             .validateClaims()
 
         if (scopes.isNotEmpty()) {
-            loginBuilder.setScope(scopes)
+            builder.setScope(scopes)
         }
         if (audience != null) {
-            loginBuilder.setAudience(audience)
+            builder.setAudience(audience)
         }
         if (parameters.isNotEmpty()) {
-            loginBuilder.addParameters(parameters)
+            builder.addParameters(parameters)
         }
 
-        loginBuilder.start(object : Callback<Credentials, AuthenticationException> {
+        builder.start(object : Callback<Credentials, AuthenticationException> {
             override fun onFailure(exception: AuthenticationException) {
                 result.error(
                     exception.getCode(),

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

@@ -0,0 +1,68 @@
+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.request.UserData
+import com.auth0.android.result.PasskeyRegistrationChallenge
+import com.auth0.auth0_flutter.request_handlers.MethodCallRequest
+import com.auth0.auth0_flutter.toMap
+import com.google.gson.Gson
+import io.flutter.plugin.common.MethodChannel
+
+private const val AUTH_PASSKEY_SIGNUP_CHALLENGE_METHOD = "auth#passkeySignupChallenge"
+
+class PasskeySignupChallengeApiRequestHandler : ApiRequestHandler {
+    override val method: String = AUTH_PASSKEY_SIGNUP_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
+
+        @Suppress("UNCHECKED_CAST")
+        val userMetadata = args["userMetadata"] as? Map<String, String>
+        val userData = UserData(
+            email = args["email"] as? String,
+            phoneNumber = args["phoneNumber"] as? String,
+            userName = args["username"] as? String,
+            name = args["name"] as? String,
+            givenName = args["givenName"] as? String,
+            familyName = args["familyName"] as? String,
+            nickName = args["nickname"] as? String,
+            picture = args["picture"] as? String,
+            userMetadata = userMetadata
+        )
+
+        api.signupWithPasskey(userData, connection, organization)
+            .start(object : Callback<PasskeyRegistrationChallenge, AuthenticationException> {
+                override fun onFailure(exception: AuthenticationException) {
+                    result.error(
+                        exception.getCode(),
+                        exception.getDescription(),
+                        exception.toMap()
+                    )
+                }
+
+                override fun onSuccess(challenge: PasskeyRegistrationChallenge) {
+                    // Forward the full WebAuthn registration options so the
+                    // create-credential step can pass them to Credential
+                    // Manager's CreatePublicKeyCredentialRequest verbatim.
+                    val authParamsPublicKey: Map<*, *> = Gson().fromJson(
+                        Gson().toJson(challenge.authParamsPublicKey),
+                        Map::class.java
+                    )
+                    result.success(
+                        mapOf(
+                            "authSession" to challenge.authSession,
+                            "authParamsPublicKey" to authParamsPublicKey
+                        )
+                    )
+                }
+            })
+    }
+}