[Documentation] Relationship with Azure and Microsoft.IdentityModel

[martinmine]

Documentation related to component

Repository

Please check all that apply

• [ ] typo
• [x] documentation doesn't exist
• [ ] documentation needs clarification
• [ ] error(s) in the example
• [ ] needs an example

Description of the issue

Several commonly used packages in asp.net core such as Microsoft.AspNetCore.Authentication.JwtBearer has a dependency on Microsoft.IdentityModel.Protocols.OpenIdConnect, which then has a dependency on System.IdentityModel.Tokens.Jwt. The two latter NuGet packages are originating from this repository, but from this repository name I get the expectation that this repository has to do with Azure AD Entra ID integration in context of in .NET. To max out the confusion, the solution name for all the packages is named Wilson (who is Wilson?). I am seeking some kind of documentation that clarifies all these questions I get as a .NET developer digging around in the OAuth code that I ship with my services. It would be great to see some documentation that says why some stuff is under the System.IdentityModel while other parts is under Microsoft.IdentityModel. Given the importance this repository has in terms of auth and its usage in asp.net core, I had an expectation that it would live under either https://github.com/dotnet/aspnetcore or some other central repository. I can understand that there are historical reasons for the naming, and all kudos to the Azure team for making this happen, but perhaps it would be time to consider renaming the repository?

[jennyf19]

@martinmine thanks for the feedback. The brand for Azure AD has evolved over time (AzureAD -> Microsoft Identity Platform -> EntraID) but we cannot change the name of the dlls to match this shift in branding. Also IdentityModel is not AzureAD/EntraID specific, it follows the standards (OAuth2/OIDC/SAML) and works with all IdPs.

As far as the package names, the repo has been around for over 10 years (since 2014) and evolved overtime. Due to parts of this library shipping in .NET, we have to be very careful with breaking changes, so not easy to make major refactorings.

As far as it not living under dotnet/aspnetcore, we have very different ship cycles. .NET ships once per year in November, with monthly updates (some security), but we need to be able to ship a security update or fix at any time. Being outside .net gives us the flexibility we need.

We are working on improving the documentation specifically for IdentityModel. Again, appreciate your feedback.

@brentschmaltz is the original author and can comment more on historical specifics.

[martinmine]

Thanks for your comment and perspectives. I have complete understanding that it becomes difficult to rename assemblies due to backwards compatibility. However, there are smaller low hanging fruits such as renaming the repository from "azure-activedirectory-identitymodel-extensions-for-dotnet" to "Microsoft.IdentityModel" (or something along those lines?), in addition to the Wilson (?) solution file to something that makes more sense for an external contributor that does not know the entire history of this repository.

[jennyf19]

Thanks for your comment and perspectives. I have complete understanding that it becomes difficult to rename assemblies due to backwards compatibility. However, there are smaller low hanging fruits such as renaming the repository from "azure-activedirectory-identitymodel-extensions-for-dotnet" to "Microsoft.IdentityModel" (or something along those lines?), in addition to the Wilson (?) solution file to something that makes more sense for an external contributor that does not know the entire history of this repository.

FYI @jmprieur ^