Share via

SecurityTokenService.GetOutputClaimsIdentity Method

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

When overridden in a derived class, this method returns a collection of output subjects to be included in the issued token.

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

Usage

'Usage
Dim principal As IClaimsPrincipal
Dim request As RequestSecurityToken
Dim scope As Scope
Dim returnValue As IClaimsIdentity

returnValue = Me.GetOutputClaimsIdentity(principal, request, scope)

Syntax

'Declaration
Protected MustOverride Function GetOutputClaimsIdentity ( _
    principal As IClaimsPrincipal, _
    request As RequestSecurityToken, _
    scope As Scope _
) As IClaimsIdentity

protected abstract IClaimsIdentity GetOutputClaimsIdentity (
    IClaimsPrincipal principal,
    RequestSecurityToken request,
    Scope scope
)

protected:
virtual IClaimsIdentity^ GetOutputClaimsIdentity (
    IClaimsPrincipal^ principal, 
    RequestSecurityToken^ request, 
    Scope^ scope
) abstract

protected abstract IClaimsIdentity GetOutputClaimsIdentity (
    IClaimsPrincipal principal, 
    RequestSecurityToken request, 
    Scope scope
)

protected abstract function GetOutputClaimsIdentity (
    principal : IClaimsPrincipal, 
    request : RequestSecurityToken, 
    scope : Scope
) : IClaimsIdentity

Parameters

  • principal
    An IClaimsPrincipal that represents the identity of the token requestor.
  • request
    A RequestSecurityToken that represents the security token request. This includes the request message as well as other client related information such as authorization context.
  • scope
    The Scope that contains information about the relying party associated with the request. This is the Scope object that was returned by the GetScope method.

Return Value

An IClaimsIdentity that contains the collection of claims that will be placed in the issued security token.

Example

The following code example shows a simple implementation of the GetOutputClaimsIdentity method. This implementation creates a name claim from the incoming identity and an age claim and adds them to the claims in the output identity. The GetScope method is not shown in this example, but you would need to override this method as well in your STS.

using System;
using System.ServiceModel;

using Microsoft.IdentityModel.Claims;
using Microsoft.IdentityModel.Configuration;
using Microsoft.IdentityModel.Protocols.WSTrust;
using Microsoft.IdentityModel.SecurityTokenService;

namespace ClaimsAwareWebService
{
    public class MySecurityTokenService : SecurityTokenService
    {

        /// The GetScope method is omitted from this example. You must override this method 
        /// in your implementation.

        /// <summary>
        /// This method returns the claims to be included in the issued token. 
        /// </summary>
        /// <param name="scope">The scope that was previously returned by GetScope method</param>
        /// <param name="principal">The caller's principal</param>
        /// <param name="request">The incoming RST</param>
        /// <returns>The claims to be included in the issued token.</returns>
        protected override IClaimsIdentity GetOutputClaimsIdentity(IClaimsPrincipal principal, RequestSecurityToken request, Scope scope)
        {


            if ( null == principal )
            {
                throw new InvalidRequestException("The caller's principal is null.");
            }


            // Get the incoming identity 
            IClaimsIdentity callerIdentity = (IClaimsIdentity)principal.Identity;

            
            // Create the output IClaimsIdentity
            IClaimsIdentity outputIdentity = new ClaimsIdentity();

            // Create a name claim from the incoming identity.
            Claim nameClaim = new Claim( ClaimTypes.Name, callerIdentity.Name );

            // Create an 'Age' claim with a value of 25. In a real scenario, this may likely be looked up from a database.
            Claim ageClaim = new Claim( "http://WindowsIdentityFoundationSamples/2008/05/AgeClaim", "25", ClaimValueTypes.Integer );

            // Add the claims to the output identity
            outputIdentity.Claims.Add( nameClaim );
            outputIdentity.Claims.Add( ageClaim );

            return outputIdentity;
        }
    }
}

Remarks

The GetOutputClaimsIdentity method is called from the token issuance pipeline, which is implemented by the Issue method. It returns an IClaimsIdentity that contains the claims that to include in the issued security token based on the requestor of the token (the principal parameter), the incoming RST (the request parameter), and the relying party for which the token is intended (the scope parameter). The logic in this method largely is concerned with answering the following questions:

  • Which claim types should be included in the response based on the RP for which it is intended? Typically this is decided on a per-RP basis from lists of claim types required for each RP or on a per-request basis by examining the Claims property of the request. However, the logic and details for determining the claims to include in the response is completely up to your implementation.

  • Which claim values should be assigned to the claims in the response? For an Identity Provider (IP-STS) this typically means using one or more claims in the requestor’s IClaimsPrincipal (provided by the principal parameter) to access a store (or other entity) to return values for the required claim types. For a Federation Provider (R-STS) this typically means performing some kind of processing on the requestor’s incoming claims to fulfill the request; perhaps performing filtering or transformation on some claims presented by the requestor, while passing others through unmodified. Of course, as in the case of deciding which claims to include in the response, the details and logic of how to determine the values of these claims is up to your implementation.

For more information about the GetOutputClaimsIdentity method, see Building an STS. For information specifically about the token (claims) issuance pipeline, see Claims Issuance Pipeline.

All of the Windows® Identity Foundation (WIF) samples contain custom STS implementations. For examples of simple STS implementations, see the samples in the Quick Start directory. For examples of more complicated STS implementations, including STSs used in delegation and federation scenarios, see the samples in the End-to-end and Extensibility directories.

Notes to Inheritors: You must override this method in your implementation of the SecurityTokenService class.

Thread Safety

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

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)

Change History

See Also

Reference

SecurityTokenService Class
SecurityTokenService Members
Microsoft.IdentityModel.SecurityTokenService Namespace
Scope Class

Other Resources

Building an STS
Claims Issuance Pipeline

Copyright © 2008 by Microsoft Corporation. All rights reserved.