Udostępnij za pośrednictwem

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

  • Artykuł

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

d4c2ae9e-ac50-43c0-a574-fe5250968485

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:

ee9c6176-05ae-4eec-adc4-8302e2dd4afa

Figure 2
Adatum’s STS UI

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

fe753d28-5b97-44f7-a3a1-dc3610f012e3

Figure 3
The main page of FabrikamShipping

Click on the New Shipment icon.

84d9ef41-3a18-499e-af69-77f08e4d1b09

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.

029a8878-1e29-4596-a842-ac988fdc7e2b

Figure 5
The new shipment confirmation screen

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

b6cd586e-6f47-4b6c-bb3c-1d04446c12cc

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.

4e1eb2bd-e9ee-4452-9b1d-b46f5822e88e

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.

8e4c164a-5f6a-49a6-abe2-c08fe29afa1e

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:

75c40a33-9089-49ae-a78a-aade23944566

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

f2391689-6cba-44d9-88bd-1255622939ec

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

39d8bb90-c131-40ea-9ddf-650cf6effcde

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

a3756ce0-9556-4aee-9bf3-75354b93f967

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!

Comments

  • Anonymous
    June 17, 2009
    Hi there. Just tried the link https://www.fabrikamshipping.com:8082/FabrikamShipping/ but it is timing out...

  • Anonymous
    June 17, 2009
    ASP.NET/VS2010 and NETFW 4 Updates to FTP publishing in Visual Studio 2010 WF/WCF/REST/Identity Management Learning by example with 4 - All about the code samples you can download for WF/WCF 4.0 Transactions are bad for REST Announcing FabrikamShipping,

  • Anonymous
    June 17, 2009
    Hi Al, did you install the sample? That URL refers to a location in your machine once the sample is up.

  • Anonymous
    June 18, 2009
    When is this Geneva framework expected to be release? Thanks

  • Anonymous
    June 18, 2009
    Hi Akash, we are on track for releasing before the end of the year HTH

  • Anonymous
    June 19, 2009
    In an October 2008 blog post I highlighted some videos from the PDC sessions, one being Identity Roadmap

  • Anonymous
    February 23, 2011
    Hey Vittorio, Can you explain more about ActAsSts? The doubts I have are:

  • Why do you need it?

  • Wasn't it possible for the WCF to query the same STS it's web front was querying? Also, are there any plans to make a ASP.NET MVC example? Thanks,

  • Anonymous
    February 24, 2011
    Hi humble.apprentice, see blogs.msdn.com/.../delegation-or-traversing-multilayer-architectures.aspx For MVC, see the SaaS version of FabrikamShipping at www.fabrikamshipping.com HTH!

  • Anonymous
    March 01, 2011
    Hey Vittorio, Got the point about ActAsSts but doesn't make it any simpler to implement in my project. I've also been playing around with Fabrikam but I'm not able to take it into my own project. Having said that I found that WIF (i.e. Add STS reference) easily integrates with new web sites instead of new ASP.NET MVC 3 projects. What I mean is, the steps on the kit are actually for web sites and not for projects (if that makes any sense). As far as I get through the MVC route is to 404 because, somehow, it's looking for the STS in c:inetpubwwwroot folder. My solution essentially is two projects: a WCF project and a MVC 3 web site that consumes those WCF services. What I want to do is authenticate a user in the MVC side and have the WCF behave based on who this person is and share state (or not, still thinking if I could use a claim for the only reason I need to share the session). Please give me a hand! Thanks,

  • Anonymous
    March 02, 2011
    the post was for understanding how that works, for step by step instructions for implementing it you can look at  msdn.microsoft.com/.../identitytrainingcourse_websitesandidentitylab2010_topic8 So, look at FabrikamShipping SaaS for handling login to an MVC app; once you've done that, use the lab above for flowing identity to the service

  • Anonymous
    March 03, 2011
    Vittorio, Yes, thank you. I was able to get it to work using these steps www.paraesthesia.com/.../working-with-windows-identity-foundation-in-asp-net-mvc.aspx and, as he says, I'll be getting your book ;). Now I can continue! Cheers,