ClaimsPrincipal Class

.NET Framework 4.5

An IPrincipal implementation that supports multiple claims-based identities.

Namespace:  System.Security.Claims
Assembly:  mscorlib (in mscorlib.dll)

[SerializableAttribute]
[ComVisibleAttribute(true)]
public class ClaimsPrincipal : IPrincipal

The ClaimsPrincipal type exposes the following members.

  NameDescription
Public methodClaimsPrincipal()Initializes a new instance of the ClaimsPrincipal class.
Public methodClaimsPrincipal(IEnumerable<ClaimsIdentity>)Initializes a new instance of the ClaimsPrincipal class using the specified claims identities.
Public methodClaimsPrincipal(IIdentity)Initializes a new instance of the ClaimsPrincipal class from the specified identity.
Public methodClaimsPrincipal(IPrincipal)Initializes a new instance of the ClaimsPrincipal class from the specified principal.
Protected methodClaimsPrincipal(SerializationInfo, StreamingContext)Initializes a new instance of the ClaimsPrincipal class from a serialized stream created by using ISerializable.
Top

  NameDescription
Public propertyClaimsGets a collection that contains all of the claims from all of the claims identities associated with this claims principal.
Public propertyStatic memberClaimsPrincipalSelectorGets and sets the delegate used to select the claims principal returned by the Current property.
Public propertyStatic memberCurrentGets the current claims principal.
Public propertyIdentitiesGets a collection that contains all of the claims identities associated with this claims principal.
Public propertyIdentityGets the primary claims identity associated with this claims principal.
Public propertyStatic memberPrimaryIdentitySelectorGets and sets the delegate used to select the claims identity returned by the Identity property.
Top

  NameDescription
Public methodAddIdentitiesAdds the specified claims identities to this claims principal.
Public methodAddIdentityAdds the specified claims identity to this claims principal.
Public methodEquals(Object)Determines whether the specified object is equal to the current object. (Inherited from Object.)
Protected methodFinalizeAllows an object to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection. (Inherited from Object.)
Public methodFindAll(Predicate<Claim>)Retrieves all of the claims that are matched by the specified predicate.
Public methodFindAll(String)Retrieves all or the claims that have the specified claim type.
Public methodFindFirst(Predicate<Claim>)Retrieves the first claim that is matched by the specified predicate.
Public methodFindFirst(String)Retrieves the first claim with the specified claim type.
Public methodGetHashCodeServes as the default hash function. (Inherited from Object.)
Protected methodGetObjectDataPopulates the SerializationInfo with data needed to serialize the current ClaimsPrincipal object.
Public methodGetTypeGets the Type of the current instance. (Inherited from Object.)
Public methodHasClaim(Predicate<Claim>)Determines whether any of the claims identities associated with this claims principal contains a claim that is matched by the specified predicate.
Public methodHasClaim(String, String)Determines whether any of the claims identities associated with this claims principal contains a claim with the specified claim type and value.
Public methodIsInRoleReturns a value that indicates whether the entity (user) represented by this claims principal is in the specified role.
Protected methodMemberwiseCloneCreates a shallow copy of the current Object. (Inherited from Object.)
Public methodToStringReturns a string that represents the current object. (Inherited from Object.)
Top

Beginning with .NET Framework 4.5, Windows Identity Foundation (WIF) and claims-based identity have been fully integrated into the .NET Framework. This means that many classes that represent a principal in the .NET Framework now derive from ClaimsPrincipal rather than simply implementing the IPrincipal interface. In addition to implementing the IPrincipal interface, ClaimsPrincipal exposes properties and methods that are useful for working with claims.

ClaimsPrincipal exposes a collection of identities, each of which is a ClaimsIdentity. In the common case, this collection, which is accessed through the Identities property, will only have a single element.

The introduction of ClaimsPrincipal in .NET 4.5 as the principal from which most principal classes derive does not force you to change anything in the way in which you deal with identity. It does, however open up more possibilities and offer more chances to exercise finer access control. For example:

  • The application code itself can work directly with the claims contained in the current principal to drive extra authentication, authorization, and personalization tasks.

  • You can front your resources with a claims processing pipeline, which can deal with authentication requests and authorization policy even before execution reaches your code. For example, you can configure a web-based application or service with a custom claims authentication manager, an instance of a class that derives from the ClaimsAuthenticationManager class. When so configured, the request processing pipeline invokes the Authenticate method on your claims authentication manager passing it a ClaimsPrincipal that represents the context of the incoming request. Your claims authentication manager can then perform authentication based on the values of the incoming claims. It can also filter, transform, or add claims to the incoming claim set. For example, it could be used to enrich the incoming claim set with new claims created from a local data source such as a local user profile

  • You can configure a web-based application with a custom claims authorization manager, an instance of a class that derives from the ClaimsAuthorizationManager class. When so configured, the request processing pipeline packages the incoming ClaimsPrincipal in an AuthorizationContext and invokes the CheckAccess method on your claims authorization manager. Your claims authorization manager can then enforce authorization based on the incoming claims.

  • Inline claims-based code access checks can be performed by configuring your application with a custom claims authorization manager and using either the ClaimsPrincipalPermission class to perform imperative access checks or the ClaimsPrincipalPermissionAttribute to perform declarative access checks. Claims-based code access checks are performed inline, outside of the processing pipeline, and so are available to all applications as long as a claims authorization manager is configured.

You can obtain a ClaimsPrincipal instance for the principal associated with a request in an RP application (or the principal under which a thread is executing) by casting the Thread.CurrentPrincipal property to ClaimsPrincipal. The claims associated with an ClaimsPrincipal object are available through its Claims property. The Claims property returns all of the claims contained by the identities associated with the principal. In the uncommon case in which the ClaimsPrincipal contains multiple ClaimsIdentity instances, you can use the Identities property or you can access the primary identity by using the Identity property. ClaimsPrincipal provides several methods through which these claims may be searched and fully supports Language Integrated Query (LINQ). Identities can be added to the principal by using the AddIdentities or AddIdentity methods.

NoteNote

To add identities to the ClaimsPrincipal, a caller must have full trust.

By default, WIF prioritizes WindowsIdentity objects when selecting the primary identity to return through the Identity property. You can modify this behavior by supplying a delegate through the PrimaryIdentitySelector property to perform the selection. The ClaimsPrincipalSelector property provides similar functionality for the Current property.

In the claim-based model, whether a principal is in a specified role is determined by the claims presented by its underlying identities. The IsInRole method essentially examines each identity associated with the principal to determine whether it possesses a claim with the specified role value. The type of the claim (represented by its Claim.Type property) used to determine which claims should be examined during role checks is specified on an identity through its ClaimsIdentity.RoleClaimType property. Thus, the claims examined during role checks can be of a different type for different identities associated with the principal.

The following example extracts the claims presented by a user in an HTTP request and writes them to the HTTP response. The current user is read from the HttpContext as a ClaimsPrincipal. The claims are then read from it and then are written to the response.

ClaimsPrincipal principal = HttpContext.Current.User as ClaimsPrincipal;
if (null != principal)
{
   foreach (Claim claim in principal.Claims)
   {
      Response.Write("CLAIM TYPE: " + claim.Type + "; CLAIM VALUE: " + claim.Value + "</br>");
   }
}

.NET Framework

Supported in: 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