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 e-mail address claim is represented as
Value contains the value of the claim and is represented as a string. For example, the e-mail address can be represented as "firstname.lastname@example.org".
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#formatto 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. Please see http://www.w3.org/2001/XMLSchema for well-known value types that you can use safely.
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
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.
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
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
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.
|Token Type||Claim Generated||Map To Windows Access Token|
|SAML 1.1||1. All claims from System.IdentityModel.SecurityTokenService.GetOutputClaimsIdentity(System.Security.Claims.ClaimsPrincipal,System.IdentityModel.Protocols.WSTrust.RequestSecurityToken,System.IdentityModel.Scope).
4. AuthenticationMethod and AuthenticationInstant claims, if the token contains an authentication statement.
|In addition to the claims listed in "SAML 1.1", except claims of type
|SAML 2.0||Same as "SAML 1.1".||Same as "SAML 1.1 Mapped to Windows Account".|
|X509||1. Claims with the X500 distinguished name, emailName, dnsName, SimpleName, UpnName, UrlName, thumbprint, RsaKey (this can be extracted using the RSACryptoServiceProvider.ExportParameters method from the X509Certificate2.PublicKey.Key property), DsaKey (this can be extracted using the DSACryptoServiceProvider.ExportParameters method from the X509Certificate2.PublicKey.Key property), SerialNumber properties from the X509 Certificate.
2. AuthenticationMethod claim with value
|1. It uses the Windows account fully qualified domain name as the
2. Claims from the X509 Certificate not mapped to Windows, and claims from the windows account obtained by mapping the certificate to Windows.
|UPN||1. Claims are similar to the claims in the Windows authentication section.
2. AuthenticationMethod claim with value
|Windows (Kerberos or NTLM)||1. Claims generated from the access token such as: PrimarySID, DenyOnlyPrimarySID, PrimaryGroupSID, DenyOnlyPrimaryGroupSID, GroupSID, DenyOnlySID, and Name
2. AuthenticationMethod with the value
|RSA Key Pair||1. The
2. AuthenticationMethod claim with the value
|Authentication Type||URI emitted in "AuthenticationMethod" claim|