Passkeys

Browse the sample

This article describes how you can use the .NET Multi-platform App UI (.NET MAUI) IPasskeys interface to register and sign in with passkeys. A passkey is a WebAuthn/FIDO2 public-key credential that replaces a password with a key pair whose private key is managed by the platform authenticator and is never exposed to your app or to .NET MAUI. Signing in is completed by that authenticator, such as Face ID, Touch ID, Windows Hello, or an Android biometric prompt backed by the device's credential manager.

The default implementation of the IPasskeys interface is available through the Passkeys.Default property. Both the IPasskeys interface and the Passkeys class are contained in the Microsoft.Maui.Authentication namespace.

How the passkey flow works

The Passkeys API is deliberately thin. It brokers between your relying party (RP) server and the operating system's authenticator, and it performs no verification of its own:

1. Your app asks your RP server to begin a ceremony. The server returns standard WebAuthn options JSON.
2. Your app passes that JSON to Passkeys.CreateAsync or Passkeys.AssertAsync, which drives the native credential UI.
3. The API returns the standard WebAuthn response JSON produced by the authenticator.
4. Your app posts that response JSON back to your RP server, which verifies it and stores the credential or establishes the session.

Because the contract is WebAuthn JSON in and WebAuthn JSON out, it interoperates directly with existing server libraries, including the built-in passkey support in ASP.NET Core Identity. For more information, see Enable Web Authentication API (WebAuthn) passkeys.

Security boundary

The client never validates a passkey. Understanding this split is essential before you ship a passkey flow:

The private key is created and held by the platform authenticator, in secure hardware where available, and is never exposed to your app or to .NET MAUI. The API only relays the public attestation and assertion material.

Origin binding

Browsers supply the WebAuthn origin from the current page. A native app has no page, so each platform derives the origin from the app's verified identity and writes it into the client data that your server validates:

Your RP server must be configured to accept the app's native origin in addition to any web origin it already accepts. An unconfigured native origin is a common cause of a ceremony that completes on the device but fails verification on the server.

Supported platforms

Call Passkeys.IsSupported before you present passkey UI, and fall back to your existing sign-in method when it returns false.

On Android, iOS, Mac Catalyst, and Windows versions below the minimum shown, IsSupported returns false and both CreateAsync and AssertAsync throw a FeatureNotSupportedException. On targets with no passkey implementation, such as netstandard, tvOS, and Tizen, IsSupported returns false and the methods throw NotImplementedInReferenceAssemblyException, which derives from NotImplementedException.

IsSupported reflects only the platform and OS version. Other runtime prerequisites, such as a configured credential provider or an enrolled biometric, aren't checked by IsSupported and instead surface when a ceremony runs.

Get started

To use passkeys, the following platform-specific setup is required. Passkeys are scoped to an RP domain. Apple and Android fetch a domain association file over HTTPS, so those platforms require a publicly reachable HTTPS domain that hosts your RP server; localhost isn't sufficient. Windows uses the HTTPS RP origin directly and requires no association file.

[
  {
    "relation": ["delegate_permission/common.get_login_creds"],
    "target": {
      "namespace": "android_app",
      "package_name": "com.example.myapp",
      "sha256_cert_fingerprints": [
        "AA:BB:CC:DD:..."
      ]
    }
  }
]

keytool -list -v -keystore <path-to-debug.keystore> -alias androiddebugkey -storepass android -keypass android

<key>com.apple.developer.associated-domains</key>
<array>
  <string>webcredentials:myapp.example.com</string>
</array>

{
  "webcredentials": {
    "apps": ["ABCDE12345.com.example.myapp"]
  }
}

curl -i https://myapp.example.com/.well-known/apple-app-site-association

Register a passkey

Registration creates a new credential. Ask your server to begin the ceremony, pass the returned PublicKeyCredentialCreationOptions JSON to Passkeys.CreateAsync, and post the resulting response JSON back to your server:

using System.Text;
using Microsoft.Maui.Authentication;

if (!Passkeys.IsSupported)
{
    // Fall back to your existing sign-in method.
    return;
}

// 1. Ask your server to begin registration. It returns PublicKeyCredentialCreationOptions JSON.
using HttpResponseMessage beginResponse =
    await httpClient.PostAsync("/passkeys/register/begin", content: null);
beginResponse.EnsureSuccessStatusCode();
string creationOptionsJson = await beginResponse.Content.ReadAsStringAsync();

// 2. Drive the native create-credential UI.
PasskeyCreationResponse created = await Passkeys.CreateAsync(creationOptionsJson);

// 3. Post the response JSON back to your server to verify attestation and store the public key.
using var body = new StringContent(created.ToString(), Encoding.UTF8, "application/json");
using HttpResponseMessage finishResponse =
    await httpClient.PostAsync("/passkeys/register/finish", body);
finishResponse.EnsureSuccessStatusCode();

// Optional: store the credential ID so you can reference this passkey later.
string credentialId = created.Id;

Sign in with a passkey

Authentication proves possession of an existing credential. The shape mirrors registration, using PublicKeyCredentialRequestOptions and Passkeys.AssertAsync:

using System.Text;
using Microsoft.Maui.Authentication;

if (!Passkeys.IsSupported)
{
    // Fall back to your existing sign-in method.
    return;
}

// 1. Ask your server to begin sign-in. It returns PublicKeyCredentialRequestOptions JSON.
using HttpResponseMessage beginResponse =
    await httpClient.PostAsync("/passkeys/login/begin", content: null);
beginResponse.EnsureSuccessStatusCode();
string requestOptionsJson = await beginResponse.Content.ReadAsStringAsync();

// 2. Drive the native get-credential UI so the user selects a passkey and authenticates.
PasskeyAssertionResponse asserted = await Passkeys.AssertAsync(requestOptionsJson);

// 3. Post the response JSON back to your server to verify the signature and finish sign-in.
using var body = new StringContent(asserted.ToString(), Encoding.UTF8, "application/json");
using HttpResponseMessage finishResponse =
    await httpClient.PostAsync("/passkeys/login/finish", body);
finishResponse.EnsureSuccessStatusCode();

// Optional: fields that are commonly read on the device.
string credentialId = asserted.Id;        // Which passkey was used, base64url.
string? userHandle = asserted.UserHandle; // The RP's user.id, when the authenticator returns one.

Configure the ceremony

Most WebAuthn configuration travels inside the options JSON that your server produces, so you set it server-side rather than through the .NET MAUI API. This includes authenticatorSelection.userVerification, authenticatorSelection.authenticatorAttachment, authenticatorSelection.residentKey, timeout, excludeCredentials, allowCredentials, attestation, and extensions. New WebAuthn fields can therefore be supplied without a .NET API change, although the resulting behavior depends on each platform's native support. Android passes the JSON through unchanged, while iOS, Mac Catalyst, and Windows map the subset the OS supports and ignore the rest.

Two behaviors can't be expressed in the options JSON, and are surfaced by the API instead.

Prefer immediately available credentials

PreferImmediatelyAvailable is a presentation choice that keeps the ceremony on the current device and skips the cross-device flow, such as a QR code or "use another device":

var options = new PasskeyRequestOptions(requestOptionsJson)
{
    PreferImmediatelyAvailable = true
};

PasskeyAssertionResponse asserted = await Passkeys.AssertAsync(options);

This setting is most useful for sign-in, but the platforms report a missing credential differently:

• On Android, sign-in with no immediately available credential fails with an InvalidOperationException, so you can distinguish it from cancellation.
• On iOS and Mac Catalyst, the same situation is reported by the OS as ASAuthorizationError.Canceled, the same error Apple returns when the user dismisses the sheet. It therefore surfaces as a cancellation, and your app can't tell "there was no passkey to use" apart from "the user dismissed the prompt."
• Windows ignores the setting entirely and always shows the Security dialog.

Because of the Apple behavior, don't rely on a cancellation to mean the user made a deliberate choice. See Handle errors for recovery guidance that works on every platform.

Cancellation

Both methods accept a CancellationToken so you can abort an in-flight ceremony, for example when the user navigates away or your own timeout elapses:

using var cts = new CancellationTokenSource(TimeSpan.FromMinutes(2));

try
{
    PasskeyAssertionResponse asserted =
        await Passkeys.AssertAsync(requestOptionsJson, cts.Token);
}
catch (OperationCanceledException)
{
    // The ceremony was cancelled by the user or by the token — and on iOS and
    // Mac Catalyst, this also covers "no passkey was available". See Handle errors.
}

Handle errors

Failures surface as standard .NET exceptions rather than a passkey-specific exception type:

Always catch OperationCanceledException rather than TaskCanceledException. Cancellation usually surfaces as the TaskCanceledException subtype, which matches the behavior of WebAuthenticator, but iOS, Mac Catalyst, and Windows check the token before starting the native ceremony and throw the base OperationCanceledException when cancellation is observed at that point. Catching the base type covers every cancellation path on every platform.

try
{
    PasskeyAssertionResponse asserted = await Passkeys.AssertAsync(requestOptionsJson);
    // Post asserted.ToString() to your server.
}
catch (FeatureNotSupportedException)
{
    // Passkeys aren't available on this device. Offer another sign-in method.
}
catch (OperationCanceledException)
{
    // The user dismissed the prompt, or — on iOS and Mac Catalyst — no passkey
    // was available. These are indistinguishable on Apple platforms, so return
    // to the sign-in screen with other options still reachable rather than
    // assuming the user deliberately declined.
}
catch (InvalidOperationException ex)
{
    // On Android: no credential was available, or the ceremony failed.
    // On other platforms: the ceremony failed.
    // ex.Message carries the platform error, which is useful in logs but not to end users.
    logger.LogWarning(ex, "Passkey assertion failed.");
}

Production considerations

• Always verify server-side. Generate every challenge on the server, use it once, and validate the challenge, RP ID, origin, attestation, and assertion before you establish a session.
• Accept the native origins. Configure your RP server to accept the Android android:apk-key-hash: origin and the Apple associated-domain origin for every build you ship, including each signing certificate you use. Debug and release builds have different Android fingerprints.
• Keep a fallback. IsSupported is false on older OS versions and on platforms without passkey support, and a user can decline the prompt. Never make a passkey the only way into an account.
• Support multiple credentials per account. Users sign in from more than one device, and passkeys don't always sync across ecosystems. Let a signed-in user register additional passkeys, list them, and revoke them.
• Use a stable RP ID. The RP ID is baked into every credential. Changing it invalidates every passkey your users have registered.
• Don't authenticate native API calls with cookies. The reference sample uses a cookie for brevity. A production native app should exchange a verified assertion for a token that's appropriate for your API.

Troubleshooting

See also

• Passkeys sample
• Web authenticator
• Enable Web Authentication API (WebAuthn) passkeys
• Web Authentication: An API for accessing Public Key Credentials Level 3
• Passkeys on fidoalliance.org
• Sign in your user with Credential Manager on developer.android.com
• Supporting passkeys on developer.apple.com
• WebAuthn API

The Passkeys API is available starting in .NET MAUI 11. For earlier versions, use Web authenticator for browser-based authentication flows, or call each platform's passkey API directly. For more information about invoking platform APIs, see Invoke platform code.