IClaimsPrincipal Interface

Article
10/05/2012

[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.]

Defines the functionality of a claims-based principal object.

Namespace: Microsoft.IdentityModel.Claims
Assembly: Microsoft.IdentityModel (in Microsoft.IdentityModel.dll)

Usage

'Usage
Dim instance As IClaimsPrincipal

Syntax

'Declaration
Public Interface IClaimsPrincipal
    Inherits IPrincipal

public interface IClaimsPrincipal : IPrincipal

public interface class IClaimsPrincipal : IPrincipal

public interface IClaimsPrincipal extends IPrincipal

public interface IClaimsPrincipal extends IPrincipal

Example

The following example shows how to access the claims presented by a user in an ASP.NET application. This example assumes that the application is configured to use Windows® Identity Foundation (WIF). For more information about accessing claims from ASP.NET, see How to: Access Claims in an ASP.NET Page. For a complete SDK sample, see the Web Application sample in the <Installation Directory>\Windows Identity Foundation SDK\<Version>\Samples\Quick Start directory.

using System;
using System.Linq;
using System.Security.Principal;
using System.Threading;
using System.Web.UI;
using System.Web.UI.WebControls;

using Microsoft.IdentityModel.Claims;

/// <summary>
/// The Default Page Class
/// </summary>
public partial class _Default : System.Web.UI.Page
{

    /// <summary>
    /// The Page_Load method implementation for this page.
    /// </summary>
    /// <param name="sender">Sender</param>
    /// <param name="e">EventArgs</param>
    protected void Page_Load( object sender, EventArgs e )
    {
        if ( Page.User.Identity.IsAuthenticated )
        {
            // Cast the Thread.CurrentPrincipal
            IClaimsPrincipal icp = Thread.CurrentPrincipal as IClaimsPrincipal;

            // Access IClaimsIdentity which contains claims
            IClaimsIdentity claimsIdentity = (IClaimsIdentity)icp.Identity;
    
            // Access claims
            foreach(Claim claim in claimsIdentity.Claims)
            {

            }
        }
        else
        {
            // Not logged in. Redirect to Login page for authentication.
            Response.Redirect( "Login.aspx" );
        }
    }
}

The following example shows how to access the claims presented by a user from a WCF service that is configured to use WIF. The code to configure the service is omitted. For the full sample, see the Web Service SDK sample in the <Installation Directory>\Windows Identity Foundation SDK\<Version>\Samples\Quick Start directory.

using System;
using System.Security.Cryptography.X509Certificates;
using System.ServiceModel;
using System.ServiceModel.Description;
using System.Threading;

using Microsoft.IdentityModel.Claims;
using Microsoft.IdentityModel.Configuration;
using Microsoft.IdentityModel.Tokens;

namespace ClaimsAwareWebService
{
    [ServiceContract]
    public interface IClaimsAwareWebService
    {
        [OperationContract]
        string ComputeResponse( string input );
    }

    class ClaimsAwareWebService : IClaimsAwareWebService
    {

        // ...


        public string ComputeResponse( string input )
        {
            // Get the caller's identity from ClaimsPrincipal.Current
            IClaimsIdentity identity = (IClaimsIdentity)((IClaimsPrincipal)Thread.CurrentPrincipal).Identity;

            /* For illustrative purposes this sample application simply shows all the parameters of 
             * claims (i.e. claim types and claim values), which are issued by a security token 
             * service (STS), in its console window. In production code, security implications of echoing 
             * the properties of claims should be carefully considered. For example, 
             * some of the security considerations are: (i) accepting the only claim types that are 
             * expected by relying party applications; (ii) sanitizing the claim parameters before 
             * using them; and (iii) filtering out claims that contain sensitive personal information). 
             * DO NOT use this sample code ‘as is’ in production code.
            */

            Console.WriteLine( "\nCaller's name: " + identity.Name + "\nClaims issued are:\n" );
            foreach ( Claim claim in identity.Claims )
            {
                Console.WriteLine( "ClaimType  : " + claim.ClaimType );
                Console.WriteLine( "ClaimValue : " + claim.Value );
                Console.WriteLine();
            }
            Console.WriteLine( "===========================" );

            return String.Format( "Computed by ClaimsAwareWebService for {0}: {1} ", identity.Name, input );
        }
    }
}

Remarks

In the claims-based model multiple users or other claims-based identities can be party to a single action. The IClaimsPrincipal interface defines the data and behavior of the identities associated with an execution context. It extends the IPrincipal interface to include one or more claims-based identities.

IClaimsPrincipal exposes a collection of identities, each of which implements the IClaimsIdentity interface. In the common case, there will be a single issuer and a single token and the identities collection will only have one element. However, it is possible in advanced scenarios for a relying party to ask (via policy) for more than one security token, potentially from different issuers. In these scenarios, the identities collection will have several elements, each of which carries claims associated with a token.

Because they represent the security context under which a request is running, IClaimsPrincipal objects and the identities and claims that are associated with them play a large role in WIF environments. For example:

A claims principal object is passed to the claims authentication manager (ClaimsAuthenticationManager) from the processing pipeline to perform authentication based on the claims presented by an entity.
A claims principal object is passed to the claims authorization manager (ClaimsAuthorizationManager) from the processing pipeline in an AuthorizationContext object to perform authorization on an entity based on its claims.
Application code uses the claims contained in the identities associated with the current principal to further authenticate and/or authorize an entity and to fulfill requests made by the entity.

You can access the principal associated with a request in an RP application by casting the CurrentPrincipal property to IClaimsPrincipal. You can then access the IClaimsIdentity objects associated with the request by using the Identities property or the System.Security.IPrincipal.Identity property. The claims associated with an IClaimsIdentity object are available through its Claims property.

Platforms

Target Platforms

Windows 7, Windows Server 2008 R2, Windows Vista SP2, Windows Server 2008 SP2, Windows Server 2003 SP2 (32-bit or 64-bit)

IClaimsPrincipal Interface

Usage

Syntax

Example

Remarks

Platforms

Target Platforms

Change History

See Also

Reference

Other Resources

Additional resources