SecurityTokenService.GetOutputClaimsIdentity Method

Reference

Definition

Namespace:: System.IdentityModel

Assembly:: System.IdentityModel.dll

Important

Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.

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

protected:
 abstract System::Security::Claims::ClaimsIdentity ^ GetOutputClaimsIdentity(System::Security::Claims::ClaimsPrincipal ^ principal, System::IdentityModel::Protocols::WSTrust::RequestSecurityToken ^ request, System::IdentityModel::Scope ^ scope);

protected abstract System.Security.Claims.ClaimsIdentity GetOutputClaimsIdentity (System.Security.Claims.ClaimsPrincipal principal, System.IdentityModel.Protocols.WSTrust.RequestSecurityToken request, System.IdentityModel.Scope scope);

abstract member GetOutputClaimsIdentity : System.Security.Claims.ClaimsPrincipal * System.IdentityModel.Protocols.WSTrust.RequestSecurityToken * System.IdentityModel.Scope -> System.Security.Claims.ClaimsIdentity

Protected MustOverride Function GetOutputClaimsIdentity (principal As ClaimsPrincipal, request As RequestSecurityToken, scope As Scope) As ClaimsIdentity

Parameters

principal: ClaimsPrincipal

A ClaimsPrincipal that represents the identity of the token requestor.

request: RequestSecurityToken

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: 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(ClaimsPrincipal, RequestSecurityToken) method.

Returns

ClaimsIdentity

A ClaimsIdentity that contains the collection of claims that will be placed in the issued security token.

Examples

The code example that is used in this topic is taken from the Custom Token sample. This sample provides custom classes that enable processing of Simple Web Tokens (SWT) and it includes an implementation of a passive STS that is capable of serving an SWT token. For an example of how to implement an active STS, you can see the Federation Metadata sample. For information about these samples and other samples available for WIF and about where to download them, see WIF Code Sample Index. The following code shows how to override the GetOutputClaimsIdentity method to return claims for your STS. In this example, the Request Security Token (RST) message is ignored and a collection of claims based on the user as authenticated at the STS is returned.

/// <summary>
/// This method returns the content of the issued token. The content is represented as a set of
/// IClaimIdentity intances, each instance corresponds to a single issued token. Currently, the Windows Identity Foundation only
/// supports a single token issuance, so the returned collection must always contain only a single instance.
/// </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, we don't use this in our implementation</param>
/// <returns></returns>
protected override ClaimsIdentity GetOutputClaimsIdentity( ClaimsPrincipal principal, RequestSecurityToken request, Scope scope )
{
    //
    // Return a default claim set which contains a custom decision claim
    // Here you can actually examine the user by looking at the IClaimsPrincipal and 
    // return the right decision based on that. 
    //
    ClaimsIdentity outgoingIdentity = new ClaimsIdentity();
    outgoingIdentity.AddClaims(principal.Claims);

    return outgoingIdentity;
}

Remarks

The GetOutputClaimsIdentity method is called from the token issuance pipeline, which is implemented by the Issue method. It returns an ClaimsIdentity that contains the claims 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 is primarily 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 ClaimsPrincipal (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.

Notes to Implementers

You must override this method in your implementation of the SecurityTokenService class.

Applies to

Dela via