Overhaul custom authz policy provider article

[guardrex]

Fixes #37370
Fixes #19611
Fixes #34469
Addresses #35801

Notes

• Overhauls the policy providers article with a shift to Blazor/Minimal APIs.
• Fixes two long-standing issues on the repo for this article.
• Recommend that we rename this file to get a little more SEO juice, so I'm drafting it with custom-authorization-policy-providers.md, and I like to match the UID for such changes.
• I re-organize and expand the explanations of the API and examples of the original coverage (live article). The goals are to ...
  • Provide more guidance on IAuthorizationPolicyProvider in a single reference section and not have it sprinkled down into other sections of the article later, which is more like what I would expect a tutorial to do. I also think that we need to bring more of the (hidden) framework code remarks into the article.
  • Explain out the general process of developing a custom authz attribute and custom provider in a bit more detail.
• The sample code in the BlazorWebAppAuthorization sample app is shown inline for easy reviewing of this PR. I'll pull that sample code out of the article before merging this PR.

🦖 NOTE TO SELF 🦖 - Remove the inline code before merging this PR!

API cross-links ...

• https://github.com/dotnet/aspnetcore/blob/main/src/Security/Authorization/Core/src/DefaultAuthorizationPolicyProvider.cs
• https://github.com/dotnet/aspnetcore/blob/main/src/Security/Authorization/Core/src/AuthorizationOptions.cs#L35
• https://github.com/dotnet/aspnetcore/blob/main/src/Security/samples/CustomPolicyProvider/Authorization/MinimumAgePolicyProvider.cs

---

Internal previews

File	Preview link
.openpublishing.redirection.json	.openpublishing.redirection.json
aspnetcore/includes/git-download.md	aspnetcore/includes/git-download
aspnetcore/security/authorization/custom-authorization-policy-providers.md	aspnetcore/security/authorization/custom-authorization-policy-providers
aspnetcore/security/authorization/policies.md	aspnetcore/security/authorization/policies
aspnetcore/toc.yml	aspnetcore/toc

[Copilot]

Pull request overview

This pull request overhauls the existing authorization policy provider documentation by renaming/replacing the old iauthorizationpolicyprovider.md article with a new, expanded article focused on Blazor Web Apps and Minimal APIs, and updates navigation and redirections accordingly.

Changes:

• Replaces the old security/authorization/iauthorizationpolicyprovider article with security/authorization/custom-authorization-policy-providers and updates TOC + cross-references.
• Adds a redirection from the deleted article path to the new article path.
• Updates the shared git-download include content used by the new article.

Reviewed changes

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

Show a summary per file

File	Description
aspnetcore/toc.yml	Updates TOC entry to point to the new article UID.
aspnetcore/security/authorization/policies.md	Updates the cross-reference to the renamed policy provider article.
aspnetcore/security/authorization/iauthorizationpolicyprovider.md	Deletes the old article in favor of the new replacement article.
aspnetcore/security/authorization/custom-authorization-policy-providers.md	Adds the new, expanded replacement article content.
aspnetcore/includes/git-download.md	Updates the sparse-checkout tip content used by the new article.
.openpublishing.redirection.json	Adds a redirect from the deleted article path to the new article path.

Comments suppressed due to low confidence (1)

aspnetcore/security/authorization/custom-authorization-policy-providers.md:152

• The :::code directive already inserts the referenced sample file, but the article also includes a second, inline copy of the same code plus a "DOC REVIEWER NOTE" that says it will be removed. This will duplicate content in the rendered article and should be cleaned up before merge (keep either :::code or the inline copy, but not both).

:::code language="csharp" source="~/../AspNetCore.Docs.Samples/security/authorization/BlazorWebAppAuthorization/Policies/Attributes/MinimumAgeAuthorizeAttribute.cs":::

<!-- DOC REVIEWER NOTE: The preceding cross-link inserts the following code.
                        The following code will be removed prior to merging
                        the PR.

[wadepickett]

Approved, but recommended some minor changes inline. I will watch for a re-review request.

[wadepickett]

@guardrex, looks great, approved.

[guardrex]

Thanks, @wadepickett. I made one more change ........

I want to make it clear that the dev still needs a minimum age requirement and handler for the policy. I flesh it out in two relevant spots:

• Where the attribute is discussed ... at the end of that section ... called out in an IMPORTANT note.
• Where use of the policy/custom policy provider is discussed ... called out inline with the service registration remarks and the examples of how to use the custom policy provider.

... and instead of a whole-article cross-link, as I had before, I cross-link them directly to the relevant bits in the three sections of the Policy-based authz article, which should speed them up implementing these bits. 🏃‍♂️

By calling it out in both spots, it's unlikely that a dev will miss the remarks. If they were to miss them, the article's API just won't work ... no-op I think ... and we'll end up getting issues about it that we'd rather not have given our workload ⛏️😅.

BTW ... Stephen says he has time this week to look this over. I recommend waiting to see what changes he wants to make, and then I'll request another review from you.