|
| 1 | +# ASP.NET Core Identity PassKey Support |
| 2 | + |
| 3 | +## Overview |
| 4 | + |
| 5 | +Pomelo.EntityFrameworkCore.MySql fully supports ASP.NET Core Identity PassKeys (WebAuthn credentials) introduced in .NET 10 / ASP.NET Core Identity Schema Version 3. |
| 6 | + |
| 7 | +## Background |
| 8 | + |
| 9 | +There was a concern raised in [dotnet/aspnetcore#64939](https://github.com/dotnet/aspnetcore/issues/64939) that MySQL providers might not support PassKeys because the `IdentityPasskeyData` class contains properties with non-primitive types (specifically `string[]` for the `Transports` property) that need to be stored as JSON using EF Core's `.ToJson()` method. |
| 10 | + |
| 11 | +## Verification Results |
| 12 | + |
| 13 | +✅ **Pomelo.EntityFrameworkCore.MySql works perfectly with PassKeys!** |
| 14 | + |
| 15 | +We've created and tested a complete sample application (`samples/PassKeyTest`) that demonstrates: |
| 16 | + |
| 17 | +1. ✅ Creating the `AspNetUserPasskeys` table with proper schema |
| 18 | +2. ✅ Storing PassKey data with complex types including `string[]` arrays |
| 19 | +3. ✅ Reading back PassKey records with full data integrity |
| 20 | +4. ✅ JSON serialization/deserialization of all properties |
| 21 | +5. ✅ Query support using MariaDB/MySQL JSON functions |
| 22 | + |
| 23 | +## How It Works |
| 24 | + |
| 25 | +Pomelo uses `MySqlStructuralJsonTypeMapping` to handle JSON columns created by `.ToJson()`: |
| 26 | + |
| 27 | +- **Storage**: JSON data is stored as `longtext` (MariaDB) or `json` (MySQL) column type |
| 28 | +- **Serialization**: Automatic conversion between .NET objects and JSON strings |
| 29 | +- **Type Support**: Full support for complex types including arrays (`string[]`, `byte[]`, etc.) |
| 30 | +- **Performance**: Efficient read/write operations with proper type mapping |
| 31 | + |
| 32 | +## Usage Example |
| 33 | + |
| 34 | +### 1. Configure DbContext |
| 35 | + |
| 36 | +```csharp |
| 37 | +public class ApplicationDbContext : IdentityDbContext< |
| 38 | + IdentityUser, |
| 39 | + IdentityRole, |
| 40 | + string, |
| 41 | + IdentityUserClaim<string>, |
| 42 | + IdentityUserRole<string>, |
| 43 | + IdentityUserLogin<string>, |
| 44 | + IdentityRoleClaim<string>, |
| 45 | + IdentityUserToken<string>, |
| 46 | + IdentityUserPasskey<string>> // Add this! |
| 47 | +{ |
| 48 | + public ApplicationDbContext(DbContextOptions<ApplicationDbContext> options) |
| 49 | + : base(options) |
| 50 | + { |
| 51 | + } |
| 52 | + |
| 53 | + protected override void OnModelCreating(ModelBuilder builder) |
| 54 | + { |
| 55 | + base.OnModelCreating(builder); |
| 56 | + |
| 57 | + // Configure PassKey entity with JSON storage |
| 58 | + builder.Entity<IdentityUserPasskey<string>>(b => |
| 59 | + { |
| 60 | + b.HasKey(p => p.CredentialId); |
| 61 | + b.ToTable("AspNetUserPasskeys"); |
| 62 | + b.Property(p => p.CredentialId).HasMaxLength(1024); |
| 63 | + b.OwnsOne(p => p.Data).ToJson(); // This enables JSON storage! |
| 64 | + }); |
| 65 | + } |
| 66 | +} |
| 67 | +``` |
| 68 | + |
| 69 | +### 2. Configure Services |
| 70 | + |
| 71 | +```csharp |
| 72 | +services.AddDbContext<ApplicationDbContext>(options => |
| 73 | + options.UseMySql(connectionString, serverVersion) |
| 74 | +); |
| 75 | + |
| 76 | +services.AddIdentity<IdentityUser, IdentityRole>() |
| 77 | + .AddEntityFrameworkStores<ApplicationDbContext>() |
| 78 | + .AddDefaultTokenProviders(); |
| 79 | +``` |
| 80 | + |
| 81 | +### 3. Use PassKeys |
| 82 | + |
| 83 | +Once configured, you can use PassKeys with ASP.NET Core Identity's standard APIs: |
| 84 | + |
| 85 | +```csharp |
| 86 | +// Register a new passkey |
| 87 | +var passkey = new IdentityUserPasskey<string> |
| 88 | +{ |
| 89 | + UserId = user.Id, |
| 90 | + CredentialId = credentialIdBytes, |
| 91 | + Data = new IdentityPasskeyData |
| 92 | + { |
| 93 | + PublicKey = publicKeyBytes, |
| 94 | + Name = "My Security Key", |
| 95 | + Transports = new[] { "usb", "nfc", "ble" }, // string[] works! |
| 96 | + CreatedAt = DateTimeOffset.UtcNow, |
| 97 | + // ... other properties |
| 98 | + } |
| 99 | +}; |
| 100 | + |
| 101 | +context.Set<IdentityUserPasskey<string>>().Add(passkey); |
| 102 | +await context.SaveChangesAsync(); |
| 103 | + |
| 104 | +// Query passkeys |
| 105 | +var userPasskeys = await context.Set<IdentityUserPasskey<string>>() |
| 106 | + .Where(p => p.UserId == userId) |
| 107 | + .ToListAsync(); |
| 108 | +``` |
| 109 | + |
| 110 | +## Tested With |
| 111 | + |
| 112 | +- ✅ .NET 10.0.101 |
| 113 | +- ✅ Microsoft.AspNetCore.Identity.EntityFrameworkCore 10.0.1 |
| 114 | +- ✅ Pomelo.EntityFrameworkCore.MySql (current version) |
| 115 | +- ✅ MySqlConnector 2.5.0 |
| 116 | +- ✅ MariaDB 11.6.2 |
| 117 | +- ✅ MySQL 8.0+ |
| 118 | + |
| 119 | +## Complete Sample |
| 120 | + |
| 121 | +See `samples/PassKeyTest` for a complete, runnable example that demonstrates: |
| 122 | +- Database creation |
| 123 | +- PassKey insertion with complex data |
| 124 | +- Data retrieval and verification |
| 125 | +- JSON structure validation |
| 126 | + |
| 127 | +## Important Notes |
| 128 | + |
| 129 | +1. **Column Type**: The `Data` column is created as: |
| 130 | + - `longtext` on MariaDB (which supports JSON validation) |
| 131 | + - `json` on MySQL 8.0+ |
| 132 | + |
| 133 | +2. **Array Support**: Non-primitive types like `string[]` are fully supported and correctly serialized as JSON arrays |
| 134 | + |
| 135 | +3. **JSON Validation**: Both MariaDB and MySQL validate the JSON structure, ensuring data integrity |
| 136 | + |
| 137 | +4. **Query Support**: You can query JSON fields using database-specific JSON functions: |
| 138 | + ```sql |
| 139 | + SELECT JSON_EXTRACT(Data, '$.Transports') FROM AspNetUserPasskeys; |
| 140 | + ``` |
| 141 | + |
| 142 | +## Migration from Other Providers |
| 143 | + |
| 144 | +If you're migrating from a different MySQL provider (like MySQL.EntityFrameworkCore) that doesn't support PassKeys: |
| 145 | + |
| 146 | +1. Update your package reference to Pomelo.EntityFrameworkCore.MySql |
| 147 | +2. Configure the DbContext as shown above |
| 148 | +3. Create and apply migrations |
| 149 | +4. Your PassKey data will work immediately! |
| 150 | + |
| 151 | +## References |
| 152 | + |
| 153 | +- [ASP.NET Core Identity PassKey Issue](https://github.com/dotnet/aspnetcore/issues/64939) |
| 154 | +- [IdentityPasskeyData Source](https://github.com/dotnet/aspnetcore/blob/main/src/Identity/Extensions.Stores/src/IdentityPasskeyData.cs) |
| 155 | +- [IdentityUserPasskey Source](https://github.com/dotnet/aspnetcore/blob/main/src/Identity/Extensions.Stores/src/IdentityUserPasskey.cs) |
| 156 | +- [WebAuthn Specification](https://www.w3.org/TR/webauthn-3/) |
0 commit comments