Creating applications in SharePoint 2010, specifically the hosted environment Office365/SharePoint Online, when you want to communicate with applications and services in Windows Azure you are limited to client-side communications or using Business Connectivity Services (BCS). This is because all server-side code must run in the sandbox and that blocks all external web service calls.
What’s the Problem?
However when you create an application in Windows Azure, or anything that wants to talk to SharePoint Online, regardless of the tools you use to connect to SharePoint Online (REST or OData / CSOM / Web Services / WebClient) you’ll quickly find you are having authentication issues. The reason for this is because SharePoint Online is configured for claims authentication and use Microsoft Online (MSO) for authentication. That’s why when you go to your SharePoint Online site, you are sent to what looks similar to a LiveID sign in page but it is branded for Office 365:
Signin Page for LiveID
So…. what’s the problem? The root problem is that none of the tools I mentioned above (REST or OData / CSOM / Web Services / WebClient) understand how to authenticate to a system that’s configured for claims based authentication (CBA). Thankfully each one can be rewired a bit as to make it work but it takes a bit of work.
Quick Primer on Claims Based Authentication
If you aren’t versed in CBA, let me point to two great links where you can get more information. Check out MSDN’s Patterns & Practices group: An Introduction to Claims but my favorite explanation one is by Donovan Follette’s real world example here . Basically here’s how it works, borrowing a picture from the P&P article:
Login Flow
The user tries to hit a resource that’s protected by CBA such as a site collection in SharePoint Online (SPO). Because the user isn’t authenticated, the user is sent to a sign in page which in this case is Microsoft Online (MSO). The user then logs (#1) in and is given a token (#2) that’s in the format of Security Assertion Markup Language (SAML). The user puts this token in a cookie in the HTTP header and goes back to the SPO site collection (#3). Because the site collection gets the authentication token and the hosting SharePoint installation trusts the source that created the token (using some digital signatures & trust configurations that were set up ahead of time by administrators), the user is allowed in.
OK… So… How Do you Fix the Tools for CBA?
Here’s the root of the problem: none of the four tools know how to authenticate with MSO and how to pass the SAML token along to the target system. The light bulb might have just gone off for a few of you… you may have been trying to programmatically authenticate with MSO and then make your request only to get a 401 - Access Denied. The reason you get that is because you aren’t passing along your token in the header of your requests… you’re being denied because you’re trying to hit the resource as an unauthenticated (aka: anonymous) user.
The big picture fix for this is very simple:
- Programmatically authenticate with MSO
- Parse the response to get the SAML token
- Attach the token to all requests to site collections in SharePoint Online
Thankfully a lot of other folks have done a lot of the heavy lifting for us. I don’t want to duplicate the work they’ve done and you should read these. Each of them have various code downloads for things you need (like the Windows Identity Foundation runtime & SDK & the CSOM redistributable (& don’t forget about the CSOM redistributable service pack 1 x86 or x64 ). Almost all of them have associated code downloads filled with helpful stuff.
- MSDN:
- Steve Peshka: Mr. Claims for SharePoint
- Wictor Wilen: SharePoint MCM & MVP who created some great code samples
- Chris Johnson: Former Microsoft Sr. Technical Project Manager who created a nice rollup app demonstrating what you learned from above links
Up Next…
Now that you understand how the authentication works & the challenges each of our client tools & techniques has with it, we need to take a moment to get past the first step: authenticate with MSO to get a SAML token!