What is Windows Identity Foundation?

  • Article

[Starting with the .NET Framework 4.5, Windows Identity Foundation (WIF) has been fully integrated into the .NET Framework. The version of WIF addressed by this topic, WIF 3.5, is deprecated and should only be used when developing against the .NET Framework 3.5 SP1 or the .NET Framework 4. For more information about WIF in the .NET Framework 4.5, also known as WIF 4.5, see the Windows Identity Foundation documentation in the .NET Framework 4.5 Development Guide.]

WIF Logo

Windows® Identity Foundation (WIF) is a framework for building identity-aware applications. The framework abstracts the WS-Trust and WS-Federation protocols and presents developers with APIs for building security token services and claims-aware applications. Applications can use WIF to process tokens issued from security token services and make identity-based decisions at the web application or web service.

WIF has the following major features:

  • Build claims-aware applications (Relying Party Applications). WIF helps developers build claims-aware applications. In addition to providing a new claims model, it provides application developers with a rich set of APIs to help making user access decisions based on claims. WIF also provides developers with a consistent programming experience whether they choose to build their applications in ASP.NET or in WCF environments. For more information, see Claims Consumer - Relying Party Applications.

  • Visual Studio Templates. WIF offers built-in Visual Studio Templates for claims-aware ASP.NET Web site and WCF Web service applications and reduces the learning curve to get familiar with the claims-based programming model. For more information, see Visual Studio Templates.

  • Easy trust establishment between claims-aware application and STS. WIF provides a utility, named FedUtil, to allow easy trust establishment between claims-aware applications and an STS, such as Active Directory Federation Services 2.0 and a LiveID STS. FedUtil supports both ASP.NET and WCF applications. It is also integrated with Visual Studio so that it can be invoked from the Solution Explorer by right clicking on a project and choosing "Add STS Reference" menu item, or from the Tools menu in Visual Studio. For more information, see FedUtil - Federation Utility for Establishing Trust from an RP to an STS.

  • ASP.NET Controls. ASP.NET controls simplify development of ASP.NET pages for building claims-aware Web applications. For more information, see Establishing Trust from an ASP.NET Relying Party Application to an STS using the FederatedPassiveSignIn Control.

  • Translate between claims and NT tokens. WIF includes a Windows service named Claims to Windows Token Service (c2WTS) that acts as a bridge between claims-aware applications and NT token based applications. It provides developers with an easy way to convert claims to NT-Token identity and makes it possible to access the resources that require NT-Token based identity from a claims-aware application. For more information, see Claims to Windows Token Service (c2WTS) Overview.

  • Build identity delegation support into claims-aware applications. WIF offers the capability of maintaining the identities of original requestors across the multiple service boundaries. This capability can be achieved by either using the "ActAs" or the "OnBehalfOf" functionality in the framework and it offers developers the ability to add identity delegation support into their claims-aware applications. For more information, see Integration with IIdentity and IPrincipal and Identity Delegation Scenario.

  • Build custom security token services (STS). WIF makes it substantially easier to build a custom security token service (STS) that supports the WS-Trust protocol. Such an STS is also referred to as an Active STS.

    In addition, the framework also provides support for building an STS that supports WS-Federation to enable Web browser clients. Such an STS is also referred to as a Passive STS.

    The framework offers built-in Visual Studio Templates for building ASP.NET STSes and WCF STSes; these templates create simple STSes and developers can extend these and implement production STSes that suit their needs. For more information, see How to: Build an ASP.NET STS and How to: Build a WCF STS.

WIF supports the following major scenarios:

  • Federation. WIF makes it possible to build federation between two or more partners. Its support for building claims-aware applications (RP) and custom security token services (STS) helps developers achieve this scenario. For more information, see Federation Scenario.

  • Identity Delegation. WIF makes it easy to maintain the identities across the service boundaries so that developers can achieve an identity delegation scenario. For more information, see Identity Delegation Scenario.

  • Step-up Authentication. Authentication requirements for different resources within an application may vary. WIF provides developers the ability to build applications that can require incremental authentication requirements (for example: initial login with Username/Password authentication and then step-up to Smart Card authentication). For more information, see Step-Up Authentication Scenario.

By using WIF, you’ll more easily reap the benefits of the claims-based identity model described in this topic. This topic provides an overview of the new features that Windows® Identity Foundation (WIF) provides for handling Claims. For more information, see Windows Identity Foundation White Paper for Developers.

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 IClaimsIdentity:

IClaimsIdentity claimsIdentity = ((IClaimsPrincipal)Thread.CurrentPrincipal).Identities[0];

For more information, see How to: Access Claims in an ASP.NET Page.

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 IsInRole. 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.

Token Type

Claim Generated

Map To Windows Access Token

SAML 1.1
  1. All claims from GetOutputClaimsIdentity

  2. The https://schemas.microsoft.com/ws/2008/06/identity/claims/confirmationkey claim that contains the XML serialization of the confirmation key, if the token contains a proof token.

  3. The https://schemas.microsoft.com/ws/2008/06/identity/claims/samlissuername claim from the Issuer element.

  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 https://schemas.xmlsoap.org/ws/2005/05/identity/claims/name, Windows authentication related claims will be added and the identity will be represented by WindowsClaimsIdentity.

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 https://schemas.microsoft.com/ws/2008/06/identity/authenticationmethod/x509. AuthenticationInstant claim with the value of the time when the certificate was validated in XmlSchema DateTime format.
  1. It uses the Windows account fully qualified domain name as the https://schemas.xmlsoap.org/ws/2005/05/identity/claims/name claim value. .

  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 https://schemas.microsoft.com/ws/2008/06/identity/authenticationmethod/password. The AuthenticationInstant claim with the value of the time when the password was validated in XmlSchema DateTime format.

  

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 https://schemas.microsoft.com/ws/2008/06/identity/authenticationmethod/windows. AuthenticationInstant with the value of the time when the Windows access token was created in the XMLSchema DateTime format.

  

RSA Key Pair
  1. The https://schemas.xmlsoap.org/ws/2005/05/identity/claims/rsa claim with the value of RSAKeyValue.

  2. AuthenticationMethod claim with the value https://schemas.microsoft.com/ws/2008/06/identity/authenticationmethod/signature. AuthenticationInstant claim with the value of the time when the RSA key was authenticated (that is, the signature was verified) in the XMLSchema DateTime format.

Authentication Type

URI emitted in “AuthenticationMethod” claim

Password

urn:oasis:names:tc:SAML:1.0:am:password

Kerberos

urn:ietf:rfc:1510

SecureRemotePassword

urn:ietf:rfc:2945

TLSClient

urn:ietf:rfc:2246

X509

urn:oasis:names:tc:SAML:1.0:am:X509-PKI

PGP

urn:oasis:names:tc:SAML:1.0:am:PGP

Spki

urn:oasis:names:tc:SAML:1.0:am:SPKI

XmlDSig

urn:ietf:rfc:3075

Unspecified

urn:oasis:names:tc:SAML:1.0:am:unspecified