Opaque (reference) access token guidance

[guardrex]

Fixes #36422

cc: @mikekistler

Stephen ... I hacked some nasty 🦖 code 🙈😆 with the help of AI to give you an idea of what I have in mind for the bits that call the auth server to validate the token.

Apparently, Entra doesn't support opaque access token validation, per this MS answer as of 2023 and a local test that I just ran here with Entra.

I originally had this in the BWA-OIDC article, but it's more general than that, so I just moved it to the additional scenarios article and cross-linked to it there from a few spots.

---

Internal previews

📄 File	🔗 Preview link
aspnetcore/blazor/security/additional-scenarios.md	aspnetcore/blazor/security/additional-scenarios
aspnetcore/blazor/security/blazor-web-app-with-entra.md	aspnetcore/blazor/security/blazor-web-app-with-entra
aspnetcore/blazor/security/blazor-web-app-with-oidc.md	aspnetcore/blazor/security/blazor-web-app-with-oidc
aspnetcore/blazor/security/index.md	aspnetcore/blazor/security/index

[Copilot]

Pull request overview

This PR adds comprehensive guidance for handling opaque (reference) access tokens in ASP.NET Core Blazor Web Apps with OIDC authentication, addressing issue #36422. The documentation explains when opaque tokens are supported by default and provides a starting-point implementation for scenarios requiring custom token validation.

Key Changes

• Explains that AddOpenIdConnect inherently supports opaque tokens for basic authentication scenarios without additional configuration
• Documents the limitation when opaque tokens need to be validated by services using AddJwtBearer
• Provides a custom AuthenticationHandler implementation as a starting point for developers who need to validate opaque tokens via introspection endpoints

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated 6 comments.

[damienbod]

Hi @guardrex nice work. If you are making docs about introspection, I think you should mention something about the revocation endpoint and that when using reference tokens, these are typically invalidated on a logout event using the revocation endpoint.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 3 comments.

[guardrex]

@halter73 ... There was considerable churn (nine commits) while updating this. It's best if you look at the latest version of the PR to determine if the updates are sane. Unfortunately, I can't squash the nine commits into one because the Copilot commit was a merge commit.

[guardrex]

@damienbod ... Would you review the updates? Stephen might be unavailable right now, and this PR is very close to being ready to merge. If you'll review the last couple of updates that I made per your suggestions, I'll ask Wade to look things over after that, and these updates can be published.

[damienbod]

LGTM, just adds 2 comments

[guardrex]

Thanks @damienbod! ... The NOTE is obviously going to be for advanced devs. I have nothing in our doc set that I can cross-link for that approach.

[guardrex]

@wadepickett ... @halter73 has gone MIA again! 😆 He's probably buried in code somewhere! I made all of his suggested updates, and @damienbod reviewed (thx again, Damien! 🙏). I think we're in good shape thus far. If we get your suggestions addressed, we can merge this. No rush tho ... it doesn't have to be today ... or even this week for that matter.

[halter73]

Only stage, and if you think it's good to go, feel free to leave no comments and tell me

[halter73]

I think this all looks good to merge. Sorry for all the repeated/stale review content! I should have noticed that before posting.