Create Custom STS Extensions

STS extensions provide developers with the ability to issue security tokens with custom claims, such as issuing claims for Active STS security tokens consumed by WCF services and issuing claims for Passive STS security tokens for consumption by WS-Federation clients. You can create and publish STS extensions in Workflow Studio; alternatively, you can use Visual Studio to create class libraries for the purpose of extending EmpowerID Security Token claims.

Developing STS Extensions

  1. In Workflow Studio, click the application icon and select Extensibility > EmpowerID STS Claims Extension from the menu.




  2. Name the STS extension appropriately and save it to the package of your choice.




    Workflow Studio creates the STS extension stub and opens the STS extension template.





  3. Implement your logic and publish the STS extension when ready.

    In the Code Tree of Solution Explorer (located to the right of the C# Editor), you will see examples of claim types. You can drag any of these into the C# Editor to have Workflow Studio generate the "Add To Claims" code for you.



When you create an STS extension you can implement one or more methods depending on what you wish to accomplish with the extension. These methods include the following:

AugmentSTSClaims Method


This method allows you to add custom claims into the claims collection before the security token is issued by the STS.

C# Syntax

public override void AugmentSTSClaims(
    IClaimIssuerContext context
)


Parameters

ParameterDescription
contextThis parameter specifies the claim issuer context object which contains the claims collection.

Example Implementation

string AccountGUIDClaimType =  "http://empowerid.sts.com/svc/2010/03/claims/accountguid";
    context.Claims.Add(new Claim(AccountGUIDClaimType, "ACCOUNT GUID VALUE"));

AugmentSTSClaims Method (RequestSecurityToken override)

This method allows you to add claims to the current user's STS claims as required by the RequestSecurityToken.

C# Syntax

public override void AugmentSTSClaims(
    IClaimsPrincipal principal,
    Microsoft.IdentityModel.Protocols.WSTrust.RequestSecurityToken request)
)


Parameters

ParametersDescription
identityThis parameter specifies the claim identity.
requestThis parameter specifies the RequestSecurityToken.

AugmentSPClaims Method

This method allows you to add claims to the current user's SharePoint claims before the security token is issued by the STS.

C# Syntax

public override void AugmentSPClaims(
    List contextClaims,
    Person contextPerson)
)

Parameters

ParameterDescription
contextClaimsSpecifies the SharePoint entity's claims collection
contextPersonSpecifies the EmpowerID person identified by the SharePoint entity

ModifyWSFederationScope Method

This method allows you to modify the WS-Fed scope.

C# Syntax

public override void ModifyWSFederationScope(
    Microsoft.IdentityModel.SecurityTokenService.Scope scope,
    string appliesTo,
    Microsoft.IdentityModel.Claims.IClaimsPrincipal principal,
    Microsoft.IdentityModel.Protocols.WSTrust.RequestSecurityToken request,
    WSFederationSingleSignOn wsFed,
    AccountPrincipal account)
)

Parameters

ParameterDescription
scopeSpecifies the scope
appliesToSpecifies the context URL
principalSpecifies the user's security principal
requestSpecifies the token request
wsFedSpecifies the EmpowerID WS-Fed connection (may be null)

ModifyWSTrustScope Method

This method allows you to modify the WS-Trust scope.

C# Syntax


public override void ModifyWSTrustScope(
    Microsoft.IdentityModel.SecurityTokenService.Scope scope,
    string appliesTo,
    Microsoft.IdentityModel.Claims.IClaimsPrincipal principal,
    Microsoft.IdentityModel.Protocols.WSTrust.RequestSecurityToken request)
)

Parameters

ParameterDescription
scopeSpecifies the scope
appliesToSpecifies the context URL
principalSpecifies the user's security principal
requestSpecifies the token request

ResolveSPClaim Method

This method allows you to resolve a SharePoint identity claim (for claims augmentation).

C# Syntax


public override Person ResolveSPClaim(
    EIDSPClaim identityClaim)
)

Parameters

ParameterDescription
identityClaimSpecifies the identity claims to be resolved

ResolveCertificate Method

This method allows you to resolve a certificate (for client certificate authentication).

C# Syntax


public override Person ResolveCertificate(
    X509Certificate2 certificate)
)

Parameters

ParameterDescription
certificateSpecifies the client certificate to be resolved

Remarks

This method returns the EmpowerID Person that is mapped to the certificate.


ResolveWindowsIdentity Method

This method allows you to resolve the identity of a Windows integrated authenticated user.

C# Syntax


public override Person ResolveWindowsIdentity(
    IClaimsPrincipal principal,
    Microsoft.IdentityModel.Protocols.WSTrust.RequestSecurityToken request)
)

Parameters

ParameterDescription
principalSpecifies the claims principal containing the Windows identity
requestSpecifies the request token

Publishing STS Extensions

  1. Click the Compile and Publish button located just above the C# Editor.




  2. From the STS Claims Extension Publishing wizard that appears, click Next.




  3. Select an EmpowerID server as the publishing location and then click Next.




    When the wizard has completed publishing, you will be promoted to restart one or more services. Restarting the services allows EmpowerID to pick up your changes as well as make the underlying assembly for the class library available to the local GAC of those services.


  4. Click Yes when prompted to restart the services.
  5. In the Active Services dialog that appears, select the services to be restarted and then click Restart.




Disabling STS Extensions

The only way to disable an STS extension is to remove the extension from active use. After an extension has been removed, you must reset IIS to ensure that the extension is no longer used.

  1. In Workflow Studio, click the Options and Settings ribbon tab and then click the STS Claims Extensions ribbon button.




  2. In the STS Claims Extensions window that opens, select the extension you wish to remove and then click the red button to the right of the extension.




  3. Click Yes to confirm your decision.




  4. Close the STS Claims Extensions window.
In this article