[release/10.0-preview7] Passkey design follow-ups (#62841)

* Passkey design follow-ups (#62530)

* Use `GetService()` instead of `GetRequiredService()`

* Remove usings

Author: MackinnonBuck

src/Identity/Core/src/IPasskeyHandler.cs

@@ -1,25 +1,44 @@
 // Licensed to the .NET Foundation under one or more agreements.
 // The .NET Foundation licenses this file to you under the MIT license.
 
+using Microsoft.AspNetCore.Http;
+
 namespace Microsoft.AspNetCore.Identity;
 
 /// <summary>
-/// Represents a handler for passkey assertion and attestation.
+/// Represents a handler for generating passkey creation and request options and performing
+/// passkey assertion and attestation.
 /// </summary>
 public interface IPasskeyHandler<TUser>
     where TUser : class
 {
     /// <summary>
-    /// Performs passkey attestation using the provided credential JSON and original options JSON.
+    /// Generates passkey creation options for the specified user entity and HTTP context.
+    /// </summary>
+    /// <param name="userEntity">The passkey user entity for which to generate creation options.</param>
+    /// <param name="httpContext">The HTTP context associated with the request.</param>
+    /// <returns>A <see cref="PasskeyCreationOptionsResult"/> representing the result.</returns>
+    Task<PasskeyCreationOptionsResult> MakeCreationOptionsAsync(PasskeyUserEntity userEntity, HttpContext httpContext);
+
+    /// <summary>
+    /// Generates passkey request options for the specified user and HTTP context.
+    /// </summary>
+    /// <param name="user">The user for whom to generate request options.</param>
+    /// <param name="httpContext">The HTTP context associated with the request.</param>
+    /// <returns>A <see cref="PasskeyRequestOptionsResult"/> representing the result.</returns>
+    Task<PasskeyRequestOptionsResult> MakeRequestOptionsAsync(TUser? user, HttpContext httpContext);
+
+    /// <summary>
+    /// Performs passkey attestation using the provided <see cref="PasskeyAttestationContext"/>.
     /// </summary>
     /// <param name="context">The context containing necessary information for passkey attestation.</param>
-    /// <returns>A task object representing the asynchronous operation containing the <see cref="PasskeyAttestationResult"/>.</returns>
-    Task<PasskeyAttestationResult> PerformAttestationAsync(PasskeyAttestationContext<TUser> context);
+    /// <returns>A <see cref="PasskeyAttestationResult"/> representing the result.</returns>
+    Task<PasskeyAttestationResult> PerformAttestationAsync(PasskeyAttestationContext context);
 
     /// <summary>
-    /// Performs passkey assertion using the provided credential JSON, original options JSON, and optional user.
+    /// Performs passkey assertion using the provided <see cref="PasskeyAssertionContext"/>.
     /// </summary>
     /// <param name="context">The context containing necessary information for passkey assertion.</param>
-    /// <returns>A task object representing the asynchronous operation containing the <see cref="PasskeyAssertionResult{TUser}"/>.</returns>
-    Task<PasskeyAssertionResult<TUser>> PerformAssertionAsync(PasskeyAssertionContext<TUser> context);
+    /// <returns>A <see cref="PasskeyAssertionResult{TUser}"/> representing the result.</returns>
+    Task<PasskeyAssertionResult<TUser>> PerformAssertionAsync(PasskeyAssertionContext context);
 }

src/Identity/Core/src/IdentityBuilderExtensions.cs

@@ -41,7 +41,7 @@ public static IdentityBuilder AddDefaultTokenProviders(this IdentityBuilder buil
     private static void AddSignInManagerDeps(this IdentityBuilder builder)
     {
         builder.Services.AddHttpContextAccessor();
-        builder.Services.AddScoped(typeof(IPasskeyHandler<>).MakeGenericType(builder.UserType), typeof(DefaultPasskeyHandler<>).MakeGenericType(builder.UserType));
+        builder.Services.AddScoped(typeof(IPasskeyHandler<>).MakeGenericType(builder.UserType), typeof(PasskeyHandler<>).MakeGenericType(builder.UserType));
         builder.Services.AddScoped(typeof(ISecurityStampValidator), typeof(SecurityStampValidator<>).MakeGenericType(builder.UserType));
         builder.Services.AddScoped(typeof(ITwoFactorSecurityStampValidator), typeof(TwoFactorSecurityStampValidator<>).MakeGenericType(builder.UserType));
         builder.Services.TryAddEnumerable(ServiceDescriptor.Singleton<IPostConfigureOptions<SecurityStampValidatorOptions>, PostConfigureSecurityStampValidatorOptions>());

src/Identity/Core/src/IdentityJsonSerializerContext.cs

@@ -11,6 +11,8 @@ namespace Microsoft.AspNetCore.Identity;
 [JsonSerializable(typeof(PublicKeyCredentialRequestOptions))]
 [JsonSerializable(typeof(PublicKeyCredential<AuthenticatorAssertionResponse>))]
 [JsonSerializable(typeof(PublicKeyCredential<AuthenticatorAttestationResponse>))]
+[JsonSerializable(typeof(PasskeyAttestationState))]
+[JsonSerializable(typeof(PasskeyAssertionState))]
 [JsonSourceGenerationOptions(
     JsonSerializerDefaults.Web,
     DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull,

src/Identity/Core/src/IdentityPasskeyOptions.cs

@@ -0,0 +1,184 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+namespace Microsoft.AspNetCore.Identity;
+
+/// <summary>
+/// Specifies options for passkey requirements.
+/// </summary>
+public class IdentityPasskeyOptions
+{
+    /// <summary>
+    /// Gets or sets the time that the browser should wait for the authenticator to provide a passkey.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// This option applies to both creating a new passkey and requesting an existing passkey.
+    /// This is treated as a hint to the browser, and the browser may choose to ignore it.
+    /// </para>
+    /// <para>
+    /// The default value is 5 minutes.
+    /// </para>
+    /// <para>
+    /// See <see href="https://www.w3.org/TR/webauthn-3/#dom-publickeycredentialcreationoptions-timeout"/>
+    /// and <see href="https://www.w3.org/TR/webauthn-3/#dom-publickeycredentialrequestoptions-timeout"/>.
+    /// </para>
+    /// </remarks>
+    public TimeSpan AuthenticatorTimeout { get; set; } = TimeSpan.FromMinutes(5);
+
+    /// <summary>
+    /// Gets or sets the size of the challenge in bytes sent to the client during attestation and assertion.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// This option applies to both creating a new passkey and requesting an existing passkey.
+    /// </para>
+    /// <para>
+    /// The default value is 32 bytes.
+    /// </para>
+    /// <para>
+    /// See <see href="https://www.w3.org/TR/webauthn-3/#dom-publickeycredentialcreationoptions-challenge"/>
+    /// and <see href="https://www.w3.org/TR/webauthn-3/#dom-publickeycredentialrequestoptions-challenge"/>.
+    /// </para>
+    /// </remarks>
+    public int ChallengeSize { get; set; } = 32;
+
+    /// <summary>
+    /// Gets or sets the effective ___domain of the server.
+    /// This should be unique and will be used as the identity for the server.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// This option applies to both creating a new passkey and requesting an existing passkey.
+    /// </para>
+    /// <para>
+    /// If left <see langword="null"/>, the server's origin may be used instead.
+    /// </para>
+    /// <para>
+    /// See <see href="https://www.w3.org/TR/webauthn-3/#rp-id"/>.
+    /// </para>
+    /// </remarks>
+    public string? ServerDomain { get; set; }
+
+    /// <summary>
+    /// Gets or sets the user verification requirement.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// This option applies to both creating a new passkey and requesting an existing passkey.
+    /// </para>
+    /// <para>
+    /// Possible values are "required", "preferred", and "discouraged".
+    /// </para>
+    /// <para>
+    /// If left <see langword="null"/>, the browser defaults to "preferred".
+    /// </para>
+    /// <para>
+    /// See <see href="https://www.w3.org/TR/webauthn-3/#enumdef-userverificationrequirement"/>.
+    /// </para>
+    /// </remarks>
+    public string? UserVerificationRequirement { get; set; }
+
+    /// <summary>
+    /// Gets or sets the extent to which the server desires to create a client-side discoverable credential.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// This option only applies when creating a new passkey, and is not enforced on the server.
+    /// </para>
+    /// <para>
+    /// Possible values are "discouraged", "preferred", or "required".
+    /// </para>
+    /// <para>
+    /// If left <see langword="null"/>, the browser defaults to "preferred".
+    /// </para>
+    /// <para>
+    /// See <see href="https://www.w3.org/TR/webauthn-3/#enumdef-residentkeyrequirement"/>.
+    /// </para>
+    /// </remarks>
+    public string? ResidentKeyRequirement { get; set; }
+
+    /// <summary>
+    /// Gets or sets the attestation conveyance preference.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// This option only applies when creating a new passkey, and already-registered passkeys are not affected by it.
+    /// To validate the attestation statement of a passkey during passkey creation, provide a value for the
+    /// <see cref="VerifyAttestationStatement"/> option.
+    /// </para>
+    /// <para>
+    /// Possible values are "none", "indirect", "direct", and "enterprise".
+    /// </para>
+    /// <para>
+    /// If left <see langword="null"/>, the browser defaults to "none".
+    /// </para>
+    /// <para>
+    /// See <see href="https://www.w3.org/TR/webauthn-3/#enumdef-attestationconveyancepreference"/>.
+    /// </para>
+    /// </remarks>
+    public string? AttestationConveyancePreference { get; set; }
+
+    /// <summary>
+    /// Gets or sets the allowed authenticator attachment.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// This option only applies when creating a new passkey, and already-registered passkeys are not affected by it.
+    /// </para>
+    /// <para>
+    /// Possible values are "platform" and "cross-platform".
+    /// </para>
+    /// <para>
+    /// If left <see langword="null"/>, any authenticator attachment modality is allowed.
+    /// </para>
+    /// <para>
+    /// See <see href="https://www.w3.org/TR/webauthn-3/#enumdef-authenticatorattachment"/>.
+    /// </para>
+    /// </remarks>
+    public string? AuthenticatorAttachment { get; set; }
+
+    /// <summary>
+    /// Gets or sets a function that determines whether the given COSE algorithm identifier
+    /// is allowed for passkey operations.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// This option only applies when creating a new passkey, and already-registered passkeys are not affected by it.
+    /// </para>
+    /// <para>
+    /// If left <see langword="null"/>, all supported algorithms are allowed.
+    /// </para>
+    /// <para>
+    /// See <see href="https://www.iana.org/assignments/cose/cose.xhtml#algorithms"/>.
+    /// </para>
+    /// </remarks>
+    public Func<int, bool>? IsAllowedAlgorithm { get; set; }
+
+    /// <summary>
+    /// Gets or sets a function that validates the origin of the request.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// This option applies to both creating a new passkey and requesting an existing passkey.
+    /// </para>
+    /// <para>
+    /// If left <see langword="null"/>, cross-origin requests are disallowed, and the request is only
+    /// considered valid if the request's origin header matches the credential's origin.
+    /// </para>
+    /// </remarks>
+    public Func<PasskeyOriginValidationContext, ValueTask<bool>>? ValidateOrigin { get; set; }
+
+    /// <summary>
+    /// Gets or sets a function that verifies the attestation statement of a passkey.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// This option only applies when creating a new passkey, and already-registered passkeys are not affected by it.
+    /// </para>
+    /// <para>
+    /// If left <see langword="null"/>, this function does not perform any verification and always returns <see langword="true"/>.
+    /// </para>
+    /// </remarks>
+    public Func<PasskeyAttestationStatementVerificationContext, ValueTask<bool>>? VerifyAttestationStatement { get; set; }
+}

src/Identity/Core/src/IdentityServiceCollectionExtensions.cs

@@ -102,7 +102,7 @@ public static class IdentityServiceCollectionExtensions
         services.TryAddScoped<ITwoFactorSecurityStampValidator, TwoFactorSecurityStampValidator<TUser>>();
         services.TryAddScoped<IUserClaimsPrincipalFactory<TUser>, UserClaimsPrincipalFactory<TUser, TRole>>();
         services.TryAddScoped<IUserConfirmation<TUser>, DefaultUserConfirmation<TUser>>();
-        services.TryAddScoped<IPasskeyHandler<TUser>, DefaultPasskeyHandler<TUser>>();
+        services.TryAddScoped<IPasskeyHandler<TUser>, PasskeyHandler<TUser>>();
         services.TryAddScoped<UserManager<TUser>>();
         services.TryAddScoped<SignInManager<TUser>>();
         services.TryAddScoped<RoleManager<TRole>>();

src/Identity/Core/src/PasskeyAssertionContext.cs

@@ -8,14 +8,12 @@ namespace Microsoft.AspNetCore.Identity;
 /// <summary>
 /// Represents the context for passkey assertion.
 /// </summary>
-/// <typeparam name="TUser">The type of user associated with the passkey.</typeparam>
-public sealed class PasskeyAssertionContext<TUser>
-    where TUser : class
+public sealed class PasskeyAssertionContext
 {
     /// <summary>
-    /// Gets or sets the user associated with the passkey, if known.
+    /// Gets or sets the <see cref="Http.HttpContext"/> for the current request. 
     /// </summary>
-    public TUser? User { get; init; }
+    public required HttpContext HttpContext { get; init; }
 
     /// <summary>
     /// Gets or sets the credentials obtained by JSON-serializing the result of the
@@ -24,17 +22,11 @@ public sealed class PasskeyAssertionContext<TUser>
     public required string CredentialJson { get; init; }
 
     /// <summary>
-    /// Gets or sets the JSON representation of the original passkey creation options provided to the browser.
-    /// </summary>
-    public required string OriginalOptionsJson { get; init; }
-
-    /// <summary>
-    /// Gets or sets the <see cref="UserManager{TUser}"/> to retrieve user information from.
+    /// Gets or sets the state to be used in the assertion procedure.
     /// </summary>
-    public required UserManager<TUser> UserManager { get; init; }
-
-    /// <summary>
-    /// Gets or sets the <see cref="HttpContext"/> for the current request. 
-    /// </summary>
-    public required HttpContext HttpContext { get; init; }
+    /// <remarks>
+    /// This is expected to match the <see cref="PasskeyRequestOptionsResult.AssertionState"/>
+    /// previously returned from <see cref="IPasskeyHandler{TUser}.MakeRequestOptionsAsync(TUser, HttpContext)"/>.
+    /// </remarks>
+    public required string? AssertionState { get; init; }
 }

src/Identity/Core/src/PasskeyAttestationContext.cs

@@ -8,28 +8,25 @@ namespace Microsoft.AspNetCore.Identity;
 /// <summary>
 /// Represents the context for passkey attestation.
 /// </summary>
-/// <typeparam name="TUser">The type of user associated with the passkey.</typeparam>
-public sealed class PasskeyAttestationContext<TUser>
-    where TUser : class
+public sealed class PasskeyAttestationContext
 {
     /// <summary>
-    /// Gets or sets the credentials obtained by JSON-serializing the result of the
-    /// <c>navigator.credentials.create()</c> JavaScript function.
-    /// </summary>
-    public required string CredentialJson { get; init; }
-
-    /// <summary>
-    /// Gets or sets the JSON representation of the original passkey creation options provided to the browser.
+    /// Gets or sets the <see cref="Http.HttpContext"/> for the current request. 
     /// </summary>
-    public required string OriginalOptionsJson { get; init; }
+    public required HttpContext HttpContext { get; init; }
 
     /// <summary>
-    /// Gets or sets the <see cref="UserManager{TUser}"/> to retrieve user information from.
+    /// Gets or sets the credentials obtained by JSON-serializing the result of the
+    /// <c>navigator.credentials.create()</c> JavaScript function.
     /// </summary>
-    public required UserManager<TUser> UserManager { get; init; }
+    public required string CredentialJson { get; init; }
 
     /// <summary>
-    /// Gets or sets the <see cref="HttpContext"/> for the current request. 
+    /// Gets or sets the state to be used in the attestation procedure.
     /// </summary>
-    public required HttpContext HttpContext { get; init; }
+    /// <remarks>
+    /// This is expected to match the <see cref="PasskeyCreationOptionsResult.AttestationState"/>
+    /// previously returned from <see cref="IPasskeyHandler{TUser}.MakeCreationOptionsAsync(PasskeyUserEntity, HttpContext)"/>.
+    /// </remarks>
+    public required string? AttestationState { get; init; }
 }

src/Identity/Core/src/PasskeyAttestationResult.cs

@@ -14,6 +14,7 @@ public sealed class PasskeyAttestationResult
     /// Gets whether the attestation was successful.
     /// </summary>
     [MemberNotNullWhen(true, nameof(Passkey))]
+    [MemberNotNullWhen(true, nameof(UserEntity))]
     [MemberNotNullWhen(false, nameof(Failure))]
     public bool Succeeded { get; }
 
@@ -22,15 +23,21 @@ public sealed class PasskeyAttestationResult
     /// </summary>
     public UserPasskeyInfo? Passkey { get; }
 
+    /// <summary>
+    /// Gets the user entity associated with the passkey when successful.
+    /// </summary>
+    public PasskeyUserEntity? UserEntity { get; }
+
     /// <summary>
     /// Gets the error that occurred during attestation.
     /// </summary>
     public PasskeyException? Failure { get; }
 
-    private PasskeyAttestationResult(UserPasskeyInfo passkey)
+    private PasskeyAttestationResult(UserPasskeyInfo passkey, PasskeyUserEntity userEntity)
     {
         Succeeded = true;
         Passkey = passkey;
+        UserEntity = userEntity;
     }
 
     private PasskeyAttestationResult(PasskeyException failure)
@@ -43,11 +50,12 @@ private PasskeyAttestationResult(PasskeyException failure)
     /// Creates a successful result for a passkey attestation operation.
     /// </summary>
     /// <param name="passkey">The passkey information associated with the attestation.</param>
+    /// <param name="userEntity">The user entity associated with the attestation.</param>
     /// <returns>A <see cref="PasskeyAttestationResult"/> instance representing a successful attestation.</returns>
-    public static PasskeyAttestationResult Success(UserPasskeyInfo passkey)
+    public static PasskeyAttestationResult Success(UserPasskeyInfo passkey, PasskeyUserEntity userEntity)
     {
         ArgumentNullException.ThrowIfNull(passkey);
-        return new PasskeyAttestationResult(passkey);
+        return new PasskeyAttestationResult(passkey, userEntity);
     }
 
     /// <summary>