WIF Claims Programming Model

ASP.NET and Windows Communication Foundation (WCF) developers ordinarily use the IIdentity and IPrincipal interfaces to work with the user’s identity information. In .NET 4.5, Windows Identity Foundation (WIF) has been integrated such that claims are now always present for any principal as illustrated in the following diagram:

In .NET 4.5, System.Security.Claims contains the new ClaimsPrincipal and ClaimsIdentity classes (see diagram above). All principals in .NET now derive from ClaimsPrincipal. All built-in identity classes, like FormsIdentity for ASP.NET and WindowsIdentity now derive from ClaimsIdentity. Similarly, all built-in principal classes like GenericPrincipal and WindowsPrincipal derive from ClaimsPrincipal.

A claim is represented by Claim class. This class has the following important properties:

• Type represents the type of claim and is typically a URI. For example, the email address claim is represented as https://schemas.microsoft.com/ws/2008/06/identity/claims/email.

• Value contains the value of the claim and is represented as a string. For example, the email address can be represented as "someone@contoso.com".

• ValueType represents the type of the claim value and is typically a URI. For example, the string type is represented as http://www.w3.org/2001/XMLSchema#string. The value type must be a QName according to the XML schema. The value should be of the format namespace#format to enable WIF to output a valid QName value. If the namespace is not a well-defined namespace, the generated XML probably cannot be schema validated, because there will not be a published XSD file for that namespace. The default value type is http://www.w3.org/2001/XMLSchema#string. For information about well-known value types that you can use safely, see the W3C XML Schema page.

• Issuer is the identifier of the security token service (STS) that issued the claim. This can be represented as URL of the STS or a name that represents the STS, such as https://sts1.contoso.com/sts.

• OriginalIssuer is the identifier of the STS that originally issued the claim, regardless of how many STSs are in the chain. This is represented just like Issuer.

• Subject is the subject whose identity is being examined. It contains a ClaimsIdentity.

• Properties is a dictionary that lets the developer provide application-specific data to be transferred on the wire together with the other properties, and can be used for custom validation.

Identity Delegation

An important property of ClaimsIdentity is Actor. This property enables the delegation of credentials in a multi-tier system in which a middle tier acts as the client to make requests to a back-end service.

Accessing Claims through Thread.CurrentPrincipal

To access the current user’s set of claims in an RP application, use Thread.CurrentPrincipal.

The following code sample shows the usage of this method to get a System.Security.Claims.ClaimsIdentity:

ClaimsPrincipal claimsPrincipal = Thread.CurrentPrincipal as ClaimsPrincipal;

For more information, see System.Security.Claims.

Role Claim Type

Part of configuring your RP application is to determine what your role claim type should be. This claim type is used by System.Security.Claims.ClaimsPrincipal.IsInRole(System.String). The default claim type is https://schemas.microsoft.com/ws/2008/06/identity/claims/role.

Claims Extracted by Windows Identity Foundation from Different Token Types

WIF supports several combinations of authentication mechanisms out of the box. The following table lists the claims that WIF extracts from different token types.