IClaimTransform.TransformClaims Method (SecurityPropertyCollection, SecurityPropertyCollection, SecurityPropertyCollection, ClaimTransformStage, String, String)

 

Provides extensibility for AD FS claim processing.

Namespace:   System.Web.Security.SingleSignOn
Assembly:  System.Web.Security.SingleSignOn.ClaimTransforms (in System.Web.Security.SingleSignOn.ClaimTransforms.dll)

Syntax

void TransformClaims(
    ref SecurityPropertyCollection incomingClaims,
    ref SecurityPropertyCollection corporateClaims,
    ref SecurityPropertyCollection outgoingClaims,
    ClaimTransformStage transformStage,
    string issuer,
    string target
)

void TransformClaims(
    SecurityPropertyCollection^% incomingClaims,
    SecurityPropertyCollection^% corporateClaims,
    SecurityPropertyCollection^% outgoingClaims,
    ClaimTransformStage transformStage,
    String^ issuer,
    String^ target
)

abstract TransformClaims : 
        incomingClaims:SecurityPropertyCollection byref *
        corporateClaims:SecurityPropertyCollection byref *
        outgoingClaims:SecurityPropertyCollection byref *
        transformStage:ClaimTransformStage *
        issuer:string *
        target:string -> unit

Sub TransformClaims (
    ByRef incomingClaims As SecurityPropertyCollection,
    ByRef corporateClaims As SecurityPropertyCollection,
    ByRef outgoingClaims As SecurityPropertyCollection,
    transformStage As ClaimTransformStage,
    issuer As String,
    target As String
)

Parameters

• incomingClaims
  Type: System.Web.Security.SingleSignOn.Authorization.SecurityPropertyCollection

  The incoming claims collection used in claim processing. For more information about claims processing, see the Remarks section.

  This collection represents claims received from an account partner, before built-in transformation has normalized them to corporate claims.

• corporateClaims
  Type: System.Web.Security.SingleSignOn.Authorization.SecurityPropertyCollection

  The corporate claims collection used in claim processing. For more information about claims processing, see the Remarks section.

  This collection represents claims normalized to corporate claims. At the end of processing, this collection is sometimes used to generate an accelerator token used by the client for subsequent requests.

• outgoingClaims
  Type: System.Web.Security.SingleSignOn.Authorization.SecurityPropertyCollection

  The outgoing claims collection used in claim processing. For more information about claims processing, see the Remarks section.

  This collection represents claims transformed and/or filtered appropriately for the target. At the end of processing, this collection is used to generate the security token for the target.

• transformStage
  Type: System.Web.Security.SingleSignOn.ClaimTransformStage

  The transform stage identifies the required stage of processing.

• issuer
  Type: System.String

  The issuer string identifies the party that authenticated the user; this can be an account partner or an account store.

• target
  Type: System.String

  The target string identifies the target of this claim process; this can be a resource partner or an application.

Remarks

TransformClaims is a general method. AD FS claims are processed when a user requests a token for an application or resource partner recognized by the Federation Service. Typically, the target parameter specifies the URI of an application or resource partner from the trust policy. TransformClaims is always called twice during claim processing: once as a pre-processing stage, and once as a post-processing stage. The stage is specified during the call in the transformStage parameter. The pre-processing stage takes place before the transforms specified in policy (the built-in transforms) are carried out. The post-processing stage takes place after the built-in transforms have been evaluated.

Examples

The three main scenarios for processing claims are discussed below, with particular attention to the role of the TransformClaims method. The incoming claims, corporate claims, and outgoing claims' SecurityPropertyCollection members are shared among the steps in each scenario. By changing these collections during the pre-processing stage of TransformClaims it is possible to affect changes in the later built-in claim processing steps. The built-in claim processing steps always add claims to one of the collections based on claims that are seen in another, but they never remove claims from any collection.

The user is authenticated with credentials to an account store serviced by the Federation Service. In this scenario, the issuer parameter is set to the URI that identifies the account store to which the user is authenticated.

Scenario 1

1. The corporateClaims collection is populated using account store claim generations.

2. TransformClaims is called in the pre-processing stage.

3. Built-in claim transformation uses the corporate claims as input and populates the outgoing claims using the transform rules for the target application or resource partner.

4. TransformClaims is called in the post-processing stage.

5. The outgoing claims collection generates a security token for the target application or resource partner.

6. The corporate claims collection is used to generate an accelerator token (browser cookie) used by the client for subsequent requests to the Federation Service.

The user is authenticated with a security token from an account partner trusted by the Federation Service. In this scenario, the issuer parameter is set to the URI that identifies the account partner that issued the incoming security token.

Scenario 2

1. The incoming claims collection is populated from the account partner's security token.

2. TransformClaims is called in the pre-processing stage.

3. Built-in claim transformation uses incoming claims as input and populates corporate claims using the transform rules for the account partner.

4. Built-in claim transformation uses corporate claims as input and populates outgoing claims using the transform rules for the target application or resource partner.

5. TransformClaims is called in the post-processing stage.

6. The outgoing claims collection is used to generate a security token for the target application or resource partner.

7. The corporate claims collection generates an accelerator token (browser cookie) that is used by the client for subsequent requests to the Federation Service.

The user is authenticated with an accelerator token (browser cookie) issued by the Federation Service during a previous transaction. The accelerator token used in this scenario came from either scenario 1 or 2 above. Therefore, the issuer parameter may identify either an account store or an account partner.

Scenario 3

1. The corporate claims collection is populated from the accelerator token.

2. TransformClaims is called in the pre-processing stage.

3. Built-in claim transformation uses the corporate claims as input and populates outgoing claims using the transform rules for the target application or resource partner.

4. TransformClaims is called in the post-processing stage.

5. The outgoing claims collection is used to generate a security token for the target application or resource partner. Be aware that the corporate claims are not used to produce an accelerator token.

See Also

IClaimTransform Interface
System.Web.Security.SingleSignOn Namespace

Return to top