ASP.NET Core Identity and Auth documentation improvements

[mkArtakMSFT]

We plan to spend some time as a team to drive improvements in this area during .NET 10 timeframe.

[mikeholczer]

This would be great! I was recently trying to get authentication and authorization setup and working in a Blazor standalone webassembly app. I was founding various docs that were inconsistent with each other. I'll see if I can find the various doc links I found and post them here, but please include cleaning up existing docs in the effort, not just adding new docs on top of what's there.

[ahelland]

If you are a .NET developer looking for docs on identity and auth you invariably end up in different places:

• The .NET documentation
• The Entra ID documentation
• Specific library documentation (like Identity.Web and MSAL)

Some pieces clearly belong in one place or the other, but then there's some overlap. For instance Entra needs to offer code samples in multiple languages meaning that they offer .NET samples in parallell with what the .NET docs have in the same area. Concepts that are strongly tied to Entra features might be explained better than what can be expected by a .NET generalist, but you can also run across samples still using startup.cs which is confusing for a dev who've only been around for program.cs. The .NET docs in turn might approach the syntactical part differently.

(And you can also come across things like samples for identity related functionality leveraging Azure Functions where the in-proc model is used instead of isolated worker. But I guess that might be slightly out of scope in this discussion.)

This confusion extends further when you dive into the complete samples which are usually hosted in GitHub - should I look under github.com/azure/xyz or github.com/dotnet/xyz?

I guess this in part echoes what @mikeholczer said.

Best Practices
Sample code illustrating specific things should be clearly marked with "this is not production grade" when that is the case. (When I create samples I also skip non-essential things so it's not a concern in itself that some code is dev grade.) But what if I want to have production grade? If I want .NET code that uses a clientId and a clientSecret I can find a sample in no time. What if I want to use a certificate instead? Those samples are much harder to find.

Or let's say I'm real nerdy about identity and come across something like the RFC draft "OAuth 2.0 for Browser-Based Applications". How do I translate that into .NET code? There is an official .NET 9 BFF sample (which is good by the way) - can I assume the finer details was also considered in making that or is that something I am expected to figure out on my own? (I understand that most of the development will always be the dev's responsibility and MSFT cannot provide exact samples for every conceivable use case, but where secure defaults can be supplied they should.)

"Missing pieces"
Have you tried typing builder.Services.AddAuthentication(). and see the number of options IntelliSense provides? Should I use builder.Services.AddAuthentication().AddMicrosoftIdentityWebApp, or builder.Services.AddAuthentication().AddOpenIdConnect - what's the difference? And how does this relate to .AddCookie, .AddBearerToken and .AddJwtBearer? It's a rabbit hole of testing, debugging, searching the web for info and pulling your hair :)

"The bigger picture"
When living in dotnet-land (great place, btw) you can do fancy things like passing the auth state from Blazor server to Blazor WASM and everyone's happy. But at some point in time some frontend dev will say they want to do React and Next.js and the story falls apart. Also something that quickly extends past what the .NET team can solve, but how do I make the .NET backend bits right here? Should I just expose API endpoints, validate incoming JWTs and be happy? Or can I easily implement the B in BFF in .NET and have a "plug-in here" integration point to mediate tokens/sessions/what-have-you?

I can see how this comes across more ranty than concrete implementation tips, but currently I'm just trying to get the discussion going :)

[davidfowl]

There's lots of work to do here and the space is complex, but from my POV we need to "teach people how to fish". That is, teach you general auth concepts and relate them to various ASP.NET APIs. Once that part is done then you have a solid foundation in understanding how to begin to ask the right set of questions that will help you validate choices for your auth architecture. This is no different from any other part of your application and we can provide the building blocks for your understanding and some samples, but it is your job to design the auth system (putting all of the building blocks together) to accomplish your scenarios.

That said, we will definitely provide samples for the MOST popular patterns, explicitly calling out which ones "need more work" to be production ready and what that would entail.

PS: I want to acknowledge that the auth system is complex, even when you understand the general auth concepts, but we don't do a great job today mapping those 2 things together.

[ahelland]

Auth is hard and it's definitely not an area where I would give a junior dev access to the "push directly to prod" button. It's a full-time job keeping track of it all. Which applies to other areas of .NET as well. Who hasn't been burned by a migration gone wrong when getting started with Entity Framework? ;)

The job of understanding when to acquire a token and when to validate said token is best left to the developer/architect, and it's not necessarily the .NET team that should be explaining all the intricacies of different OAuth flows either. I do think however that Microsoft are better suited to provide correct implementations of the flows than a non-specialist dev. (If this is best handled by the .NET team or Entra teams internally isn't top of mind for most people on the outside.) Even good tools might require a user manual though.

I agree the approach should be teaching people to fish - the hard part is figuring out what is needed in addition to giving them driving directions to the nearest lake :) (And to be clear; there is also a distinction between what is suited for official docs and what works better as informal blog posts by the team and various community members.)

[davidfowl]

The job of understanding when to acquire a token and when to validate said token is best left to the developer/architect, and it's not necessarily the .NET team that should be explaining all the intricacies of different OAuth flows either. I do think however that Microsoft are better suited to provide correct implementations of the flows than a non-specialist dev. (If this is best handled by the .NET team or Entra teams internally isn't top of mind for most people on the outside.) Even good tools might require a user manual though.

I'll be frank and I don't think the .NET team is going to solve this problem. People build entire careers and companies around this specific domain.

There is no free lunch here. We're not going to turn you into an auth expert, if you want that guarantee then pay for a hosted service, otherwise, there will be lots of gap filling to do.

[ahelland]

No, no, to be clear - I don't expect the .NET team to turn me (or anyone else) into an identity expert or a database ninja or an SME in other coding related fields for that matter. That requires effort and time from the individual.

What I'm trying to highlight is that even if you know both C# and OAuth it can be daunting to go from builder.Services.AddAuthentication(). to a working web app if you're not able to find the docs and samples to nudge you along the way. (I'm not hung up on that particular line of code - that's just to exemplify.)

[guardrex]

@mikeholczer ... Instead of discussing your findings here, can you open the issue for me on the docs repo? Use the Open a documentation issue link/feedback form at the bottom of the article ...

https://learn.microsoft.com/aspnet/core/blazor/security/webassembly/

[mikeholczer]

@mikeholczer ... Instead of discussing your findings here, can you open the issue for me on the docs repo? Use the Open a documentation issue link/feedback form at the bottom of the article ...

https://learn.microsoft.com/aspnet/core/blazor/security/webassembly/

I created dotnet/AspNetCore.Docs#34743