Document IPasskeyHandler and attestation state validation - #37438
Open
rolandVi wants to merge 1 commit into
Open
Document IPasskeyHandler and attestation state validation#37438rolandVi wants to merge 1 commit into
rolandVi wants to merge 1 commit into
Conversation
guardrex
self-requested a review
August 7, 2026 16:01
Collaborator
|
Thanks @rolandVi! ... I'm heading OOF for the weekend shortly, so I'll look at this next week. Have a great weekend! 🍻 |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Resolves #37437. Tracked by dotnet/aspnetcore#66750.
IPasskeyHandler<TUser>is public API with no docs. An app that calls it directly takes over storing the attestation state between the two registration requests, and that state is what decides which account the new passkey ends up on. The passkeys article only covers theSignInManagerpath today, so anyone stepping off it has nothing to go on. This adds a section on when to reach for the handler and what the app becomes responsible for once it does.What changed
One new H2, Customize the passkey handler, in
aspnetcore/security/authentication/passkeys/index.md. Five subsections: when to implement the interface, what the attestation state is, the three things an app has to get right (integrity, ownership, single use), a worked registration example, and how to register a custom handler.It sits after Custom origin validation and before Registration flow, so the customization sections run least to most invasive. The Step 2 paragraph in the registration flow now points at it, since that's where the state is first mentioned.
The example keeps the state in a data-protected cookie rather than server-side session state. It needs no extra infrastructure and it mirrors what
SignInManageralready does.The DI subsection flags that
AddSignInManagerregisters the default handler withAddScoped, notTryAddScoped(IdentityBuilderExtensions.csline 44), so a custom handler registered before the Identity calls is silently replaced. Worth a reviewer's eye, it's easy to get wrong and you can't tell from the API.Internal previews