ClaimsPrincipalPermission Class

Reference

Definition

Namespace:: System.IdentityModel.Services

Assembly:: System.IdentityModel.Services.dll

Important

Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.

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.

public ref class ClaimsPrincipalPermission sealed : System::Security::IPermission, System::Security::Permissions::IUnrestrictedPermission

[System.Serializable]
public sealed class ClaimsPrincipalPermission : System.Security.IPermission, System.Security.Permissions.IUnrestrictedPermission

[<System.Serializable>]
type ClaimsPrincipalPermission = class
    interface IPermission
    interface ISecurityEncodable
    interface IUnrestrictedPermission

Public NotInheritable Class ClaimsPrincipalPermission
Implements IPermission, IUnrestrictedPermission

Inheritance: Object
ClaimsPrincipalPermission

Attributes: SerializableAttribute

Implements: IPermission ISecurityEncodable IUnrestrictedPermission

Examples

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.IdentityModel.Services;
using System.Security.Claims;
using System.Security.Permissions;
using System.Threading;

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/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>

Remarks

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

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.

Constructors

ClaimsPrincipalPermission(String, String)

Creates a new instance of the ClaimsPrincipalPermission class.

Methods

CheckAccess(String, String)	Checks if the current principal is authorized to perform the specified action on the specified resource.
Copy()	Returns a copy of the current ClaimsPrincipalPermission instance.
Demand()	Checks if the current principal is authorized for the resource-action pairs associated with the current instance.
Equals(Object)	Determines whether the specified object is equal to the current object. (Inherited from Object)
FromXml(SecurityElement)	Reconstructs the current permission and its state from the specified XML encoding.
GetHashCode()	Serves as the default hash function. (Inherited from Object)
GetType()	Gets the Type of the current instance. (Inherited from Object)
Intersect(IPermission)	Returns a permission that is the intersection of the current permission and the specified permission.
IsSubsetOf(IPermission)	Returns a value that indicates whether current permission is a subset of the specified permission.
IsUnrestricted()	Returns a value that indicates whether the permission is unrestricted.
MemberwiseClone()	Creates a shallow copy of the current Object. (Inherited from Object)
ToString()	Returns a string that represents the current object. (Inherited from Object)
ToXml()	Returns the XML encoded form of the current permission and its state.
Union(IPermission)	Returns 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.

Applies to

Deila með