Merge pull request #36690 from dotnet/main

Merge to Live

Author: wadepickett

aspnetcore/security/authorization/claims.md

@@ -4,14 +4,85 @@ author: wadepickett
 description: Learn how to add claims checks for authorization in an ASP.NET Core app.
 ms.author: wpickett
 monikerRange: '>= aspnetcore-3.1'
-ms.date: 11/26/2021
+ms.date: 01/22/2026
 uid: security/authorization/claims
+ai-usage: ai-assisted
 ---
 # Claims-based authorization in ASP.NET Core
 
 <a name="security-authorization-claims-based"></a>
 
-:::moniker range=">= aspnetcore-6.0"
+:::moniker range=">= aspnetcore-7.0"
+
+When an identity is created it may be assigned one or more claims issued by a trusted party. A claim is a name value pair that represents what the subject is, not what the subject can do. For example, you may have a driver's license, issued by a local driving license authority. Your driver's license has your date of birth on it. In this case the claim name would be `DateOfBirth`, the claim value would be your date of birth, for example `8th June 1970` and the issuer would be the driving license authority. Claims-based authorization, at its simplest, checks the value of a claim and allows access to a resource based upon that value. For example if you want access to a night club the authorization process might be:
+
+The door security officer would evaluate the value of your date of birth claim and whether they trust the issuer (the driving license authority) before granting you access.
+
+An identity can contain multiple claims with multiple values and can contain multiple claims of the same type.
+
+## Adding claims checks
+
+Claim-based authorization checks:
+
+* Are declarative.
+* Are applied to Razor Pages, controllers, or actions within a controller.
+* Can ***not*** be applied at the Razor Page handler level, they must be applied to the Page.
+
+Claims in code specify claims which the current user must possess, and optionally the value the claim must hold to access the requested resource. Claims requirements are policy based; the developer must build and register a policy expressing the claims requirements.
+
+The simplest type of claim policy looks for the presence of a claim and doesn't check the value.
+
+Build and register the policy and call <xref:Microsoft.AspNetCore.Builder.AuthorizationAppBuilderExtensions.UseAuthorization%2A>. Registering the policy takes place as part of the Authorization service configuration, typically in the `Program.cs` file:
+
+[!code-csharp[](~/security/authorization/claims/samples/7.x/WebAll/Program.cs?name=snippet&highlight=6-7,21)]
+
+In this case the `EmployeeOnly` policy checks for the presence of an `EmployeeNumber` claim on the current identity.
+
+Apply the policy using the `Policy` property on the [`[Authorize]`](xref:Microsoft.AspNetCore.Authorization.AuthorizeAttribute) attribute to specify the policy name.
+
+[!code-csharp[](~/security/authorization/claims/samples/7.x/WebAll/Controllers/Home2Controller.cs?name=snippet&highlight=1)]
+
+The `[Authorize]` attribute can be applied to an entire controller or Razor Page, in which case only identities matching the policy are allowed access to any Action on the controller.
+
+[!code-csharp[](~/security/authorization/claims/samples/7.x/WebAll/Controllers/VacationController.cs?name=snippet&highlight=1)]
+
+The following code applies the `[Authorize]` attribute to a Razor Page:
+
+[!code-csharp[](~/security/authorization/claims/samples/7.x/WebAll/Pages/Index.cshtml.cs?name=snippet&highlight=1)]
+
+Policies can ***not*** be applied at the Razor Page handler level, they must be applied to the Page.
+
+If you have a controller that's protected by the `[Authorize]` attribute but want to allow anonymous access to particular actions, you apply the `AllowAnonymousAttribute` attribute.
+
+[!code-csharp[](~/security/authorization/claims/samples/7.x/WebAll/Controllers/VacationController.cs?name=snippet&highlight=14)]
+
+Because policies can ***not*** be applied at the Razor Page handler level, we recommend using a controller when policies must be applied at the page handler level. The rest of the app that doesn't require policies at the Razor Page handler level can use Razor Pages.
+
+Most claims come with a value. You can specify a list of allowed values when creating the policy. The following example would only succeed for employees whose employee number was 1, 2, 3, 4, or 5.
+
+[!code-csharp[](~/security/authorization/claims/samples/7.x/WebAll/Program.cs?name=snippet2&highlight=6-8)]
+
+### Add a generic claim check
+
+If the claim value isn't a single value or a transformation is required, use <xref:Microsoft.AspNetCore.Authorization.AuthorizationPolicyBuilder.RequireAssertion%2A>. For more information, see [Use a func to fulfill a policy](xref:security/authorization/policies#use-a-func-to-fulfill-a-policy).
+
+## Multiple Policy Evaluation
+
+If multiple policies are applied at the controller and action levels, ***all*** policies must pass before access is granted:
+
+[!code-csharp[](~/security/authorization/claims/samples/7.x/WebAll/Controllers/SalaryController.cs?name=snippet&highlight=1,14)]
+
+In the preceding example any identity which fulfills the `EmployeeOnly` policy can access the `Payslip` action as that policy is enforced on the controller. However, in order to call the `UpdateSalary` action the identity must fulfill *both* the `EmployeeOnly` policy and the `HumanResources` policy.
+
+If you want more complicated policies, such as taking a date of birth claim, calculating an age from it, and then checking that the age is 21 or older, then you need to write [custom policy handlers](xref:security/authorization/policies).
+
+In the following sample, both page handler methods must fulfill *both* the `EmployeeOnly` policy and the `HumanResources` policy:
+
+[!code-csharp[](~/security/authorization/claims/samples/7.x/WebAll/Pages/X/Salary.cshtml.cs?name=snippet&highlight=1,2)]
+
+:::moniker-end
+
+:::moniker range="= aspnetcore-6.0"
 
 When an identity is created it may be assigned one or more claims issued by a trusted party. A claim is a name value pair that represents what the subject is, not what the subject can do. For example, you may have a driver's license, issued by a local driving license authority. Your driver's license has your date of birth on it. In this case the claim name would be `DateOfBirth`, the claim value would be your date of birth, for example `8th June 1970` and the issuer would be the driving license authority. Claims-based authorization, at its simplest, checks the value of a claim and allows access to a resource based upon that value. For example if you want access to a night club the authorization process might be:
 

aspnetcore/security/authorization/claims/samples/7.x/WebAll/Controllers/Home2Controller.cs

@@ -0,0 +1,41 @@
+using Microsoft.AspNetCore.Authorization;
+using Microsoft.AspNetCore.Mvc;
+using System.Diagnostics;
+using WebAll.Models;
+
+namespace WebAll.Controllers
+{
+    public class Home2Controller : Controller
+    {
+        private readonly ILogger<Home2Controller> _logger;
+
+        public Home2Controller(ILogger<Home2Controller> logger)
+        {
+            _logger = logger;
+        }
+
+        public IActionResult Index()
+        {
+            return View();
+        }
+
+        public IActionResult Privacy()
+        {
+            return View();
+        }
+
+        #region snippet
+        [Authorize(Policy = "EmployeeOnly")]
+        public IActionResult VacationBalance()
+        {
+            return View();
+        }
+        #endregion
+
+        [ResponseCache(Duration = 0, Location = ResponseCacheLocation.None, NoStore = true)]
+        public IActionResult Error()
+        {
+            return View(new ErrorViewModel { RequestId = Activity.Current?.Id ?? HttpContext.TraceIdentifier });
+        }
+    }
+}

aspnetcore/security/authorization/claims/samples/7.x/WebAll/Controllers/SalaryController.cs

@@ -0,0 +1,27 @@
+using Microsoft.AspNetCore.Authorization;
+using Microsoft.AspNetCore.Mvc;
+
+namespace WebAll.Controllers
+{
+    #region snippet
+    [Authorize(Policy = "EmployeeOnly")]
+    public class SalaryController : Controller
+    {
+        public IActionResult Index()
+        {
+            return View();
+        }
+
+        public IActionResult Payslip()
+        {
+            return View();
+        }
+
+        [Authorize(Policy = "HumanResources")]
+        public IActionResult UpdateSalary()
+        {
+            return View();
+        }
+    }
+    #endregion
+}

aspnetcore/security/authorization/claims/samples/7.x/WebAll/Controllers/VacationController.cs

@@ -0,0 +1,29 @@
+using Microsoft.AspNetCore.Authorization;
+using Microsoft.AspNetCore.Mvc;
+
+namespace WebAll.Controllers
+{
+    #region snippet
+    #region snippet2
+    [Authorize(Policy = "EmployeeOnly")]
+    public class VacationController : Controller
+    {
+        public IActionResult Index()
+        {
+            return View();
+        }
+
+        public ActionResult VacationBalance()
+        {
+            return View();
+        }
+        #endregion
+
+        [AllowAnonymous]
+        public ActionResult VacationPolicy()
+        {
+            return View();
+        }
+    }
+    #endregion
+}

aspnetcore/security/authorization/claims/samples/7.x/WebAll/Models/ErrorViewModel.cs

@@ -0,0 +1,9 @@
+namespace WebAll.Models
+{
+    public class ErrorViewModel
+    {
+        public string? RequestId { get; set; }
+
+        public bool ShowRequestId => !string.IsNullOrEmpty(RequestId);
+    }
+}

aspnetcore/security/authorization/claims/samples/7.x/WebAll/Pages/Error.cshtml

@@ -0,0 +1,26 @@
+@page
+@model ErrorModel
+@{
+    ViewData["Title"] = "Error";
+}
+
+<h1 class="text-danger">Error.</h1>
+<h2 class="text-danger">An error occurred while processing your request.</h2>
+
+@if (Model.ShowRequestId)
+{
+    <p>
+        <strong>Request ID:</strong> <code>@Model.RequestId</code>
+    </p>
+}
+
+<h3>Development Mode</h3>
+<p>
+    Swapping to the <strong>Development</strong> environment displays detailed information about the error that occurred.
+</p>
+<p>
+    <strong>The Development environment shouldn't be enabled for deployed applications.</strong>
+    It can result in displaying sensitive information from exceptions to end users.
+    For local debugging, enable the <strong>Development</strong> environment by setting the <strong>ASPNETCORE_ENVIRONMENT</strong> environment variable to <strong>Development</strong>
+    and restarting the app.
+</p>

aspnetcore/security/authorization/claims/samples/7.x/WebAll/Pages/Error.cshtml.cs

@@ -0,0 +1,27 @@
+using Microsoft.AspNetCore.Mvc;
+using Microsoft.AspNetCore.Mvc.RazorPages;
+using System.Diagnostics;
+
+namespace WebAll.Pages
+{
+    [ResponseCache(Duration = 0, Location = ResponseCacheLocation.None, NoStore = true)]
+    [IgnoreAntiforgeryToken]
+    public class ErrorModel : PageModel
+    {
+        public string? RequestId { get; set; }
+
+        public bool ShowRequestId => !string.IsNullOrEmpty(RequestId);
+
+        private readonly ILogger<ErrorModel> _logger;
+
+        public ErrorModel(ILogger<ErrorModel> logger)
+        {
+            _logger = logger;
+        }
+
+        public void OnGet()
+        {
+            RequestId = Activity.Current?.Id ?? HttpContext.TraceIdentifier;
+        }
+    }
+}

aspnetcore/security/authorization/claims/samples/7.x/WebAll/Pages/Index.cshtml

@@ -0,0 +1,10 @@
+@page
+@model IndexModel
+@{
+    ViewData["Title"] = "RP Home page";
+}
+
+<div class="text-center">
+    <h1 class="display-4">RP pages Welcome</h1>
+    <p>Learn about <a href="https://docs.microsoft.com/aspnet/core">building Web apps with ASP.NET Core</a>.</p>
+</div>

aspnetcore/security/authorization/claims/samples/7.x/WebAll/Pages/Index.cshtml.cs

@@ -0,0 +1,16 @@
+using Microsoft.AspNetCore.Authorization;
+using Microsoft.AspNetCore.Mvc.RazorPages;
+
+namespace WebAll.Pages
+{
+    #region snippet
+    [Authorize(Policy = "EmployeeOnly")]
+    public class IndexModel : PageModel
+    {
+        public void OnGet()
+        {
+
+        }
+    }
+    #endregion
+}

aspnetcore/security/authorization/claims/samples/7.x/WebAll/Pages/Privacy.cshtml

@@ -0,0 +1,8 @@
+@page
+@model PrivacyModel
+@{
+    ViewData["Title"] = "RP Privacy Policy";
+}
+<h1>@ViewData["Title"]</h1>
+
+<p>RP: Use this page to detail your site's privacy policy.</p>