Azure-activedirectory-identitymodel-extensions-for-dotnet: Add clear documentation about claims type mapping

[zvrba]

The original issue got closed without any useful resolution.

I understand the reluctance to make a breaking change (turning off mapping by default), but it should at least be clearly documented in a warning box in the documentation in one of the sections on authorization!!!!!!!!!!!!!!!!!!!!!!

Edit: as an example, this page https://docs.microsoft.com/en-us/aspnet/core/security/authorization/claims?view=aspnetcore-2.2 shows how to require "EmployeeNumber" claim. When I paste my token in jwt.ms, it displays "scp" as the scope name. Then I added the code below, and did it work? NO!

---

From the original post.

Seriously, closed? I just lost two days trying to get the following to work

                opts.AddPolicy("ProjectAccessScope", policy => {
                    policy.RequireClaim("scp", Components.AppScopes.ProjectMember);
                });

It was constantly failing, I had to turn off policy-based authorization and inspect the token manually to discover that it has been renamed. And where is renaming of token types mentioned in the aspnet.core documentation? NOWHERE!

_Originally posted by @zvrba in https://github.com/AzureAD/azure-activedirectory-identitymodel-extensions-for-dotnet/issues/415#issuecomment-507764708_

[GeoK]

Hi @zvrba - I'm sorry to hear that. We can definitely do better w.r.t. documentation.
Could you recommend a good spot for a comment like that within the IdentityModel extensions for .Net library?

[zvrba]

Hi,

I think the comment should really be placed into the aspnet core page I linked to in the original post. I'm new to aspnet core and that documentation is the first I consult when developing. If it must be in IdentityModel documentation, then I think this would be the appropriate page: https://github.com/AzureAD/azure-activedirectory-identitymodel-extensions-for-dotnet/wiki/How-ASP.NET-Core-uses-Microsoft.IdentityModel-extensions-for-.NET

Add a section "WARNING about claim type mapping" and text like: Standard jwt claims get remapped to WS (or whatever it's called) URI claim types, i.e., the claim type shown on jwt.ms won't match the type fetched from the User principal. When checking these claims, as described on https://docs.microsoft.com/en-us/aspnet/core/security/authorization/claims?view=aspnetcore-2.2, you should use constants from ClaimTypes class or turn of remapping like this: [insert code].

Another thing: Initially, I have tried to use constants from ClaimTypes class (assembly version 4.1.1.0), but I haven't been able to find a constant for "scope", which definitely gets remapped. That's where things went wrong. So something else is amiss -- why is there no scope type in ClaimTypes class?

[GeoK]

@zvrba - Thank you for raising this issue and for the suggestions.
I'll add this item as one of task for the next milestone.

To answer your other question, _ClaimTypes_ class belongs to _System.Security.Claims_ assembly which ships independently of IdentityModel extensions for .Net assemblies.
The complete mapping of claim types is available here.

[brentschmaltz]

@zvrba @GeoK i'll work on a wiki page that asp.net can link to if they choose. I agree this whole mapping issue is complicated.

[ericsampson]

That would be great @brentschmaltz , this is a footgun area : )