Clarify DefaultPolicy and FallbackPolicy Behavior in XML Docs

[shethaadit]

Description

This PR updates the XML documentation for DefaultPolicy and FallbackPolicy in the AuthorizationPolicy class to provide clearer explanations of when each policy applies.

Changes:

• FallbackPolicy:

  • Clarifies that it only applies when no authorization metadata is present (e.g., no [Authorize] attributes or RequireAuthorization() calls).
  • Explains why it is not used when an [Authorize] attribute is present without a policy name.
  • Emphasizes that it is primarily relevant for middleware-based authorization.

• DefaultPolicy:

  • States that it applies whenever authorization is required but no specific policy is set.
  • Clarifies that an [Authorize] attribute without a policy name will always use DefaultPolicy instead of FallbackPolicy.
  • Provides guidance on explicitly defining policies to avoid confusion.

Why This Change?

• Addresses user concerns about unexpected behavior when using [Authorize] without a policy name.
• Ensures developers understand when FallbackPolicy is ignored and why DefaultPolicy takes precedence.
• Prevents security risks due to misinterpretations of policy precedence.

Fixes #60452

[Copilot]

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

Comments suppressed due to low confidence (1)

src/Security/Authorization/Core/src/AuthorizationOptions.cs:30

• [nitpick] Consider using XML elements instead of backticks to mark inline code (e.g., policy names) for improved clarity in XML documentation.

/// - The `DefaultPolicy` applies whenever authorization is required, but no specific policy is set.

[halter73]

Thanks! This looks like a big improvement.

Part of me wanted to continue to cross-reference IAuthorizeData for completeness, but most consumers of the API won't have any familiarity with that and are better served by the new mentions to [Authorize] and RequireAuthorization().

[shethaadit]

Hi @halter73, Than you for all suggestions. I have committed them. Could you please re-approve and merge?

[shethaadit]

Hi @halter73, Than you for all suggestions. I have committed them. Could you please re-approve and merge?

Hi @halter73, a gentle reminder on this. :)

[halter73]

Thank you!