ClaimsPrincipalPermission Class

.NET Framework 4.5

Represents a permission that uses a ClaimsAuthorizationManager implementation to determine if access to a resource should be granted to the active principal. This class cannot be inherited.

System.Object
  System.IdentityModel.Services.ClaimsPrincipalPermission

Namespace:  System.IdentityModel.Services
Assembly:  System.IdentityModel.Services (in System.IdentityModel.Services.dll)

[SerializableAttribute]
public sealed class ClaimsPrincipalPermission : IPermission, 
	ISecurityEncodable, IUnrestrictedPermission

The ClaimsPrincipalPermission type exposes the following members.

  NameDescription
Public methodClaimsPrincipalPermissionCreates a new instance of the ClaimsPrincipalPermission class.
Top

  NameDescription
Public methodStatic memberCheckAccessChecks if the current principal is authorized to perform the specified action on the specified resource.
Public methodCopyReturns a copy of the current ClaimsPrincipalPermission instance.
Public methodDemandChecks if the current principal is authorized for the resource-action pairs associated with the current instance.
Public methodEquals(Object)Determines whether the specified object is equal to the current object. (Inherited from Object.)
Public methodFromXmlReconstructs the current permission and its state from the specified XML encoding.
Public methodGetHashCodeServes as the default hash function. (Inherited from Object.)
Public methodGetTypeGets the Type of the current instance. (Inherited from Object.)
Public methodIntersectReturns a permission that is the intersection of the current permission and the specified permission.
Public methodIsSubsetOfReturns a value that indicates whether current permission is a subset of the specified permission.
Public methodIsUnrestrictedReturns a value that indicates whether the permission is unrestricted.
Public methodToStringReturns a string that represents the current object. (Inherited from Object.)
Public methodToXmlReturns the XML encoded form of the current permission and its state.
Public methodUnionReturns a new permission that is the union of the current permission and the specified permission. ClaimsPrincipalPermission object that has all of the resource-action pairs that are present in the current instance and the target instance.
Top

The ClaimsPrincipalPermission class provides the capability to perform imperative access checks by using the ClaimsAuthorizationManager that is configured for an application. By invoking the Demand method or the static CheckAccess method, you can provide protection to resources from within the execution path of your code according to the authorization policy defined for your claims authentication manager. Declarative access checks can be performed by using the ClaimsPrincipalPermissionAttribute class.

Important noteImportant

The ClaimsPrincipalPermission class uses the claims authorization manager configured by the IdentityConfiguration that is set under the FederatedAuthentication.FederationConfiguration property. This is true in all cases, even in scenarios where WS-Federation is not used; for example, active (WCF) Web applications and Console applications. You can specify the claims authorization manager either in configuration or programmatically. To specify the claims authorization manager in a configuration file, set the <claimsAuthorizationManager> element under an <identityConfiguration> element and ensure that this identity configuration is referenced by the <federationConfiguration> element that is loaded by the runtime (for example, by setting the identityConfigurationName attribute). To set the claims authorization manager programmatically, provide a handler for the FederatedAuthentication.FederationConfigurationCreated event.

On one level, the functionality provided by ClaimsPrincipalPermission is similar to the role-based access checks (RBAC) provided through the PrincipalPermission class; however, the ClaimsAuthorizationManager class performs checks based on the claims presented by the active principal. This enables far more granularity than is available through pure RBAC, where many permissions are typically collected under a single role. Perhaps, more importantly, claims-based authorization enables better separation of business logic and authorization policy because permission can be demanded for a specific action on a resource in code and back-end policy can be used to configure which claims the presenting entity must possess in order to satisfy the demand. Like RBAC, ClaimsPrincipalPermission performs a user-based access check, that is, unlike code access security implemented by classes that derive from the CodeAccessPermission class and use a stack walk to ensure that all callers of the code have been granted a permission, ClaimsPrincipalPermission performs its check only on the current principal.

The static CheckAccess method checks access for a specified action on a specified resource. The resource and action are both strings and are typically URIs. You can also initialize an instance of ClaimsPrincipalPermission with an action and a resource and call the Demand method. Although the constructor only takes a single resource and action, ClaimsPrincipalPermission objects can be combined through the Union and Intersect methods. A permission created by using these methods may contain multiple resource-action pairs.

Both methods determine access by invoking the ClaimsAuthorizationManager.CheckAccess method of the configured claims authorization manager with an AuthorizationContext composed of the active principal (Thread.CurrentPrincipal), the resource, and the action. They throw a SecurityException if the current principal is not authorized to perform the action on the resource; otherwise, execution proceeds.

In the case of a ClaimsPrincipalPermission that contains multiple resource-action pairs, the ClaimsAuthorizationManager.CheckAccess method is invoked for each of the resource-action pairs contained in the permission. For the call to Demand to succeed, the active principal must be authorized for all of the resource-action pairs contained in the permission.

The following example shows how to protect a resource by using the Demand method, the CheckAccess method, or a ClaimsPrincipalPermissionAttribute declaration. In each case, the configured ClaimsAuthorizationManager is invoked to evaluate the current principal against the specified resource and action. If the current principal is not authorized for the specified action on the specified resource, a SecurityException is thrown; otherwise, execution proceeds.

using System;
using System.Security.Permissions;
using System.Security.Principal;
using System.Threading;
using System.Security.Claims;
using System.IdentityModel.Services;

namespace ClaimsBasedAuthorization
{
    /// <summary> 
    /// Program illustrates using Claims-based authorization 
    /// </summary> 
    class Program
    {
        static void Main(string[] args)
        {
            // 
            // Method 1. Simple access check using static method.  
            // Expect this to be most common method. 
            //
            ClaimsPrincipalPermission.CheckAccess("resource", "action");

            // 
            // Method 2. Programmatic check using the permission class 
            // Follows model found at http://msdn.microsoft.com/en-us/library/system.security.permissions.principalpermission.aspx 
            //
            ClaimsPrincipalPermission cpp = new ClaimsPrincipalPermission("resource", "action");
            cpp.Demand();

            // 
            // Method 3. Access check interacting directly with the authorization manager. 
            //            
            ClaimsAuthorizationManager am = new ClaimsAuthorizationManager();
            am.CheckAccess(new AuthorizationContext((ClaimsPrincipal)Thread.CurrentPrincipal, "resource", "action"));

            // 
            // Method 4. Call a method that is protected using the permission attribute class 
            //
            ProtectedMethod();

            Console.WriteLine("Press [Enter] to continue.");
            Console.ReadLine();
        }

        // 
        // Declarative access check using the permission class. The caller must satisfy both demands. 
        //
        [ClaimsPrincipalPermission(SecurityAction.Demand, Resource = "resource", Operation = "action")]
        [ClaimsPrincipalPermission(SecurityAction.Demand, Resource = "resource1", Operation = "action1")]
        static void ProtectedMethod()
        {
        }
    }
}

The following XML shows the minimum configuration required to use a custom claims authorization manager with the ClaimsPrincipalPermission class. You must, at a minimum, declare both the system.identityModel and the system.identityModel.services sections in the <configSection> element and then specify your authorization manager in a <claimsAuthorizationManager> element under the default identity configuration. This will ensure that your authorization manager is referenced from the default federation configuration. Alternatively, you can specify the name of the identity configuration under which your authorization manager is specified in the identityConfigurationName attribute of the <federationConfiguration> element.

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <configSections>
    <!-- WIF configuration sections -->
    <section name="system.identityModel" type="System.IdentityModel.Configuration.SystemIdentityModelSection, System.IdentityModel, Version=4.0.0.0, Culture=neutral, PublicKeyToken=B77A5C561934E089"/>
    <section name="system.identityModel.services" type="System.IdentityModel.Services.Configuration.SystemIdentityModelServicesSection, System.IdentityModel.Services, Version=4.0.0.0, Culture=neutral, PublicKeyToken=B77A5C561934E089"/>
  </configSections>
  
  <startup>
    <supportedRuntime version="v4.0" sku=".NETFramework,Version=v4.5" />
  </startup>
  
  <system.identityModel>
    <identityConfiguration>
      <claimsAuthorizationManager type ="MyClaimsAuthorizationManager.MyClaimsAuthorizationManager, MyClaimsAuthorizationManager"/>
    </identityConfiguration>
  </system.identityModel>
  
</configuration>

.NET Framework

Supported in: 4.6, 4.5

Windows 8.1, Windows Server 2012 R2, Windows 8, Windows Server 2012, Windows 7, Windows Vista SP2, Windows Server 2008 (Server Core Role not supported), Windows Server 2008 R2 (Server Core Role supported with SP1 or later; Itanium not supported)

The .NET Framework does not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.
Was this page helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2014 Microsoft