ClaimsPrincipal Class

Definition

Namespace:

System.Security.Claims

Assembly:

System.Security.Claims.dll

Source:

ClaimsPrincipal.cs

An IPrincipal implementation that supports multiple claims-based identities.

public ref class ClaimsPrincipal : System::Security::Principal::IPrincipal

public class ClaimsPrincipal : System.Security.Principal.IPrincipal

type ClaimsPrincipal = class
    interface IPrincipal

Public Class ClaimsPrincipal
Implements IPrincipal

Inheritance

Object

ClaimsPrincipal

Derived

System.Security.Principal.GenericPrincipal

System.Security.Principal.WindowsPrincipal

Implements

IPrincipal

Examples

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.

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

Remarks

Beginning with .NET Framework 4.5, Windows Identity Foundation (WIF) and claims-based identity are fully integrated into .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, or the principal under which a thread is executing, in a relying party (RP) application 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.

Note

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.

Constructors

ClaimsPrincipal()	Initializes a new instance of the ClaimsPrincipal class.
ClaimsPrincipal(BinaryReader)	Initializes an instance of ClaimsPrincipal with the specified BinaryReader.
ClaimsPrincipal(IEnumerable<ClaimsIdentity>)	Initializes a new instance of the ClaimsPrincipal class using the specified claims identities.
ClaimsPrincipal(IIdentity)	Initializes a new instance of the ClaimsPrincipal class from the specified identity.
ClaimsPrincipal(IPrincipal)	Initializes a new instance of the ClaimsPrincipal class from the specified principal.
ClaimsPrincipal(SerializationInfo, StreamingContext)	Obsolete. Initializes a new instance of the ClaimsPrincipal class from a serialized stream created by using ISerializable.

Properties

Claims	Gets a collection that contains all of the claims from all of the claims identities associated with this claims principal.
ClaimsPrincipalSelector	Gets or sets the delegate used to select the claims principal returned by the Current property.
Current	Gets the current claims principal.
CustomSerializationData	Contains any additional data provided by a derived type. Typically set when calling WriteTo(BinaryWriter, Byte[]).
Identities	Gets a collection that contains all of the claims identities associated with this claims principal.
Identity	Gets the primary claims identity associated with this claims principal.
PrimaryIdentitySelector	Gets or sets the delegate used to select the claims identity returned by the Identity property.

Methods

AddIdentities(IEnumerable<ClaimsIdentity>)	Adds the specified claims identities to this claims principal.
AddIdentity(ClaimsIdentity)	Adds the specified claims identity to this claims principal.
Clone()	Returns a copy of this instance.
CreateClaimsIdentity(BinaryReader)	Creates a new claims identity.
Equals(Object)	Determines whether the specified object is equal to the current object. (Inherited from Object)
FindAll(Predicate<Claim>)	Retrieves all of the claims that are matched by the specified predicate.
FindAll(String)	Retrieves all or the claims that have the specified claim type.
FindFirst(Predicate<Claim>)	Retrieves the first claim that is matched by the specified predicate.
FindFirst(String)	Retrieves the first claim with the specified claim type.
GetHashCode()	Serves as the default hash function. (Inherited from Object)
GetObjectData(SerializationInfo, StreamingContext)	Populates the SerializationInfo with data needed to serialize the current ClaimsPrincipal object.
GetType()	Gets the Type of the current instance. (Inherited from Object)
HasClaim(Predicate<Claim>)	Determines whether any of the claims identities associated with this claims principal contains a claim that is matched by the specified predicate.
HasClaim(String, String)	Determines whether any of the claims identities associated with this claims principal contains a claim with the specified claim type and value.
IsInRole(String)	Returns a value that indicates whether the entity (user) represented by this claims principal is in the specified role.
MemberwiseClone()	Creates a shallow copy of the current Object. (Inherited from Object)
ToString()	Returns a string that represents the current object. (Inherited from Object)
WriteTo(BinaryWriter, Byte[])	Serializes using a BinaryWriter.
WriteTo(BinaryWriter)	Serializes using a BinaryWriter.

See also

• Claim
• ClaimsIdentity
• ClaimsAuthenticationManager
• ClaimsAuthorizationManager