Add doc pages for AddOpenIdConnect and AddJwtBearer specifically

[halter73]

Help us make content visible

• Tell us what search terms you used and how you searched docs.
  • ASP.NET Core OIDC
  • ASP.NET Core JWT Bearer
• Tell us what docs you found that didn't address your concern.
  • https://andrewlock.net/an-introduction-to-openid-connect-in-asp-net-core/ (too outdated)
  • https://devblogs.microsoft.com/dotnet/jwt-validation-and-authorization-in-asp-net-core/ (too outdated)
  • https://learn.microsoft.com/en-us/aspnet/core/blazor/security/blazor-web-app-with-oidc?view=aspnetcore-8.0&pivots=with-bff-pattern (too blazor specific)

Describe the new topic

• Explain why this topic is needed.

Currently in the TOC for ASP.NET Core Authentication, we have sections for Azure, cookie, Windows, cert, and WS-Fed auth, but nothing for generic OIDC or JWT bearer auth. ASP.NET Core's generic OIDC and JWT bearer auth handlers are used under the covers for Azure Entra auth on ASP.NET Core, but this is not clear from the documentation.

I think pointing this out would be enlightening to many customers, particularly the ones on Azure, because you can configure generic OpenIdConnectOptions and JwtBearerOptions when calling the Entra-specific AddMicrosoftIdentityWebApp and AddMicrosoftIdentityWebApi methods respectively.

And I think this will obviously be a big help to developers who are using something other than Entra as their OIDC provider. While documentation directly from third-party OIDC providers will likely be better in some ways because they can tell you step-by-step how to configure the provider, a lot of developers have a good understanding of OIDC and how to configure the provider, but just need help integrating with ASP.NET Core. And for those new to OIDC, we should link to https://learn.microsoft.com/en-us/entra/identity-platform/v2-protocols-oidc

• Suggest a location in the Table of Contents.

I recommend adding "Configure OIDC authentication" and "Configure JWT bearer authentication" right below "Configure cookie authentication" in the TOC below.

• Write an abstract. In one short paragraph, describe what this topic will cover.

For the OIDC doc, we could follow the outline of https://learn.microsoft.com/en-us/entra/identity-platform/scenario-web-app-sign-user-app-configuration?tabs=aspnetcore. Anything that's specific to how to configure the provider or acquire the client id or secret will be left as an exercise for the reader. Of course, we'll also cross-reference the Entra docs and recommend using Microsoft.Identity.Web instead of the generic handlers when working with Entra specifically.

For the JWT bearer doc, we could follow the outline of https://learn.microsoft.com/en-us/entra/identity-platform/scenario-protected-web-api-app-configuration?tabs=aspnetcore with the same caveat about recommending Microsoft.Identity.Web when working with Entra.

@andrewlock Has a great writeup about Microsoft.AspNetCore.Authentication.OpenIdConnect shortly after it came out, and it's what often comes up if you search "ASP.NET Core OIDC", but it's very outdated. I'm guessing he wouldn't mind if we used it for inspiration. But be warned, the UseOpenIdConnectAuthentication method no longer even exists.

Fortunately, the much more up-to-date Secure an ASP.NET Core Blazor Web App with OpenID Connect (OIDC) is starting to rank higher in search results, and that does demonstrate both AddOpenIdConnect and AddJwtBearer, but this shouldn't be hidden away deep in the Blazor docs. Not everyone needs to authenticate an auto-rendering Blazor app which does add complexity. The OIDC and JWT bearer handlers can be used directly in many different kinds of web apps.

• Create an outline for the new topic. We'll help review the outline and approve it before anyone writes a topic.

@guardrex @mikekistler @jennyf19 FYI

[damienbod]

I created almost the same issue:

See this issue: https://github.com/dotnet/AspNetCore.Docs/issues/30647

It has an outline already. I would add web because OIDC for non web is different.

I can do this if you want.

[damienbod]

@halter73 Also I have a lot of links to docs about this here:

https://github.com/damienbod/aspnetcore-standup-authn-authz

and here:

https://github.com/damienbod/aspnetcore-standup-securing-apis

[Rick-Anderson]

@damienbod

I can do this if you want.

That would be fantastic. Let me know how I can help.

[damienbod]

@Rick-Anderson Perfect. Once I get the feedback/ok from @halter73 , I will start. I have a structure of the doc in the linked issue, waiting for feedback there.

I will define a suggestion as well for the JWT doc.

Greetings Damien

[damienbod]

I start to implement the OIDC page

[damienbod]

Configure OIDC web authentication

PR: https://github.com/dotnet/AspNetCore.Docs/pull/33908