Announcing FabrikamShipping, in-depth semi-realistic sample for Geneva Framework

Do you remember the PDC session in which Kim announced all the new wave of identity products, including Geneva?

During that session I showed a pretty comprehensive demo, where  all the products & services worked together for enabling a fairly realistic end-to-end scenario. You have seen demos based on the same scenario at TechEd EU, TechDays and in many presentations from my colleagues in the various subsidiaries; finally, if you came at the Geneva booth at RSA chances are that you got an detailed walkthrough of it. Since people liked it so much, we thought it would have been nice to extract just the main web application from that scenario, and make it available to everyone in form of an in-depth example. You can find the code in a handy self-installing file on code gallery, at https://code.msdn.microsoft.com/FabrikamShipping (direct link here).

The idea is that we bridge the gap between pure technical learning content (the training kit) and high level presentation (take your pick), by providing you with a demo that on one side you can use for explaining to non-technical people what’s the point of claims-based identity, on the other side you can take the code apart and see what makes the application tick. You will see that we do little more than applying the solutions described in the identity developer training kit to the challenges that a real application requires: we comment the code here and there so you’ll always know what is going on, if you want to go deeper we recommend you look up the specific solution you are focusing on in the SDK documentation and in the training kit.

Below I am pasting the “readme” you will find in the package. We really appreciate your feedback! let us know what you like and what you don’t like, what topics you’d like covered in more depth, etc etc and as usual we’ll do our best to make you happy.

Overview

FabrikamShipping is a semi-realistic sample web application that demonstrates how to use the Geneva Framework 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 Geneva Framework 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

Figure 1
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 https://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.

A Brief Walkthrough

Let’s take a quick look at how to use the application, without worrying about how it works for now: we will take care of the implementation details in the next section.

Pretend that you are John, and that you have a package to send. Open a browser and navigate to FabrikamShippings’ URI: https://www.fabrikamshipping.com:8082/FabrikamShipping/.

Since you are not authenticated yet, FabrikamShipping redirects you to the Adatum STS:

Figure 2
Adatum’s STS UI

Use the suggested credentials for John and hit Submit. You’ll land on FabrikamShipping’s main page:

Figure 3
The main page of FabrikamShipping

Click on the New Shipment icon.

Figure 4
The new shipment screen

As you can see, the Sender area is already populated with John’s data: this is thanks to the claims received directly from Adatum with the sign in token. For filling the Recipient form, click on “Search in CRM”; you will get a small dialog, from where you can pick a customer (here I’ll pick Dan Park).

Click the green Submit button.

Figure 5
The new shipment confirmation screen

Everything seems in order: click the Ship It! button.

Figure 6
The shipping label printing screen

Our new shipment has been created! Here there is the label that, once printed, will have to be attached to the package we want to send.

Let’s take a look at what happens when we want to modify our shipment. Click the Go to Home button.

Figure 7
The main screen now shows our new shipment for Dan

The list of shipments now includes the new entry we just created. Let’s say that we want to reroute this shipment: click directly on the Dan Park entry.

Figure 8
The shipping workflow

This page shows the shipment workflow: we are currently in the Pickup state.

Note: FabrikamShipping does not really provide any meaningful backend workflow logic, since the point of this sample is demonstrating identity capabilities rather than how to handle business processes. If for demo purposes you want to advance the state of the shipment, you can do so “manually” by clicking on a hidden button. If you hover the mouse pointer under the state label of the current stage (in this case the label “Running”) you’ll see that it changes into a hand: if you click, the workflow will advance one step.

Click the Reroute Shipment button, change something and click on the Reroute button:

Figure 9
John cannot reroute existing shipments

You will get an error: John does not have enough privileges for modifying existing shipments.

Try to start over, this time using Mary’s credentials. Remember to use a different browser instance, otherwise the Adatum STS will recognize you as John and will issue you a token without even presenting you the credentials gathering UI.

If you try to reroute a shipment, you will discover that you can do it without issues: this is because Mary belongs to the Managers group, and the system takes that into account when assigning privileges.

In the next section we will see some details about what happens behind the scenes for making this possible.

Implementation Details

Figure 10
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 beta 2 of the Geneva Framework. 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

Figure 11
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 https://www.adatumcorporation.com/FederationPassive/ . All the identity content here is a mild customization of the default development STS offered by Geneva Framework Beta2
• 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 the Geneva Framework, 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.
    • https://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 Session_start 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 App_Code/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

Figure 12

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 Geneva Framework 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. Ta-daahhhhh!