IdentityModel 7x
All the IdentityModel libraries must have the same version 7.0.0 in your project and including the recursive dependencies.
dotnet restore yourProject.csproj
dotnet list yourProject.csproj package --include-transitiveto see the list of all packages dependencies.
We are excited to announce the release of IdentityModel 7.0.0, a major update to our popular .NET auth validation library. This new version introduces several improvements related to serialization and consistency in the API, which will provide a better user experience for developers, as well as full AOT compatibility on .NET, and huge perf improvements compared to 6x.
Working closely with Stephen Toub and the .NET perf army, we were able to make considerable perf improvements for IdentityModel 7, building on RSA crypto improvements already in .NET8.
Initial perf assessments with .NET7 and System.IdentityModel.Tokens.JWT 6.31.0 compared to .NET8 and IdentityModel 7.0.0 using JsonWebTokenHandler
| CPU | 1 token | 10 tokens | 100 tokens | 1000 tokens | 10000 tokens |
|---|---|---|---|---|---|
| .NET7 | 51 | 91 | 100 | 100 | 100 |
| .NET8 | 42 | 70 | 100 | 100 | 100 |
| RPS | 1 token | 10 tokens | 100 tokens | 1000 tokens | 10000 tokens |
|---|---|---|---|---|---|
| .NET7 | 565.54 | 554.54 | 131 | 15.01 | 1.9 |
| .NET8 | 569.34 | 562.94 | 193.52 | 22.32 | 2.38 |
Efficiency = RPS / CPU
| Efficiency | 1 token | 10 tokens | 100 tokens | 1000 tokens | 10000 tokens |
|---|---|---|---|---|---|
| .NET7 | 11.089 | 6.094 | 1.310 | 0.150 | 0.019 |
| .NET8 | 13.556 | 8.042 | 1.935 | 0.223 | 0.024 |
Throughput = Processed MBytes / 60
The throughput measures how many bytes are received in the client per second
| Throughput MB/sec | 1 token | 10 tokens | 100 tokens | 1000 tokens | 10000 tokens |
|---|---|---|---|---|---|
| .NET7 | 107.31 | 102.86 | 22.77 | 2.63 | 0.287 |
| .NET8 | 106.72 | 105.1 | 34.28 | 4.08 | 0.429 |
We are excited to deliver these perf improvements, as well as full AOT compatibility. Updating your service to .NET8 and IdentityModel 7x means your service benefits from meaningful improvements reflected in COGs, throughput, and latency.
One of the main improvements in IdentityModel 7.x is related to serialization issues. Previously, IdentityModel used Newtonsoft for JSON serialization, but now it uses System.Text.Json. While this change provides better performance and AOT compatibility with .NET, it also means that there may be some subtle differences in serialization that users need to be aware of.
For example, some of our types that are based on JSON specs have settable collections. However, .NET best practices recommend not having setters on properties with collections. Therefore, we have removed the setters on these collections, which may result in some differences in behavior for users who use different serialization logic.
Additionally, when JSON is being deserialized into an object and the property name in the JSON does not match any property in the type, there is a model to place the deserialized JSON into the property AdditionalData.Dictionary<string, object>. We have made improvements to how unknown properties are handled during deserialization to provide a more consistent user experience.
Another improvement in IdentityModel 7.x is related to consistency in the API. Specifically, we have made changes to how unknown properties are handled during deserialization to provide a more consistent user experience. Previously, when unknown properties were encountered during deserialization, they were stored in internal objects. However, in the new version, complex unknown types are exposed as JsonElement that you can examine for the underlying type.
We have also removed setters on properties with collections to follow best practices and present a consistent API. While this may result in some differences in behavior for users who use different serialization logic, we believe that it is an important step towards providing a more consistent user experience.
If you are currently using IdentityModel, you may need to make some changes to migrate to version 7.x. Specifically, you should be aware of the following breaking changes:
IdentityModel no longer supports .NET framework 4.5.2, which reached end of support on April 24, 2022. It's recommended to migrate to .NET 8, which has considerable perf improvements compared to .NET 7, Stephen Toub's .NET 8 perf blog is coming soon. Dropping .NET 452 allowed IdentityModel to be fully Ahead of Time (AOT) compatible.
-
ValidateTokenwas a sync method calling an async method, which can lead to threadpool starvation when on the hot path, this method has been deprecated, please useValidateTokenAsyncinstead. See issue #2253 for details.
-
JwtPayload.Exp,.Iat,.Nbfwas returning values asintwhich does not handle dates after Tue, 19 Jan 2038 03:14:07 GMT. These are marked as obsolete and new methods return a long instead, please usepublic long? Expirationandpublic long? NotBeforeinstead. See issue #2266 for details.
-
JwtPayload.Sub, was strictly enforced as aStringper Jwt specifications. However, in order to accommodate a subset of customer who are setting thesubclaim as aNumber, we've made changes to enablesubclaim to be set as aNumberorString. Lastly, it was also discovered that, we used to allow 'sub' claim to be anArraywhich, will no longer be allowed moving forward. See issue #2398 for details.
Bringing you a more performant IdentityModel with full AOT compatibility in .NET 8 has been a team effort on many fronts.
Huge thank you to our colleagues in DevDiv, @stephentoub, @davidfowl, @eerhardt, @Tratcher, @halter73, @BrennanConroy, and @captainsafia.
Huge thank you to our community members, @kevinchalet, @Cyberboss, @cakescience, @brockallen, @leastprivilege, and @josephdecock, who gave feedback early on with previews 1-5 which enabled us to catch regressions quickly and ensure the breaking changes were as minimal as possible.
Finally, thanks to our dev team, @brentschmaltz, @keegan-caruso, @westin-m, our lead @jennyf19, and our PM, @jmprieur, for delivering on these improvements. We are looking forward to delivering more value across our suite of Microsoft auth SDKs.
Please join the discussion on IdentityModel 7 or open an issue in the repo.