UPDATE 2012-02-01: A new and better approach to this is detailed in a new Visual Guide - Visual guide to Azure Access Control Services authentication with SharePoint 2010.
Using Windows Live ID as login provider for SharePoint is a really huge thing. It makes the scenario for public facing web sites, extranets etc. much more easier, for instance there is no need to maintain passwords and users in the same degree. For SharePoint 2007 there is no native support for this, so I built a custom Live ID login provider (available at http://spwla.codeplex.com), but SharePoint 2010 has native support for claims based access. And that is what’s on the menu for tonight…
This post, and the subsequent ones, will show you how to enable Windows Live ID on a SharePoint 2010 farm (SPF or SPS). I will do a visual approach using a lot of screenshots. It has not been an easy path since there are no official guidance on this subject (at the time of this writing), so I’m going to throw in a couple of steps where you can fail miserably while setting it up. Big thanks to Paul Schaeflein who also walked the hard path and took some hits to get this to work! Although there are a couple of available blog posts out there on this issue, some of the are very sparse on the details (why?) and some even contains faulty instructions. Just to safe up on this - the instructions works on my machines and I’ve been able to reproduce these steps a number of times. If you have any suggestions or comments, just leave them here and I’ll try to (get someone to) answer them…
So what are we waiting for, let’s get the party started. I have to warn you - if you don’t like certificates - stop reading!
Background
While I will explain more in details as we move along I think it is important to have a little heads up on claims based access and Windows Live ID. First of all (passive) claims based access is based on the simple scenario where a client/user (subject) trying to access a site (also called Relying Party/RP). This RP has distributed the login procedure to one or more trusted parties called Identity Providers (IP). In our case SharePoint is the RP and Live ID is the IP and you of course are the subject. When the subject tries to access the RP, the subject will be redirected to the IP where the actual logon process is taking place. By attaching cookies to the response and redirecting the user back to the RP with a set of (encrypted) claims the RP can finally authenticate the user. For a better understanding I recommend you to read A guide to Claims-based Identity and Access Control.
Windows Live ID (WLID) will take care of the login and send back a unique ID to the SharePoint site. This unique ID is the only claim WLID will give you. (Unfortunately you cannot get the correct e-mail address or the name of the user.) SharePoint will first verify the validity of the encrypted security token (containing the claims) before actually starting the AuthN and AuthZ process using the unique ID as username in SharePoint. You will later see how we give access to these unique ID’s.
Another important thing to keep in mind is that WLID have two “zones”; INT and PROD. The PROD zone is what you normally use when logging in to Hotmail etc. The INT zone is used for development and testing and have a completely different account database, so you need to have accounts in the INT zone to continue, more about this in a little bit. You cannot skip the INT zone, you have to register your site there first before applying for approval in the PROD zone.
The steps provided here is only for the INT environment. For PROD it is basically the same and the post is long enough as it is…
Registering the site
Before even starting to configure the SharePoint site we need to register our site for usage with Windows Live ID. This is done using the Microsoft Service Manager web application located at http://msm.live.com/. You log in to this service using you normal (PROD) Windows Live ID account.
In the left menu click on Register Your Site (1). This will bring up the Register Your Site page where you should enter the name of your site, use a descriptive name (2) and the DNS Name of your site (3). The DNS Name is important! Here you must specify a DNS Name, which we will later change into a URI, or rather URN. Write something random such as
wictor.live
.
The DNS Name will be used as a SAML Audience when the security token is sent back and it will be verified by SharePoint. According to the SAML specification the audience must be a URI (a URN or URL). If you use a URL then WLID will for some reason remove the protocol from the audience when sending it back to the RP and SharePoint will throw an exception ([InvalidOperationException: This operation is not supported for a relative URI.] System.Uri.GetLeftPart(UriPartial part)). This might change in the future.
Finally you have to specify that you will use Windows Live ID (4). Click Submit to continue.
You will get a confirmation screen. Click Yes to confirm and proceed to the next step
After a few seconds you will be presented with the results. If anything goes wrong you need to go back and edit your registration accordingly - but it shouldn’t if you followed these steps.
Click on the Go to Manage Your Site link. In the drop-down (1) select the site that you just registered and then click on the Modify Editable Site Properties link (2).
The next screen allows you to edit the properties of the site. First of all check the Show advanced properties check box to enable more options.
First we need to rename the Domain name (1) and set our real domain name to use. Then we need to replace the dummy DNS name (2) with a URN, in this case I use
urn:wictorslivesite:int
. Remember not to specify a URL, it just won’t work as of now. The third thing to edit is the Default Return Url (3); this must be an HTTPS url pointing to the
/_trust/default.aspx page
, for instance
https://extranet.corp.local/_trust/default.aspx
. This is the URL that the IP will post back the results to. Finally we have to edit the Expire Cookie URL (4). Just fix the URL and never mind the actual page (you can implement such a page if you feel to at a later time).
Then scroll down a bit on the page until you reach Override Authentication Policy, this step is crucial. Select MBI_FED_SSL in the drop-down. And when you’re done click Submit (at the top of the page).
Verify and confirm your changes by clicking Yes on the next screen. Take a screenshot and/or notes all these changes.
That’s it. Your site is now configured. Actually you can configure a bunch of more features here - but stick to these as of now…
Let’s move on to the SharePoint Server.
Certificates
Claims based authentication uses certificates for encryption and signing and you have to trust the certificate of the IP on your SharePoint servers. The following steps must be done on all WFE’s in the farm.
To get the IP certificate; browse to federation metadata URL: https://nexus.passport-int.com/federationmetadata2/2007-06/federationmetadata.xml (this is for the INT zone). Then copy the inner text from the first X509Certificate node. Open up the Notepad application and paste the text and then save the file as LiveID-INT.cer. Make sure that you only get the inner text of the element.
Now you have the certificate in a file and you need to import it to the correct locations on the SharePoint Server(s). It is actually required to be stored locally on three different locations. Open mmc.exe and add the Certificates snap-in. When you select to add it you must first select to use the Computer Account to manage the accounts for and select to use the Local computer as computer to manage.
Expand the tree until you reach SharePoint > Certificates then right-click on the node and Select All Tasks > Import…
In the import wizard that appears locate the LiveID-INT.cer file you just created and then click Next > Next > Finish. That’s the first one.
Repeat this procedure for the Trusted Root Certification Authority and Trusted People. Don’t worry if you don’t have a Certificates sub-node. It will be created when you import the certificate.
Now we’re one step closer and it is time to get dirty with some PowerShell. You could of course have done this step using PowerShell, but I leave that for another crafty blogger to show how… Just remember to do this on all WFE’s!
Create the STS provider
To create the Trusted Identity Token Issuer, that we will use to configure as the login provider for the Web Applications, we fire up PowerShell. This step will not be that “visual” as the previous ones, since none of these commands can be run using the standard SharePoint user interface. I guess it’s just a matter of time until someone makes a neat add-on with these simple commands…
I’ll give you the script first and then explains all the involved steps:
1: asnp microsoft.sharepoint.powershell
2: $realm = "urn:wictorslivesite:int"
3: $certfile = "C:\Temp\LiveID-INT.cer"
4: $rootcert = Get-PfxCertificate $certfile
5: New-SPTrustedRootAuthority "Live ID INT Root Authority" -Certificate $rootcert
6: $emailclaim = New-SPClaimTypeMapping -IncomingClaimType "http://schemas.xmlsoap.org/claims/EmailAddress" -IncomingClaimTypeDisplayName "http://schemas.xmlsoap.org/claims/EmailAddress" -SameAsIncoming
7: $upnclaim = New-SPClaimTypeMapping -IncomingClaimType "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier" -IncomingClaimTypeDisplayName "UPN" -LocalClaimType "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn"
8: $authp = New-SPTrustedIdentityTokenIssuer -Name "LiveID INT" -Description "LiveID INT" -Realm $realm -ImportTrustCertificate $certfile -ClaimsMappings $emailclaim,$upnclaim -SignInUrl "https://login.live-int.com/login.srf" -IdentifierClaim "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier"
The first line just loads the SharePoint PowerShell Snapin (1), asnp is a shortcut for Add-PSSnapin and saves you a cpl of keystrokes. Then we set three local properties; realm corresponds to the DNS Name (that is the URN), certfile points to the location where you saved the LiveID-INT.cer file and the rootcert is the certificate loaded in as an object.
Make sure not to make any typos in the claims URN’s - been there, done that!
Then we add the certificate to a SharePoint trusted Root Authority, using the New-SPTrustedRootAuthority cmdlet. You can verify that it is correctly imported by going to Central Adminitration > Security > Manage Trust:
Then we need to create two claims mappings; one for e-mail (line 6) and one for the identifier (line 7). The claim mappings defines how the incoming claims are mapped to the SharePoint tokens. These two claims are then sent into the New-SPTrustedIdentityProvider cmdlet (line 8) and here is where the magic happens. This cmdlet creates a new trusted identity provider with a name and description, we instruct it which claims mappings to use and which claim is the identifier claim. We are also specifying the URL for the WLID (INT zone) login page.
Once these commands are executed, we are ready to head on over to the UI and create a Web Application. By all means, if you prefer to do the rest using PowerShell, feel free to do it.
If you are fiddling back and forwards using different registered Live ID services, you can switch the Realm using the DefaultProviderRealm property of the Trusted Identity Provider object (authp). Don’t forget to call Update() on the object… You can only have one provider for each service, even if the realms differ.
Create the Web Application
Fire up Central Administration and go to Application Management > Manage web applications. Click New to create a new Web Application.
First of all you need to select to use Claims Based Authentication. Then enter a Name for your web application, use the port 443 (SSL) and (in this case) configure the host header to match the domain name that you entered while registering the WLID service. Just standard stuff so far.
Under Security Configuration make sure that you select Use Secure Sockets Layer (SSL).
Under Claims Authentication Types leave Windows Authentication enabled if you like, but make sure to check Trusted Identity Provider checkbox and then check the LiveID INT provider, the one we created using PowerShell.
Once done click OK to create the Web Application.
We’re almost there just a few steps more…
Create the Site Collection
Once the Web Application is created you can directly click on the Create Site Collection link. Enter name and description for the site, and also specify which template to use.
Now it is time to give some permissions to this site collection. Assume that we did not select any Windows Authentication when creating the Web Application, then we can only add Live ID users, right?
If you don’t have a WLID account in the INT domain it is time to get one now. Open up a new browser window. Go to https://accountservices.passport-int.net/ and sign up for a new account or sign in using one of your existing INT accounts. (Stability of the INT domains are not 100% :-). When you have signed up or logged in click on Credentials and then View your unique ID.
You will now see a screen with your unique ID; write it down, copy it or remember it…
Close the browser and return to the Central Administration where you started creating a Site Collection. Now paste or write this unique ID and append
@live.com
in the Primary Site Collection Administrator. But, make sure to convert all characters to lowercase, otherwise you will not be able to log in later:
Then click OK to create the Site Collection.
Final configurations
Before browsing to the site we need to make some final adjustment in the IIS. To be precise we will add a certificate to the site. You can use a certificate that you have acquired for your site or when testing just use a Self-Signed, which I will show you here.
To create a Self-Signed certificate start the IIS Manager and select the server. In the Features View double-click the Server Certificates module.
Then click Create Self-Signed Certificate in the Actions bar to the right and follow the instructions. Mostly next-next-finish.
The final configuration is to use this certificate on the Web Application. Choose the Web Application you created in SharePoint in the IIS Manager (1), then click on Bindings (2), select to edit the only binding you have (3) and choose the SSL certificate you just created in the drop-down (4). Click OK and close everything down.
That’s it! Let’s see how it behaves…
Taking it for a test drive
Now open up a web browser and go to the web application you have created using the domain name you specified when creating it, make sure to use https. You should see the standard warning in the browser that the certificate is not valid (add it as trusted if you want to skip this warning in the future), otherwise just click the continue link.
If you have several authentication providers you will see the new SharePoint 2010 Sign In screen with a drop-down where you can choose the authentication provider you would like to use to log in with. If you only have one, in this case the WLID, you will be redirected to the WLID Log In screen - the same will happen if you select LiveID in the drop-down.
If you get an error stating We’re unable to complete your request, like below, you most certainly have not used the correct Realm when creating the trusted identity provider using PowerShell. Make sure that the Realm and the DNS Name in the Live ID Service Manager are exactly the same, case sensitive and all.
The Windows Live ID sign in screen should look as expected, just the same as logging in to other Live ID services. Enter your INT username and password (remember this is still the INT zone).
If you remembered your username and password correctly you will very soon see the beautiful SharePoint 2010 scenery:
Note that your username and display name will be exactly the same as the unique id you have for that user. How to fix this is scheduled for a later post :)
Next steps
So, there you have it. It’s a handful of steps to complete and you have to make sure not to mistype anything. I will continue this series with some more info that could be of great use when setting this up - hopefully not as long as this one though…