Microsoft WF Security Pack CTP

1 User Guide
Table of Contents
Table of Contents.............................................................................................1
Introduction......................................................................................................2
Background...................................................................................................2
Purpose.........................................................................................................2
Installation........................................................................................................3
System Requirements...................................................................................3
Instructions...................................................................................................3
Uninstall........................................................................................................3
WF Service activities........................................................................................3
ImpersonatingReceiveScope.........................................................................4
PrincipalPermissionScope..............................................................................5
WF Client activities...........................................................................................6
TokenFlowScope...........................................................................................6
GetUserNameSecurityToken.........................................................................8
GetSamlSecurityToken..................................................................................8
WF Client+Service activities..........................................................................10
OperationContextScope..............................................................................10
GetBootstrapToken.....................................................................................11
Known Issues..................................................................................................12
Notes.............................................................................................................. 13
Tested Environments..................................................................................13
Installation Content.....................................................................................13
Building Source code...................................................................................13
Additional Information....................................................................................14
Introduction
The Microsoft WF Security Pack CTP 1 is the first community technology
preview (CTP) release of a set of activities and their implementation based on
Windows Workflow Foundation in .NET Framework 4 (WF 4) and the Windows
Identity Foundation (WIF).

Background
The Windows Communication Foundation (WCF) not only provides a common
programming model for building web services using different protocols (the
Service Model), but it also provides a common identity model to leverage
different security schemes for authentication and authorization of clients and
services (the Identity Model). The Identity Model in WCF enables many
common web service security scenarios.

Although WF 4 provides a new programming model for building web services

(ServiceModel.Activities), there is currently no additional support for easily
leveraging the WCF Identity Model. These scenarios are possible to achieve
using extensibility, but it remains a non-trivial task to the developer to
accomplish.

Purpose
The Microsoft WF Security Pack CTP 1 contains both activities and their
designers which illustrate how to easily enable various security-related
scenarios using workflow, including:

• Impersonating a client identity in the workflow.

• In-workflow authorization, such as PrincipalPermission and validation of

Claims.

• Authenticated messaging using ClientCredentials specified in the

workflow, such as username/password or a token retrieved from a
Security Token Service (STS).

• Flowing a client security token to a back-end service (claims-based

delegation) using WS-Trust ActAs.

The Microsoft WF Security Pack CTP 1 includes the following activities:

• WF Service activities
o ImpersonatingReceiveScope impersonates a client’s
WindowsIdentity on the workflow thread for the activities in
scope.
o PrincipalPermissionScope verifies that the incoming identity
from a Receive activity passes a PrincipalPermission check
based on user or role.
• WF Client activities
 o TokenFlowScope causes any Send activities within the scope
to flow the enlisted security token with the outgoing message.
o GetUserNameSecurityToken initializes a username/password
security token (so it can be used with a TokenFlowScope).
o GetSamlSecurityToken retrieves a SAML security token from a
target Security Token Service (so it can be used with a
TokenFlowScope).
• WF Client+Service activities (often used in conjunction with WF Client
activities)
o OperationContextScope exposes OperationContext &
ServiceSecurityContext of a Receive in a workflow thread-
agnostic way for the activities in scope.
o GetBootstrapToken retrieves the incoming primary identity
from a Receive activity (relies on access to OperationContext &
ServiceSecurityContext).

The latest version of this document can be found at http://wf.codeplex.com.

Installation
System Requirements
• Prerequisite software
o Microsoft .NET Framework 4
o Microsoft Windows Identity Foundation
o Microsoft Visual Studio 2010 (only required when using
Microsoft WF Security Pack within Microsoft Visual Studio)

Note: the setup .msi does not attempt to detect the presence of Windows
Identity Foundation (WIF) on the machine. While it is possible to install the
pack without having WIF installed, the WF Security Pack activities will not
execute correctly without it.

Instructions
Download and run the setup file
Microsoft_WF_Security_Pack_CTP_1_Setup.msi. Click Allow if you encounter a
User Account Control dialog.

Uninstall
1. Open “Control Panel” and select “Programs and Features”.
2. Select “Microsoft WF Security Pack CTP 1” and click “Uninstall”.

WF Service activities
This section describes the WF Service activities of the WF Security Pack in
detail.
ImpersonatingReceiveScope
The ImpersonatingReceiveScope activity enables all activities in scope to be
executed under the impersonation context of a client-provided identity. The
identity is presented by the client in order to authenticate to the WF Service.

The Request property is a WF 4 Receive activity. Upon receiving the client’s

request in the workflow, a valid WindowsIdentity is obtained in one of three
ways:
1. From the authenticated client’s identity, if Windows credentials are
required by the service.
2. From the authenticated client’s claim set, if a WCF-based UPN claim
was provided.
3. From the authenticated client’s claim set, if a WIF-based UPN claim
was provided.

Throughout the execution of the Body (i.e. the activities within the scope), all
workflow threads are setup to impersonate the previously-obtained
WindowsIdentity. Furthermore, outgoing messages (e.g. from Send
activities) sent from within an ImpersonatingReceiveScope activity will invoke
Kerberos delegation, presuming the WindowsIdentity token supports that
level of impersonation.

The following example demonstrates how to use an ImpersonatingReceiveScope

activity to impersonate a client’s WindowsIdentity, provided as part of an
UpdatePurchaseOrder request, in order to update the SQL database under
that impersonation context:
 Figure 1 - ImpersonatingReceiveScope

PrincipalPermissionScope
The PrincipalPermissionScope activity enforces authorization within the workflow
by performing a principal permission check against a client-provided identity.

After a message is received (via a Receive activity within the scope of the
Body), the authenticated client identity is checked against the principal
permission values specified in the PrincipalPermissionName and
PrincipalPermissionRole arguments. This permission demand is done in the
same way as enforced by the PrincipalPermission class or attribute, and
therefore it also supports ASP.NET Role Providers in addition to
WindowsIdentity.
The following example demonstrates how to use a PrincipalPermissionScope
activity to authorize an UpdatePurchaseOrder request submitted by a client
who must be an Administrator:

Figure 2 - PrincipalPermissionScope

WF Client activities
This section describes the WF Client activities of the WF Security Pack in
detail.

TokenFlowScope
The TokenFlowScope activity enables Send activities within the scope to utilize
security tokens that have been enlisted in the workflow. This activity is most
often used in conjunction with other activities that create or retrieve security
tokens (e.g. GetUserNameSecurityToken, GetSamlSecurityToken, GetBootstrapToken).

The enlisted security tokens are passed down through the Send activity via
the OperationContext to the WCF channel layer where they are added to the
message by a custom ClientCredentials behavior (WorkflowClientCredentials).
This behavior passes all enlisted tokens that match the type of client
credential expected by the binding.

The following example demonstrates how to use a TokenFlowScope activity to

flow a Username security token to an Add-Service-Reference-generated
activity (Add) to call the Add operation on a calculator service:
 Figure 3 - TokenFlowScope & GetUserNameSecurityToken

<client>
<endpoint address="http://localhost:8001/calculator" binding="wsHttpBinding"
bindingConfiguration="WSHttpBinding_ICalculator" contract="ICalculator"
name="WSHttpBinding_ICalculator"

behaviorConfiguration="clientWF" >
<!-- the above behaviorConfiguration was added to the generated config -->
</endpoint>
</client>
…
<behaviors>
<endpointBehaviors>
<!-- the following behaviorConfiguration was added to the generated config -->
<behavior name="clientWF">
<clientCredentials type="Microsoft.Security.Activities.WorkflowClientCredentials,
Microsoft.Security.Activities, Version=1.0.0.0, Culture=neutral,
PublicKeyToken=31bf3856ad364e35" >
…
</clientCredentials>
</behavior>
</endpointBehaviors>
</behaviors>
GetUserNameSecurityToken
The GetUserNameSecurityToken activity creates a UserNameSecurityToken
(based on input UserName and Password values) and enlists it with a
TokenFlowScope.

The UserName and Password values can be specified at runtime using

workflow variables.

See the TokenFlowScope section for an example of how to use the

GetUserNameSecurityToken activity.

GetSamlSecurityToken
The GetSamlSecurityToken activity retrieves a SamlSecurityToken from a
Security Token Service (STS) and enlists it with a TokenFlowScope.

The GetSamlSecurityToken activity uses a client endpoint specified in

configuration via the IssuerEndpointConfigurationName property. The Uri of
the STS can also be overwritten in the workflow by using the
IssuerEndpointAddress argument.

The AppliesTo argument allows the workflow author to provide the Uri of the
relying party, i.e. the service that is expecting to receive a
SamlSecurityToken from the workflow client.

The TrustVersion property allows the workflow author to configure which

version of WS-Trust is used to format the RequestSecurityToken (RST) and
RequestSecurityTokenResponse (RSTR) messages. The default value is WS-
Trust 1.3.

The following example demonstrates how to use a GetSamlSecurityToken

activity with a TokenFlowScope activity to flow the SamlSecurityToken to an
Add-Service-Reference-generated activity (Add) to call the Add operation on a
calculator service:
 Figure 4 - TokenFlowScope & GetSamlSecurityToken

<client>
<endpoint name="STSEndpoint" binding="ws2007HttpBinding"
bindingConfiguration="Binding_STS" address="http://localhost:8000/sts"
contract="IWSTrustContract" />

<endpoint address="http://localhost:8001/calculator" binding="wsHttpBinding"

bindingConfiguration="WSHttpBinding_ICalculator" contract="ICalculator"
name="WSHttpBinding_ICalculator"

behaviorConfiguration="clientWF" >
<!-- the above behaviorConfiguration was added to the generated config -->
</endpoint>
</client>
…
<behaviors>
<endpointBehaviors>
<!-- the following behaviorConfiguration was added to the generated config -->
<behavior name="clientWF">
<clientCredentials type="Microsoft.Security.Activities.WorkflowClientCredentials,
Microsoft.Security.Activities, Version=1.0.0.0, Culture=neutral,
PublicKeyToken=31bf3856ad364e35" >
…
</clientCredentials>
</behavior>
</endpointBehaviors>
</behaviors>
WF Client+Service activities
This section describes the WF Client+Service activities of the WF Security
Pack in detail. Although these activities can be used in any WF Service, they
are most useful in middle-tier WF scenarios when information from a client
request is needed as part of a call to a back-end service.

OperationContextScope
The OperationContextScope activity makes the OperationContext of the current
operation accessible on the workflow thread for the duration of that
operation. Some commonly-used properties on OperationContext include
message headers, message properties, and the identity of the caller.

The following example shows how to use an OperationContextScope activity to

allow access to the ServiceSecurityContext.PrimaryIdentity of the
authenticated caller:
 Figure 5 - OperationContextScope

GetBootstrapToken
The GetBootstrapToken activity uses the PrimaryIdentity of the current
operation to bootstrap the security token, which can then be used to flow to a
back-end service. Most commonly, the bootstrap token will be used as a WS-
Trust ActAs token when a Saml token is required by the back-end service (see
the Claims-based Delegation scenario below).

The PrimaryIdentity is obtained through OperationContext, therefore the

GetBootstrapToken activity must be used within an OperationContextScope
activity. Furthermore, in order to flow the token to a corresponding WF 4
Send activity, the GetBootstrapToken activity also needs to be placed within a
TokenFlowScope.

The following example demonstrates how to configure the activity to flow a

client’s token to a back-end calculator service and call the Add operation:
 Figure 6 - OperationContextScope, TokenFlowScope, & GetBootstrapToken

Known Issues
None at the time of CTP 1 release.
Notes
Tested Environments
Microsoft WF Security Pack CTP 1 has been tested on the following
environments for both x86- and x64-based architectures:
1. Windows 7

2. Windows Server 2008 R2

3. Windows Vista SP2

4. Windows Server 2008 SP2

Installation Content
The setup file will install the following content into your machine:
• Files
o $ProgramFiles$\Microsoft WF Security Pack\CTP
1\Microsoft.Security.Activities.dll
o $ProgramFiles$\Microsoft WF Security Pack\CTP
1\Microsoft.Security.Activities.Design.dll
o $ProgramFiles$\Microsoft WF Security Pack\CTP
1\Microsoft.VisualStudio.WorkflowSecurityPack.dll
o $ProgramFiles$\Microsoft WF Security Pack\CTP
1\Microsoft.Security.Activities.chm
• Visual Studio Integration
o A “Security” category added to the toolbox of workflow project
with seven items inside:
 GetBootstrapToken
 GetSamlSecurityToken
 GetUserNameSecurityToken
 ImpersonatingReceiveScope
 OperationContextScope
 PrincipalPermissionScope
 TokenFlowScope

Building Source code

The integration package in Microsoft WF Security Pack CTP 1 leverages the
Visual Studio 2010 SDK to provide a Visual Studio integrated experience.
However, using the activities or their designers does not require the
installation of the Visual Studio 2010 SDK.

If you want to build the source code with the integration package, you need
to have Visual Studio 2010 SDK installed. You can download the Visual Studio
2010 SDK from http://www.microsoft.com/downloads/details.aspx?
FamilyID=47305cf4-2bea-43c0-91cd-1b853602dcc5&displaylang=en
Additional Information
• Windows Workflow Foundation on CodePlex: http://wf.codeplex.com/
• Windows Workflow Foundation on MSDN:
http://msdn.microsoft.com/en-us/netframework/aa663328.aspx
• Visual Studio on MSDN: http://msdn.microsoft.com/en-
us/vstudio/default.aspx
• .NET Framework Developer Center: http://msdn.microsoft.com/en-
us/netframework/default.aspx
• Endpoint Blog: http://blogs.msdn.com/endpoint/
• Go with the Flow Blog: http://blogs.msdn.com/flow/
• Zulfiqar Ahmed’s blog: http://zamd.net/

The information contained in this document relates to pre-release software product, which
may be substantially modified before its first commercial release. Accordingly, the information
may not accurately describe or reflect the software product when first commercially released.
This document is provided for informational purposes only, and Microsoft makes no warranties,
express or implied, with respect to this document or the information contained in it.

Microsoft may have patents, patent applications, trademarks, copyrights, or other intellectual
property rights covering subject matter in this document. Except as expressly provided in any
written license agreement from Microsoft, the furnishing of this document does not give you
any license to these patents, trademarks, copyrights, or other intellectual property.
©2010 Microsoft Corporation. All rights reserved.

Microsoft, Windows, Visual Studio, and the .NET logo are trademarks of the Microsoft group of
companies. All other trademarks are property of their respective owners.