Dotnet-api-docs: Where is the documentation for System.IdentityModel.Tokens.Jwt?

[stamminator]

With Windows Identity Foundation (WIF) now integrated into .NET and the System.IdentityModel.Tokens.Jwt NuGet package getting 8,000+ downloads every day, I don't understand why there isn't any official documentation. The MSDN documentation is disgraceful, offering nothing that IntelliSense doesn't already communicate, what little you have on Microsoft Docs offers no instructions, and the official GitHub repo for the NuGet package is a confusing mess that feels like trying to crack a walnut with a sledgehammer when trying to sift through the many projects just to find a simple, no-frills example.

For example, take a standard and common use case of needing to encrypt a JWT payload. The only usable solution I could find is this Stack Overflow post, and even that uses a hodgepodge of WIF 3.5 and .NET 4+ namespaces that feels more like a hack than a good solution.

JWTs are the standard now, and Microsoft Docs desperately needs dedicated documentation for developers on this topic. Please let us know what the plan is for this.

• Thanks

---

Document Details

⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

• ID: 06bdbd36-1298-419e-9ae8-e3582e804ced
• Version Independent ID: be11dcde-c28b-d40c-08c0-bc4d504c6df9
• Content: System.IdentityModel Namespace
• Content Source: xml/ns-System.IdentityModel.xml
• Service: .net
• GitHub Login: @dotnet-bot
• Microsoft Alias: v-jibran

[mairaw]

Thanks for your feedback @stamminator. @brentschmaltz can you please comment on this issue? MSDN will no longer exist in a couple of months as well.

[infoberg]

I second that request. Weeks gone by, still no reaction/documentation available?

[mairaw]

This was moved to our backlog as a P3 work item @infoberg. We'll need @brentschmaltz to take a look at this request and take action.

[brentschmaltz]

@mairaw We are currently documenting here: https://github.com/AzureAD/azure-activedirectory-identitymodel-extensions-for-dotnet/wiki

[infoberg]

@brentschmaltz please excuse me if I am missing something here, but do you call the release notes, links to the source code and 1 sample (which does not include JWE) a documentation?

[BoomerHudson]

Sent from Mailhttps://go.microsoft.com/fwlink/?LinkId=550986 for Windows 10

From: [e-mail]
Sent: Thursday, June 14, 2018 07:07 AM
To: dotnet/[e-mail]
Cc: [e-mail]
Subject: Re: [dotnet/docs] Where is the documentation for System.IdentityModel.Tokens.Jwt? (#5321)

@brentschmaltzhttps://nam04.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2Fbrentschmaltz&data=02%7C01%7C%7C6a6e7dae8754436ac47708d5d1ef59fa%7C84df9e7fe9f640afb435aaaaaaaaaaaa%7C1%7C0%7C636645748285072457&sdata=GKED3INvFKOER2JhLBgFEdvWq8ml2ywIiaIbZBstyik%3D&reserved=0 please excuse me if I am missing something here, but do you call the release notes, links to the source code and 1 sample (which does not include JWE) a documentation?

—
You are receiving this because you are subscribed to this thread.
Reply to this email directly, view it on GitHubhttps://nam04.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2Fdotnet%2Fdocs%2Fissues%2F5321%23issuecomment-397270950&data=02%7C01%7C%7C6a6e7dae8754436ac47708d5d1ef59fa%7C84df9e7fe9f640afb435aaaaaaaaaaaa%7C1%7C0%7C636645748285072457&sdata=Xq6g44WrDQMM2xHNrjtIlD0mR4%2BSIihv7nxFF4D1V9A%3D&reserved=0, or mute the threadhttps://nam04.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2Fnotifications%2Funsubscribe-auth%2FAkggoJmXPe2nqAy9KzR4irgoa2jDEYGvks5t8lHrgaJpZM4T8DYa&data=02%7C01%7C%7C6a6e7dae8754436ac47708d5d1ef59fa%7C84df9e7fe9f640afb435aaaaaaaaaaaa%7C1%7C0%7C636645748285072457&sdata=FDxoR8Ufv8iIqjAU2zR8YkaVTvL6s%2BOxK5XUfcqL3UU%3D&reserved=0.
To how it may concern I not sure what you talking about it may been in my computer when My computer crash I am trying to learn don't know if I can if I lost it then I polishes . it is a little hard to learn by videos but that’s the way I have trial oh I must miss it or on the other video

                                                                   Thanks Boomer

[brentschmaltz]

@BoomerHudson @stamminator @infoberg noted, we haven't produced good docs.
https://github.com/AzureAD/azure-activedirectory-identitymodel-extensions-for-dotnet/wiki

This is a start.

Each time I am asked for sample code, I put it here:
https://github.com/brentschmaltz/IdentityModel

[stamminator]

@brentschmaltz I appreciate the start, and the acknowledgement of the documentation issue. Is there a plan in place for getting proper documentation up to speed in general?

[brentschmaltz]

@stamminator We are at the planing stage for the doc work.

What would be most helpful for you?

[stamminator]

@brentschmaltz Well I only have my anecdotal example — I don't know what's being asked for in general — but I would say anything related to working with JWTs in a future-proof way. My use case was trying to encrypt a JWT using System.IdentityModel.Tokens.Jwt. The only solution I could find is not workable (as far as I know) for .NET Core, so when we move to that framework, we'll be forced to redo our entire JWT signing/handing implementation using something like jose-jwt.

[infoberg]

@brentschmaltz I would love to see samples and in-depth documentation on JWE

[brentschmaltz]

@stamminator @infoberg I am heading out for a week on vacation. I looked at the SO above, we can do better than that.
If you open an issue asking for a samples for different flavors of JWE (dir, keywrap, ect) we will get it done for 5.2.5 currently slated for Aug 10th.

[stamminator]

@brentschmaltz Thanks for your hard work. Enjoy vacation!

[mhamri]

@brentschmaltz I checked all the samples and in all of them they are working with azure! the sample for a simple web api with angular frontend that doesn't need azure backend is missing. special parts that i was looking for was token generation and user sign-in. in all the scenario, samples are delegating this tak to a third party issuer (azure/oAuth2) which both is not working for me.

[brentschmaltz]

@mhamri can you remind me of what you are looking for?

[laura-rodriguez]

Hi @brentschmaltz,
As per OpenId Connect spec:
_The alg value SHOULD be the default of RS256 or the algorithm sent by the Client in the id_token_signed_response_alg parameter during Registration._
Where exactly is this validated? In my case, I want to accept only tokens with alg equals to RS256.
Can you please point me where this validation is being made?

[Thiagopc]

Where have documentation System.IdentityModel.Tokens.Jwt?
A long time has passed!

[brentschmaltz]

@Thiagopc we started with this: https://github.com/AzureAD/azure-activedirectory-identitymodel-extensions-for-dotnet/wiki/Supported-Algorithms

We are adding a section for Crypto extensibility.

[brentschmaltz]

@laura-rodriguez you are correct in the sense we don't explicitly check, we can add an option to check when calling OpenIdConnectProtocolValidator.

Although, the normal pattern of using discovery, makes me wonder why we need to do this?

[mairaw]

I transferred this issue to the dotnet-api-docs repo but this issue is beyond the scope of work of our team. @brentschmaltz is there a better place to move this issue?

[brentschmaltz]

@jmprieur
Should we put our docs here?
https://docs.microsoft.com/en-us/azure/active-directory/develop/msal-overview

[jmprieur]

Which kind of doc, @brentschmaltz : a reference doc for Wilson? It's already referenced from https://docs.microsoft.com/en-us/azure/active-directory/develop/reference-v2-libraries#microsoft-supported-server-middleware-libraries.

Or are we talking of a conceptual doc (that we'd need to create?)

[brentschmaltz]

@jmprieur conceptual mainly.
To help with these types of questions?

[MisinformedDNA]

Add this on: What properties need to be set in TokenValidationParameters? I search the web for hours and determined that I needed to set IssuerSigningKey and ValidateIssuerSigningKey (at least). Then I run into opposite advice and I'm confused as to what I'm supposed to do instead. Not expecting a solution here, but, my gosh, why does it have to be this difficult?

[brentschmaltz]

@MisinformedDNA we have this wiki on token validation: https://github.com/AzureAD/azure-activedirectory-identitymodel-extensions-for-dotnet/wiki/ValidatingTokens
See if this helps.