I finally found (read: made) the time to get back to the “Fun with FabrikamShipping SaaS” series. As in the first installment (where I provided a “script” for going through the creation and use of a small business edition instance) here I will walk you through the onboarding and use of a new Enterprise instance of FabrikamShipping SaaS without going in the implementation details. Later posts (I hate myself when I commit like this) will build on those walkthroughs for explaining how we implemented certain features. I would suggest you skim through the Small Business walkthrough before jumping to this one, as there are few things that I covered at length there and I won’t repeat here.

Demoing the Enterprise edition is a bit more demanding than the Small Business edition, mostly because in the enterprise case we require the customer to have a business identity provider available. Also, every new subscription requires us to spin a new dedicated hosted service, hence we approve very few new ones in the live instance of the demo. The good news is that we provide you with helpers which allow you to experience the demo end to end without paying the complexity costs that the aforementioned two points entail: the enterprise companion and a pre-provisioned enterprise subscription. In this walkthrough I will not make use of any special administrative powers, but I will instead use those two assets exactly in the way in which you would. And without further ado…

Subscribing to an Enterprise Edition instance of FabrikamShipping

Today we’ll walk a mile in the shoes of Joe. Joe handles logistic for AdventureWorks, a mid-size enterprise which crafts customized items on-demand. AdventureWorks invested in Active Directory and keeps its users neatly organized in organizational and functional groups.

AdventureWorks needs to streamline its shipment practices, but does not want to develop an in-house solution; Joe is shopping for a SaaS application which can integrate with AdventureWorks infrastructure and processes, and lands on FabrikamShipping SaaS. The main things about FabrikamShipping which capture Joe’s interest are:

• The promise of easy Single Sign On for all AdventureWorks’ employees to the new instance
• The exclusive use of resources: enterprise instances of FabrikamShipping are guaranteed to run on dedicated compute and DB resources that are not shared with any other enterprise customer, with all the advantages which come with it (complete isolation, chance to fine-tune the amount of instances on which the service runs according to demand, heavy customizations are possible, and so on)
• The possibility to reflect in the application’s access rights the existing hierarchy and attributes defined in AdventureWorks’ AD
• The existence of REST-based programmatic endpoints which would allow the integration of shipment and management capabilities in existing tools and processes

And all this in full SaaS tradition: a new customized instance of FabrikamShipping can be provisioned simply by walking through an online wizard, and after that all that is required for accessing the application is a browser.

The feature set of the Enterprise edition fits the bill nicely, hence Joe goes ahead and subscribes at https://fabrikamshipping.cloudapp.net/. The first few steps are the same ones we saw for the small biz edition.

(here I am using Live ID again, but of course you can use google or facebook just as well. Remember the note about subscriptions being unique per admin subscriber)

Once signed in, you land on the first page of the subscription wizard.

Compared to the corresponding screen in the subscription wizard for the Small Biz edition, you’ll notice two main differences:

• The “3. Users” tab is not present. In tis place there are two tabs, “3. Single Sign On” and “4. Access Policies”. We’ll see the content of both in details, here I’d just like to point out that our general purpose visualization engine is the same and here it is simply reflecting the different kind of info we need to gather for creating an enterprise-type instance.
• There’s a lot more text: that’s for explaining some behind-the-scenes of the demo and setting expectations. I’ll pick up some of those points in this walkthrough

Who reads all that text anyway? Let’s just hit Next.

The Company Data step is precisely the same as the one in the Small Biz edition, all the same considerations apply; to get to something interesting we have to hit Next one more time.

Now things start getting interesting. Rather than paraphrasing, let me paste here what I wrote in the UI:

One of the best advantages of the Enterprise Edition of FabrikamShipping is that it allows your employees to access the application with their corporate credentials: depending on your local setups, they may even be able to gain access to FabrikamShipping without even getting prompted, just like they would access an intranet portal.
The subscription wizard can automatically configure FabrikamShipping to recognize users from your organization, but for doing so it requires a file which describes your network setup. If your company uses Active Directory Federation Services 2.0 (ADFS 2.0) that file is named FederationMetadata.xml: please ask your network administrator to provide it to you and upload it here using the controls below.
If you are not sure about the authentication software used in your organization, please contact your network administrator before going further in the subscription wizard and ask if your infrastructure supports federation or if a different subscription level may better suit your needs.

Modern federation tools such as ADFS2.0 can generate formal descriptions of themselves: information such as which addresses should be used, which certificate should be used to verify signatures and which claims you are willing to disclose about your users can be nicely packaged in a well-known format, in this case WS-Federation metadata. Such descriptions can be automatically consumed by tools and APIs, so that trust relationships can be established automatically without exposing administrators to any of the underlying complexity. As a result, you can set up single sign on between your soon-to-be new instance of FabrikamShipping and your home directory just by uploading a file.

What happens here is that the subscription wizard does some basic validation on the uploaded metadata – for example it verifies that you are not uploading metadata which are already used for another subscriber – then it saves it along with all the other subscription info. At provisioning time, at the end of the wizard, the provisioning engine will use the federation metadata to call some ACS APIs for setting up AdventureWorks as an Identity Provider.

That’s a very crisp demonstration of the PaaS nature of the Windows Azure platform: I don’t have to manage a machine with a federation product on top of it in order to configure SSO, I can just call an API to configure the trust settings and the platform will take care of everything else. That’s pure trust on tap, and who cares about the pipes.

Note 1: You don’t have an ADFS2.0 instance handy? We’ve got you covered! Jump to the last section of the post to learn how to use SelfSTS as a surrogate for this demo.

Note 2: If you use ADFS2.0 here, you’ll need to configure the new instance as a valid relying party. Once your instance will be ready, you’ll get all the necessary information via email.
Also: the claims that FabrikamShipping needs are email, given name, surname name, other phone and group. You can use any claim type as long as they contain the same information, however if you use the schemas.xmlsoap.org URIs things will be much easier (FabrikamShipping will automatically create mappings: see the next screen).

Let’s say that Joe successfully uploaded the metadata file and can now hit Next.

The Access Policies screen is, in my opinion, the most interesting of the entire wizard. Here you decide who in your org can do what in your new instance.

FabrikamShipping instances recognize three application roles:

• Shipping Creators, who can create (but not modify) shipments
• Shipping Managers, who can create AND modify shipments
• Administrators, who can can do all that the Shipping Managers can do and in addition (in a future version of the demo) will have access to some management UI

Those roles are very application-specific, and asking the AdventureWorks administrators to add them in their AD would be needlessly burdening them (note that they can still do it if they choose to). Luckily, they don’t have to: In this screen Joe can determine which individuals in the existing organization will be awarded which application role.

FabrikamShipping is, of course, using claims-based identity under the hood, but the word “claim” never occur on the page. Note how the UI is presenting to the user very easy and intuitive choices: for every role there’s the option to assign it to all users or none, there’s no mention of claims or attributes. If Joe so chooses, he can pick the Advanced option and have access to a further level of sophistication: in that case, the UI offers the possibility of defining more fine-grained rules which assign the application roles only when certain claims with certain values are present. Note that the claim types list has been obtained directly from AdventureWork’s metadata.

Once again, you can see PaaS in action. All the settings Joe is entering here will end up being codified as ACS rules at provisioning time, via management API.

The lower area on the screen queries Joe about how to map the claims coming from AdventureWorks in the user attributes that FabrikamShipping needs to know in order to perform its function (for example, for filling the sender info for shipments). One of the advantages of claims based identity is that often there is no need to pre-provision users, as the necessary user info can be obtained just in time directly at runtime together with the authentication token. In this case AdventureWorks claims are a perfect match for FabrikamShipping, but it may not always be the case (for example instead of having Surname your ADFS2 may offer Last Name, which contains the same info but it is codified as a different claim type).

Once the settings are all in, hitting Next will bring to the last screen of the wizard.

This is again analogous to the last screen in the subscription wizard for Small Biz, in also in this case I am going to defer the explanation for the Windows Azure-PayPal integration to a future post.

Let’s click on the link for monitoring the provisioning status.

Now that’s a surprise! Whereas the workflow for the Small Biz provisioning was just 3 steps long, here the steps are exactly twice that number. But more importantly, some of the steps here are significantly more onerous. You can refer to the session I did at TechEd Europe about details on the provisioning, or to a future post (I feel for my future self, I am really stacking up A LOT of those ) but let me just mention here that one Enterprise Edition instance requires the manual creation of a new hosted service, the dynamic creation of a new Windows Azure package and deployment, the startup of a new web role and so on. That’s all stuff which require resources and some time, which is why we accept very few new Enterprise subscriptions. However! Walking through the provisioning wizard is useful per se, for getting a feeling of how onboarding for an enterprise type SaaS application may look like and for better understanding the source code.

If instead you are interested to play with the end result, we got you covered as well! You can access a pre-provisioned Enterprise instance of FabrikamShipping, named (surprise surprise) AdventureWorks. All the nécessaire for accessing that instance is provided in the FabrikamShipping SaaS companion, which I’ll cover in the next section.

For the purpose of this walkthrough, however, let’s assume that the subscription above gets accepted and processed. After some time, Joe will receive an email containing the text below:

Your instance of FabrikamShipping Enterprise Edition is ready!

The application is available at the address https://fs-adventureworks1.cloudapp.net/. Below you can find some instructions that will help you to get started with your instance.

You can manage your subscription by visiting the FabrikamShipping management console <https://fabrikamshipping.cloudapp.net/SubscriptionConsole/Management/Index>

. Please make sure to use the same account you used when you created the subscription.

Single Sign On

If you signed up using SelfSTS, make sure that the SelfSTS endpoint is active when you access the application. SelfSTS should use the same signing certificate that was active at subscription time. If you configured your tenant using the companion package <http://code.msdn.microsoft.com/fshipsaascompanion> , the SelfSTS should already be configured for you.

If you indicated your ADFS2.0 instance (or equivalent product) at sign-up time, you need to establish Relying Party Trust with your new instance before using it. You can find the federation metadata of the application at the address https://fabrikamshipping.accesscontrol.appfabriclabs.com/FederationMetadata/2007-06/FederationMetadata.xml

Expiration

Your instance will be de-provisioned within 2 days. Once the application is removed we will notify you.

_____

If you want a demonstration of how to use FabrikamShipping, please refer to the documentation at www.fabrikamshipping.com <http://www.fabrikamshipping.com/> . If you want to take a peek at what happens behind the scenes, you can download the FabrikamShipping Source Package <http://code.msdn.microsoft.com/fshipsaassource> which features the source code of the entire demo.

For any question or feedback, please feel free to contact us at fshipsupport@microsoft.com.

Thank you for your interest in the Windows Azure platform, and have fun with FabrikamShipping!

Sincerely,

the Windows Azure Platform Evangelism Team

Microsoft C 2010

The first part of the mail communicates the address at which the new instance is now active. Note the difference between the naming schema we used for Small Business, https://fabrikanshipping-smallbiz.cloudapp.net/<subscribercompany>, and the one we use here, .cloudapp.net">https://fs-<subscribercompany>.cloudapp.net. The first schema betrays its (probably) multitenant architecture, whereas here it’s pretty clear that every enterprise has its own exclusive service. Among the many differences between the two approaches, there is the fact that in the small biz case you use a single SSL certificate for all tenants, whereas here you need to change it for everyone (no wildcards). As you can’t normally obtain a <something>.cloudapp.net certificate, we decided to just use self-signed certs and have the red bar show so that you are aware of what’s going on in there. In a real life app FabrikamShipping would likely offer a “vanity URL” service instead of the naming schema used here, which would eliminate the certificate problem here. Anyway, long story short: later you’ll see a red bar in the browser, and that’s by design.

The Single Sign On section gives indications on how to set up the Relying Party Trust toward FabrikamShipping on your ADFS; of course what you are really doing is pointing to the ACS namespace that FabrikamShipping is leveraging. Once you’ve done that, Joe just needs to follow the link at the beginning of the mail to witness the miracle of federation & SSO unfold in front of his very eyes.

Accessing the AdventureWorks Instance with the Enterprise Companion

When we deployed the live instance of FabrikamShipping, we really thought hard how to make it easy for you guys to play with the demo. For the Small Biz it was easy, all you need is a browser, but the Enterprise posed challenges. Just how many developers have access to one ADFS2 instance to play with? And if they do, just how long they’ll have to wait between their subscription wizard run and when we have time to provision their subscription?

In order to ease things for you, we attached the problem on two fronts:

• We created a self contained WS-Federation STS surrogate, which does not require installation, supports federation metadata generation, uses certificates form the file system and has some limited claim editing capabilities. That’s the (now) well known SelfSTS.
• We used one pre-defined SelfSTS instance to provision one Enterprise edition instance, which we named (surprise!) AdventureWorks, then we made that pre-configured SelfSTS available for download so that everybody can run it on their local machine, pretend that it is the AdventureWorks’s ADFS2  and use it to access the aforementioned pre-provisioned FabrikamShipping SaaS instance.

All that stuff (and more) ended up in the package we call the Enterprise Companion, which (just like the source code package) can be downloaded from code gallery.

Once you download and install the companion, check out the StartHere.htm page: it contains the basic instructions for playing with the AdventureWorks instance (and more, which I will cover in the next “Fun with..” installment).

In fact, all you need to do is to launch the right SelfSTS and navigate to the instance’s address. Let’s do that!

Assuming that you unpacked the companion in the default location, you’ll find the SelfSTS in C:FabrikamShippingSaaS_CompanionassetsOAuthSampleAdventureWorks.SelfSTSSelfSTS.exe. The name already gives away the topic of the next “Fun with” post . If you launch it and you click on Edit Claim Types and Values you’ll see which claims are being sent. You can change the values, but remember that the AdventureWorks instance has been set with this set of claim types: if you change the types, you won’t be able to access the instance.

Close the Edit Claims window, and hit the green button Start; the button will turn red, and SelfSTS will begin listening for requests. At this point you just need to navigate to https://fs-adventureworks1.cloudapp.net/ and that’s it! If you want to verify that the federation exchange is actually taking place, you can use your standard inspection tools (Fiddler, HttpWatch, IE9 dev tools) to double check; below I am using HttpWatch. Remember what I said above about the browser’s red bar being by design here.

…and that’s pretty much it! Taken out of context this is just a web site federating with a WS-Federation IP thru ACS, but if you consider that this instance has been entirely generated from scratch starting from the company info provided during the subscription wizard, just leveraging the management APIs of Windows Azure, SQL Azure and ACS, and that the same machinery can be used again and again and again for producing any custom instance you want, that’s pretty damn impressive. Ah, and of course the only things that are running on premise here are the STS and the user’s browser; everything else is in the cloud

You don’t have ADFS2.0 but you want to sign-up for a new Enterprise Instance?

In the part of the walkthrough covering the subscription wizard I assumed that you have an ADFS2 instance handy from where you could get the required FederationMetadata.xml document, but as I mentioned in the last section we know that it is not always the case for developers. In order to help you to sign up for a new instance even if you don’t have ADFS2 (remember the warnings about us accepting very few new instances), in addition to the AdventureWorks SelfSTS we packed in the Enterprise companion a SECOND SelfSTS instance, that you can modify to your heart’s content and use as a base for creating a new subscription. The reason for which we have two SelfSTSes is that no two subscription can refer to the same IP metadata (for security reasons), hence if you want to create a new subscription you cannot reuse the metadata that come in the SelfSTS described in the last section as those are already tied to the preprovisioned AdventureWorks instance. At the same time, we don’t want to force you to modify that instance of SelfSTS as it would make impossible to you to get to AdventureWorks again (unless you re-download the companion).

The second SelfSTS, which you can find in C:FabrikamShippingSaaS_CompanionassetsSelfSTSSelfSTSbinRelease, out of the box is a copy of the AdventureWorks one. There was no point making it different, because you have to modify it anyway (remember, you are sharing the sample with everybody else who downloaded the companion hence you all need to have different metadata if you want to create new subscriptions). Creating different metadata is pretty simple, in fact all you need to do is to generate a new certificate (the introductory post about SelfSTS explains how) and you’re done.

The last thing you need to do before being ready to use that copy of SelfSTS in the new subscription wizard is to generate the metadata file itself. I often get feature requests about generating the metadata document file from the SelfSTS, but in fact it is very simple tog et one already with today’s UI:

• Click Start on the SelfSTS UI
• Hit the “C” button on the right of the Metadata filed; that will copy on the clipboard the address from which SelfSTS serves the metadata document
• Open notepad, File->Open, paste the metadata address: you’ll get the metadata bits
• Save in a file with .XML extension

Et voila’! Metadata document file a’ la carte, ready to be consumed by the subscription wizard. By the way, did I mention that we provision really few enterprise instances and if you want to experience the demo there’s a preprovisoned instance you can go thru? Ah right, that was 1/2 the post so I did mention that. I’m sorry, it must be the daylight savings

Neext?

Phew, long post is long. This was the second path you can take through FabrikamShipping SaaS to experience how the demo approached the tradeoffs entailed in putting together a SaaS solution. There is a third one, and it’s in fact a sub-path of the Enterprise edition: it shows how an Enterprise instance of FabrikamShipping SaaS offers not only web pages, but also web services which can be used to automate some aspects of the shipping processes. The web services aren’t too interesting per se, what is interesting is how they are secured: using OAuth2 and the autonomous profile for bridging between a business IP and REST services, all going through ACS, of course still being part of the dynamic provisioning that characterized the generation of the instance as a whole. That scenario is going to be the topic of the third and last installment of the “Fun with FabrikamShipping SaaS” series: after those, I’ll start slicing the sample to reach the code and uncover the choices we made, the solutions we found and the code you can reuse for handling the same issues in your own solutions.