Fun with FabrikamShipping SaaS III: Programmatic Use of the Enterprise Edition via OData, OAuth2

Welcome to the last installment of the “Fun with FabrikamShipping SaaS” series. The “fun” blogs are meant to help you walking through the demo; once we are done with that, I’ll finally start to talk about what makes the demo tick: architecture, code and all those nice things.

The walkthrough I am discussing here is in fact a sub-scenario of the Enterprise Edition subscription: if you didn’t read the post which described it, you should really go through it and follow the steps it describes before getting into this post.

Last time Joe successfully subscribed to FabrikamShipping SaaS on behalf of its company, AdventureWorks, and obtained a dedicated Enterprise Edition instance: a dedicated web application running in Windows Azure (at https://fs-adventureworks1.cloudapp.net/) that AdventureWorks employees can SSO into, which authorizes them according to their role at AdventureWorks and the rules Joe established at sign-up time, etc etc.

Delivering the application functionality via web application is the most classic delivery vehicle for a SaaS solution, however it is not the only one. Let’s say that AdventureWorks would like to embed shipping capabilities in their existing LoB applications, rather than having their employees switch between the LoB app UI and the FabrikamShipping UI. In other words, Joe would like to be able to access FabrikamShipping via APIs, too. And being Joe a very trendy guy, he wants to access those APIs in REST style.

Few years ago, delivering on that requirement would have been a messy, sticky business: bridging enterprise and REST has always been less than straightforward, especially where access control plays an important part. luckily today it is much clearer what a solution should look like. I’ll get to the architecture in a later post, here I will just describe the solution from Joe’s perspective.

Wen Joe got his FabrikamShipping instance provisioned, he got a  web application listening at https://fs-adventureworks1.cloudapp.net/ for AdventureWorks users to interact with the app. The web application is secured via WS-Federation, configured to trust the AdventureWorks STS via ACS at onboarding time (the magic which enables SSO).

Joe also got a programmatic OData endpoint, https://fs-adventureworks1.cloudapp.net/FabrikamShippingDataService, to exclusive use for AdventureWorks as well. This endpoint is secured using OAuth2. Thanks to the fact that FabrikamShipping is using ACS, the same trust relationship can be piggybacked for enabling AdventureWorks employees to securely invoke the OData service without having to provision extra credentials just to call the service. Once again, the details will come in a later post: just to whet your appetite, let’s say that the client consuming the OData service can acquire a SAML token via WS-Trust from the local active directory and trade it in at the ACS with a REST-friendly token which can be used to secure calls to the OData service via OAuth2.

So many words for describing what in the end is a very simple and straightforward user experience. Want to experience that yourself? The Enterprise Companion once again comes to the rescue. The SelfSTS provided with the companion includes the necessary endpoint to enable this scenario, and it includes a test client which uses it for invoking the OData endpoint form the pre-provisioned AdventureWorks instance.

Turn on the companion’s SelfSTS as described in the “Accessing the AdventureWorks Instance with the Enterprise Companion” section in the former post.

Once you’ve done that, open the test client solution (C:\FabrikamShippingSaaS_Companion\assets\OAuthSample\TestClient.sln) and hit F5.

The test client advertises the endpoints that will be involved in the call. The identity provider is the local AdventureWorks SelfSTS, the endpoint we are going to get the REST-friendly token is the OAuth2 (draft 13) endpoint on ACS, and the OData service is the one exposed by FabrikamShipping from the AdventureWorks instance. Hit enter and watch closely what happens.

After few seconds, the test client announces that it successfully requested & received a SAML token :

right after that, the test client trades that SAML token for a REST-friendly token from ACS:

Note that the token from ACS already contains the result of the rules which map claims from AdventureWorks into the roles specific to FabrikamShipping.

At this point we are ready to invoke the OData service:

The test client made a big deal out of all the intermediary steps, but that’s of course just for didactic purposes: in a real solution all those steps would take place in the blink of an eye, and completely transparently.

There you have it! Joe was able to invoke an OData service by using his active directory identity and piggybacking the settings already in place for the web SSO. What’s more, this service endpoint was dynamically provisioned as part of the SaaS solution, just like the web application: that’s handy for AdventureWorks, and good business for Fabrikam.

Alrighty, at this point you are able to walk though the main paths of the FabrikamShipping SaaS demo: creating and accessing a small business subscription, creating and accessing an enterprise subscription, and accessing the enterprise subscription programmatically via REST. Now we can finally start to chat about what’s inside the solution.