Passkeys (.NET 11): document Microsoft.Maui.Authentication.Passkeys - #3456
Conversation
PoliCheck Scan ReportThe following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans. ✅ No issues foundMore information about PoliCheckInformation: PoliCheck | Severity Guidance | Term |
|
Learn Build status updates of commit f75b0bf: ✅ Validation status: passed
For more details, please refer to the build report. |
There was a problem hiding this comment.
Pull request overview
Adds conceptual documentation for the new .NET MAUI 11 Preview 7 passkeys (WebAuthn/FIDO2) API (Microsoft.Maui.Authentication.Passkeys) and wires it into the docs entry points (what’s new, platform-integration index, and TOC).
Changes:
- Adds a new Passkeys article under Platform integration > Communication with setup guidance, flow overview, and examples.
- Adds a Passkeys entry to the Communication TOC and to the platform-integration index (monikered).
- Updates the .NET MAUI .NET 11 “What’s new” page with a Passkeys section and snippet.
Show a summary per file
| File | Description |
|---|---|
| docs/platform-integration/communication/passkeys.md | New Passkeys conceptual article (monikered) with setup + usage guidance. |
| docs/TOC.yml | Adds Passkeys to the Communication nav. |
| docs/platform-integration/index.md | Adds Passkeys to the Communication feature table for net-maui-11+. |
| docs/whats-new/dotnet-11.md | Adds Passkeys blurb + example and updates ms.date. |
Copilot's findings
Suppressed comments (1)
docs/platform-integration/communication/passkeys.md:367
- This “Passkeys sample” See also link points at a dotnet/maui-samples path that doesn’t exist on main yet, so it’s currently broken. Same as the banner link above: consider removing it until the sample merges, or link to the maui-samples PR/branch as a temporary target and switch back to main once it’s available.
- [Passkeys sample](https://github.com/dotnet/maui-samples/tree/main/11.0/PlatformIntegration/Passkeys)
- Files reviewed: 4/4 changed files
- Comments generated: 2
PoliCheck Scan ReportThe following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans. ✅ No issues foundMore information about PoliCheckInformation: PoliCheck | Severity Guidance | Term |
|
Learn Build status updates of commit 8e1d3bd: 💡 Validation status: suggestions
docs/platform-integration/communication/passkeys.md
For more details, please refer to the build report. Note: Your PR may contain errors or warnings or suggestions unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them. |
PoliCheck Scan ReportThe following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans. ✅ No issues foundMore information about PoliCheckInformation: PoliCheck | Severity Guidance | Term |
|
Learn Build status updates of commit 1eb7adc: 💡 Validation status: suggestions
docs/platform-integration/communication/passkeys.md
For more details, please refer to the build report. Note: Your PR may contain errors or warnings or suggestions unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them. |
Adds a focused article for the Preview 7 passkeys (WebAuthn/FIDO2) API: flow overview and security boundary, native origin binding per platform, supported OS floors, Android Digital Asset Links and Apple Associated Domains setup, registration and assertion examples, PreferImmediatelyAvailable, cancellation, error handling, production cautions, and troubleshooting. Wires the article into the TOC and the platform-integration index (moniker gated to >=net-maui-11.0), and adds a what's new entry for .NET 11. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
- Split the malformed-JSON row: Android surfaces invalid options as InvalidOperationException from the credential provider rather than ArgumentException, which only iOS, Mac Catalyst, and Windows produce. - Name NotImplementedInReferenceAssemblyException (derives from NotImplementedException) for netstandard, tvOS, and Tizen, instead of implying FeatureNotSupportedException covers every unsupported target. - Correct the cancellation-subtype explanation. Android yields TaskCanceledException even for a pre-cancelled token, so the split isn't "pre-cancelled vs in-flight"; it's that Apple and Windows check the token before starting the native ceremony. Catching OperationCanceledException remains the correct guidance. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
The IMPORTANT callout said Android's InvalidOperationException lets you tell "no credential" apart from "the user changed their mind". That overstates it: InvalidOperationException is Android's catch-all for every non-cancellation failure, so it separates a missing credential from a cancellation but not from a configuration or native error. This contradicted the errors table, which already maps domain-association and other native failures to the same type, and the try/catch sample, which says the Android branch covers both. Narrow the callout to match. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 6f3a708f-f4e0-4f7e-8346-a509a099be4a
1eb7adc to
4886237
Compare
PoliCheck Scan ReportThe following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans. ✅ No issues foundMore information about PoliCheckInformation: PoliCheck | Severity Guidance | Term |
|
Learn Build status updates of commit 4886237: 💡 Validation status: suggestions
docs/platform-integration/communication/passkeys.md
For more details, please refer to the build report. Note: Your PR may contain errors or warnings or suggestions unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them. |
PoliCheck Scan ReportThe following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans. ✅ No issues foundMore information about PoliCheckInformation: PoliCheck | Severity Guidance | Term |
|
Learn Build status updates of commit 46ea074: 💡 Validation status: suggestions
docs/platform-integration/communication/passkeys.md
For more details, please refer to the build report. Note: Your PR may contain errors or warnings or suggestions unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them. |
Summary
Source verification
The API, platform behavior, OS floors, and exception mapping were verified against the Preview 7
Passkeysimplementations and public API surface from dotnet/maui#36837, plus the reviewed relying-party sample in dotnet/maui-samples#776. The guidance distinguishes Android's no-credentialInvalidOperationExceptionfrom iOS/Mac Catalyst cancellation semantics and recommends catchingOperationCanceledExceptionacross platforms.Dependency
The article uses the durable Samples Browser URL
/samples/dotnet/maui-samples/platformintegration-passkeys, registered by dotnet/maui-samples#776.Do not merge this PR until the sample is published. The content is complete and CI is green; the only outstanding item is the sample link resolving.
The blocker is no longer package availability. All required .NET 11 Preview 7 packages have now reached NuGet.org, and the latest dotnet/maui-samples#776 run restores successfully with no
NU1102errors.Microsoft.Maui.Controls11.0.0-preview.7.26406.9Microsoft.Extensions.Logging.Debug,Microsoft.AspNetCore.Identity.EntityFrameworkCore,Microsoft.EntityFrameworkCore.Sqlite11.0.0-preview.7.26381.103The CI SDK resolution problem in the samples repo has been fixed. The 11.0 release metadata channel still reports
11.0.100-preview.6.26359.118as the latest SDK and has no Preview 7 entry, so the samples workflows requesting11.0.xwere resolving to the Preview 6 SDK and workloads. That produced a Preview 7 MAUI package built against a Preview 6 Android workload, failing withCS1705on aJava.Interopversion mismatch.dotnet/maui-samples#778 has merged, pinning the PR build workflow to the exact SDK
11.0.100-preview.7.26381.103. An exact version installs directly from the build feed rather than resolving through the release metadata channel, so this no longer waits on Preview 7 appearing in release metadata. The fresh #776 run confirms it worked: noNU1102, noCS1705, andbuild (windows-latest)now passes.The macOS leg then failed for a second, unrelated reason: the workflow selected Xcode 26.3, but the final Apple Preview 7 workloads require Xcode 26.6.
dotnet/maui-samples#779 has merged, switching CI to Xcode 26.6.
Both CI blockers are therefore fixed on the samples repo's default branch. What remains is a definitive fresh #776 run that picks up both changes, since its most recent run predates the Xcode fix.
These were environment and release-sequencing issues, not defects in the sample or in this article.
No change to this PR is needed when the dependency clears. The unblock order is: dotnet/maui-samples#776 gets a fresh CI run on the fixed workflow and goes green on both legs, #776 merges, the sample indexes, then this PR can merge as-is.
A branch or PR URL was deliberately not used as a temporary substitute, because a non-durable link would ship in published docs if the swap-back were missed.
Validation
The consolidated Preview 7 changes to
docs/whats-new/dotnet-11.mdare intentionally reserved for a separate final PR.Internal previews