Authorize with a specific scheme article overhaul - #37439
Conversation
There was a problem hiding this comment.
Pull request overview
This PR modernizes the “Authorize with a specific scheme” documentation by replacing the older limitingidentitybyscheme.md article with a new authorize-with-a-specific-scheme.md article, adding a redirection for the old URL, and updating cross-references and terminology across related docs.
Changes:
- Replaced
limitingidentitybyscheme.mdwith a newauthorize-with-a-specific-scheme.mdarticle and added a redirection entry for the old URL. - Updated multiple docs to use consistent “JWT Bearer” / “Bearer” terminology and refreshed related content (policy schemes, MFA wording, routing references).
- Updated DocFX localization exclusions (
no-loc) for “Bearer”/“Cookies”/“JWT Bearer”.
Reviewed changes
Copilot reviewed 26 out of 26 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
| aspnetcore/web-api/http-repl/index.md | Terminology update for JWT Bearer tokens. |
| aspnetcore/tutorials/web-api-help-pages-using-swagger.md | Terminology update for JWT Bearer token wording. |
| aspnetcore/security/authorization/policies.md | Terminology update for JWT Bearer token wording in cURL guidance. |
| aspnetcore/security/authorization/limitingidentitybyscheme.md | Deleted legacy article (superseded by new article + redirect). |
| aspnetcore/security/authorization/custom-authorization-policies-with-iauthorizationrequirementdata.md | Updated JWT Bearer terminology in narrative steps. |
| aspnetcore/security/authorization/authorize-with-a-specific-scheme.md | New replacement article (key overhaul + new examples). |
| aspnetcore/security/authentication/policyschemes.md | Updated date and added clearer forwarding-order guidance + xrefs. |
| aspnetcore/security/authentication/mfa.md | Renamed to “Multi-factor” and refreshed wording/date. |
| aspnetcore/security/authentication/index.md | Updated xrefs to the replacement article + JWT Bearer terminology. |
| aspnetcore/security/authentication/cookie.md | Updated xrefs to the replacement article. |
| aspnetcore/security/authentication/configure-jwt-bearer-authentication.md | Updated headings/terminology around JWT Bearer authentication. |
| aspnetcore/mvc/security/authorization/custom-authorization-policies-with-iauthorizationrequirementdata-in-mvc.md | Updated JWT Bearer terminology in testing guidance. |
| aspnetcore/fundamentals/servers/yarp/authn-authz.md | Updated wording to JWT Bearer token. |
| aspnetcore/fundamentals/routing/includes/routing3-7.md | Updated routing metadata links to the new article/anchors. |
| aspnetcore/fundamentals/routing.md | Updated routing metadata link + front-matter date. |
| aspnetcore/fundamentals/openapi/includes/customize-openapi9.md | Updated JWT Bearer-related wording. |
| aspnetcore/fundamentals/openapi/customize-openapi.md | Updated JWT Bearer-related wording. |
| aspnetcore/fundamentals/minimal-apis/security.md | Updated JWT Bearer terminology in authentication strategy section. |
| aspnetcore/docfx.json | Added “Bearer”, “Cookies”, and “JWT Bearer” to no-loc list. |
| aspnetcore/blazor/security/webassembly/hosted-with-microsoft-entra-id.md | Updated JWT Bearer terminology. |
| aspnetcore/blazor/security/webassembly/hosted-with-identity-server.md | Updated JWT Bearer terminology. |
| aspnetcore/blazor/security/webassembly/hosted-with-azure-active-directory-b2c.md | Updated JWT Bearer terminology. |
| aspnetcore/blazor/security/index.md | Updated “multi-factor authentication” wording. |
| aspnetcore/blazor/security/blazor-web-app-with-oidc.md | Updated JWT Bearer terminology. |
| aspnetcore/blazor/security/blazor-web-app-with-entra.md | Updated JWT Bearer terminology. |
| .openpublishing.redirection.json | Added redirect from old article path to new article path. |
Suppressed comments (6)
aspnetcore/security/authorization/authorize-with-a-specific-scheme.md:82
- The xref for
WithMetadatapoints toMicrosoft.Teams.Cards.AdaptiveCard.WithMetadata, which is unrelated to Minimal APIs and will likely resolve to the wrong API (or fail to resolve).
For a Minimal API endpoint, use the xref:Microsoft.AspNetCore.Authorization.AuthorizeAttribute in a xref:Microsoft.Teams.Cards.AdaptiveCard.WithMetadata%2A call to set the schemes:
aspnetcore/security/authorization/authorize-with-a-specific-scheme.md:103
AuthorizationPolicyBuilder.AddAuthenticationSchemesexpects individual scheme names (params array). Passing a single comma-delimited string will register one scheme name containing a comma, not two schemes.
.RequireAuthorization(policy =>
policy.AddAuthenticationSchemes(
CookieAuthenticationDefaults.AuthenticationScheme + "," +
JwtBearerDefaults.AuthenticationScheme));
**aspnetcore/security/authorization/authorize-with-a-specific-scheme.md:148**
* `Microsoft.Net.Http.Server.AuthenticationSchemes` doesn’t appear to be the right API for ASP.NET Core authorization policies here. The code uses `policy.AuthenticationSchemes`, so the text should refer to that collection instead of an unrelated xref.
If you prefer to specify the desired schemes in a policy, set the xref:Microsoft.Net.Http.Server.AuthenticationSchemes collection when adding the policy.
In the following example, the Over18 policy only runs against the identity created by the JWT Bearer handler (xref:Microsoft.AspNetCore.Authentication.JwtBearer.JwtBearerDefaults.AuthenticationScheme%2A?displayProperty=nameWithType). For an example of the MinimumAgeRequirement class used in the following example, see xref:security/authorization/policies. The xref:Microsoft.AspNetCore.Authorization.AuthorizationPolicyBuilder.RequireAuthenticatedUser%2A method enforces user authentication to endpoints where the policy is applied.
**aspnetcore/security/authorization/authorize-with-a-specific-scheme.md:238**
* The interaction between schemes specified on `[Authorize]` and schemes specified by policy is described as “combined” but doesn’t explicitly state the effect (union/any-succeeds). Given the security implications, it would help to be explicit about the resulting behavior.
[Authorize] attribute scheme and policy scheme interaction
The authorization schemes for an endpoint with one or more Authorize attributes and one or more policy-based schemes are combined to set the final set of permitted schemes for the endpoint.
**aspnetcore/fundamentals/minimal-apis/security.md:101**
* This section mixes “JWT Bearer” casing with “JWT-bearer” in the same block, which is inconsistent with the terminology used elsewhere in the article.
This issue also appears on line 129 of the same file.
In the Program.cs file, two JWT Bearer-based authentication strategies are registered with the following scheme names:
- "Bearer"
- "LocalAuthIssuer"
"Bearer" is the typical default scheme in JWT-bearer based enabled apps. However, you can override the default scheme by setting the DefaultScheme property as shown in the previous example.
**aspnetcore/fundamentals/minimal-apis/security.md:133**
* The first sentence uses “JWT-bearer based authentication” while the next sentence uses “JWT Bearer-based authentication”. The first sentence should match the updated terminology.
Use 'dotnet user-jwts' for development testing
The examples in this article use an app configured with JWT-bearer based authentication. JWT Bearer-based authentication requires clients to present a token in the request header, which is used to validate their identity and claims. Typically, a central authority like an identity server issues the tokens.
For development on the local machine, the dotnet user-jwts command-line tool can be used to create bearer tokens.
</details>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Co-authored-by: Luke Latham <1622880+guardrex@users.noreply.github.com>
Fixes #35819
Fixes #36615
Fixes #35027
Addresses #35801
Wade, Tom ... Stephen is crazy busy 😅 and probably won't have time to look at this. Let's try Copilot and putting our heads together on this to get it across the finish line.
Notes ...
Question: I'd like to drop the sample app for this totally. It's old ... it's clunky ... it's MVC ... and this coverage probably isn't enhanced all that much by hosting a sample that doesn't fully work OOB. It's only really providing code that is easily inlined, as you can see on the PR diff. Should I drop it completely, or should I move it to the samples repo? I hope you'll just let me 💀 it.
Internal previews
Toggle expand/collapse