Search Wiki:
dpelog.png

Overview


updated for RTM

FabrikamShipping is a semi-realistic sample web application that demonstrates how to use Windows Identity Foundation for authentication, authorization and identity driven customization for a web frontend and a services backend. Its main goal is to show how to implement common tasks and features in web applications, combining the techniques presented separately in other technology learning material such as the Windows Identity Foundation SDK and the Identity Developer Training Kit.

Note that while all efforts have been made for following best practices whenever possible, FabrikamShipping is NOT a reference implementation since it is designed for readability and for making as clear as possible for the reader to understand what is happening, as opposed to efficiency and maintainability. You should NOT use FabrikamShipping code in production.

The FabrikamShipping Scenario


scenario.png
FabrikamShipping’s main actors

The FabrikamShipping scenario has been originally designed as part of an end-to-end demo for PDC 2008 (video recording available at http://channel9.msdn.com/pdc2008/BB11/, from 31” on). While the general narrative remains largely unchanged, this example has been adapted to be a standalone web solution that you can install and examine on your machine without the need for virtual machines, services subscription or even internet connectivity.

Fabrikam is an ISV that sells S+S solutions to business customers. FabrikamShipping is one of such solutions: it is a web application that allows users to ship packages. Shipments are created by entering details about sender and intended recipient. Once a shipment has been created, it will go through a workflow which represents the various shipment phases (pickup, package, transit, delivery); every phase will allow the user to perform specific actions, such as cancelling the shipment or rerouting to a different address.

Adatum Corporation is a customer of Fabrikam, and subscribed to the FabrikamShipping application. John and Mary work for Adatum, and routinely use FabrikamShipping. John handles logistic in Manufacturing, while Mary is a manager: their different positions in the company translate in different privileges when using the application.

Implementation Details



implementation.png
FabrikamShipping’s Architecture

FabrikamShipping is a classic web application, which authenticates its users via passive federation.

The example includes a mock identity provider, www.adatumcorporation.com, which is a light customization of the default development STS template project provided with the RC of Windows Identity Foundation. Since the solution is designed to be able to run from a single machine, we make the STS available via HTTPS on a custom IIS binding (on port 8081) and we provide opportune entry on the local HOST file.

The main application, https://www.fabrikamshipping.com:8082/FabrikamShipping/, is configured in a similar way and it is set to accept tokens directly from Adatum.

Note: In a more realistic scenario, Fabrikam would have a resource STS that would be used to maintain the relationship with Adatum and all the other federated partners, and where any claims transformation that may be need would take place. Every Fabrikam applications, including FabrikamShipping, would then trust the resource STS instead of having to handle the relationship with the federated partner directly.
In this sample we did not feature a resource STS at this level mainly because we wanted to keep thing simple and maintain smooth demo flow: there is a single application, that may even be running a hoster; there is a single federated partner in the picture; and for this application there is no need for claims transformation at the presentation layer. Unless you fall exactly in this category, there is a very high probability that your scenarios will indeed benefit from trusting your own resource STS rather than the partner directly.

All FabrikamShipping business logic lives in a set of WCF services. The presentation layer invokes the services using a delegation mechanism: the access privileges are decided for every service call on the basis of the current web application’s user, as opposed to relying on trusted subsystem or full website impersonation approaches. The services are configured to accept tokens from an internal STS with ActAs capabilities: the STS is in turn invoked by the presentation layer’s code-behind with the token of the original user.

The Visual Studio Solution: What to Look For


vssol.png
FabrikamShipping solution structure

The Visual Studio solution is pretty simple, and has been organized in a way that surfaces the main entities in the architecture and their component. At a glance, those are the projects and what to look from the identity management point of view:

  • The Adatum folder contains only the STS subfolder with our mock identity provider, the web site http://www.adatumcorporation.com/FederationPassive/. All the identity content here is a mild customization of the default development STS offered by Windows Identity Foundation RC
  • The Fabrikam folder contains the bulk of the sample. The BackEnd subfolder contains all the projects that constitute the business logic of the sample
    • FabrikamShipping.Services.Contracts is a class library containing all the contract definitions for the services. No identity code here.
    • FabrikamShipping.Services.Host is the web application that hosts the services, which are all message-activated. The web.config shows how to configure the ClaimsAuthorizationModule, use the ConfigureServiceHostBehaviorExtensionElement for configuring WCF services for using Windows Identity Foundation, and assign policies via custom claimsAuthorizationManager class.The App_Code folder contains the definition of the custom claimsAuthorizationManager class, substantially the same sample found in the SDK.
    • FabrikamShipping.Services is a class library containing the services implementations. No identity code here.
    • FabrikamShipping.Data is a class library containing the data model for shipments, customers and all the entities used by the sample. No identity code here.
  • The STS folder contains the internal STS.
    • FabrikamShipping.RPSts is the web application which contains the ActAs STS which issues tokens for the frontend to invoke the backend services.The web.config shows how to configure an active STS secured via X509 certificate; it also demonstrates how to use a custom X509SecurityTokenHandler class (defined in SimpleX509SecurityTokenHandler.cs, integrated by SimpleCertificateValidator.cs) for defining the list of acceptable certificates.The ST implementation in ActAsSecurityTokenService.cs, and the method GetOutputClaimsIdentity in particular, demonstrates how to drive issuance decisions on the basis of ActAs tokens
  • The FrontEnd folder contains the main web application.
    • http://www.fabrikamshipping.com/FabrikamShipping/ is the website of the main application.The web.config contains the classic settings that are the output of the federation wizard (or fedutil) when configuring a website to accept tokens from an identity provider. Furthermore, the web.config contains the binding that is needed for requesting a token from the ActAs STS.The global.asax, and specifically the Sessionstart handler, demonstrates how to use the token obtained from the identity provider as an ActAs token with WSTrustClient for invoking our internal ActAs STS. The resulting token is then stored in the HTTP session, where it will be available whenever the application will need to call a backend service (a real application may need to find a more solid solution for maintaining session state).The AppCode/Clients folder contains utility classes for invoking WCF services by injecting in the call an issued token already in our possession: in our case, this will be the delegated token we stored in the HTTP session at the time of global.asax’s session_start execution.Most aspx pages will take advantage of IClaimsIdentity in the usual way for accessing claims from the identity provider; the calls to the backend services will be performed by taking advantage of the utility classes mentioned above

The Solution in IIS


iis.png
FabrikamShipping structure in IIS

  • The structure that emerges in IIS matches the solution description above. Note that
  • Both websites introduce their own SSL bindings (8081 for Adatum and 8082 for Fabrikam)
  • The SSL certificates are self-signed, and configured as part of the overall setup script
  • In order to preserve your current settings, all web applications in the FabrikamShipping sample make use of a custom application pool, FabrikamShippingAppPool, which holds all the necessary permissions for accessing the private keys associated to the sample certificates above

Summary


FabrikamShipping is a learning tool designed for you to observe, take apart and experiment with Windows Identity Foundation and claims based identity. We tried to make it somewhat realistic in order to hint to the business value and to the solutions to some of the most common challenges you need to address when developing a web application; at the same time, we tried to keep things simple and to make sure you always know what is going on and which part does which function. We hope we managed to strike the right balance, and that FabrikamShipping will help you to enjoy the benefits of claims-based access. More details will be posted on http://channel9.msdn.com/identity/ and http://blogs.msdn.com/vbertocci/
Last edited Nov 17 2009 at 8:00 PM  by Vittorio, version 9
Comments
jhakasjk wrote  Jan 26 2011 at 10:28 AM  
Hi,

Please provide the documentation also.

Updating...
Page view tracker