Skip to content

Document IPasskeyHandler and attestation state validation - #37438

Open
rolandVi wants to merge 1 commit into
dotnet:mainfrom
rolandVi:passkey-handler-guidance
Open

Document IPasskeyHandler and attestation state validation#37438
rolandVi wants to merge 1 commit into
dotnet:mainfrom
rolandVi:passkey-handler-guidance

Conversation

@rolandVi

@rolandVi rolandVi commented Aug 7, 2026

Copy link
Copy Markdown
Member

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 the SignInManager path 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 SignInManager already does.

The DI subsection flags that AddSignInManager registers the default handler with AddScoped, not TryAddScoped (IdentityBuilderExtensions.cs line 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

File Preview link
aspnetcore/security/authentication/passkeys/index.md aspnetcore/security/authentication/passkeys/index

@guardrex guardrex self-assigned this Aug 7, 2026
@guardrex
guardrex self-requested a review August 7, 2026 16:01
@guardrex

guardrex commented Aug 7, 2026

Copy link
Copy Markdown
Collaborator

Thanks @rolandVi! ... I'm heading OOF for the weekend shortly, so I'll look at this next week. Have a great weekend! 🍻

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Passkeys: document IPasskeyHandler and how to validate attestation state integrity and ownership

2 participants