4. Federating with Windows Azure ACS

So far, you have seen how to create a custom IP/STS, how to configure a SharePoint web application to use the IP/STS, and how to define a custom claims provider to provide end users with a better experience. You will probably agree, however, that the process is not overly easy, and using an out-of-the-box solution would be better than developing so much code. Luckily, Windows Azure offers ACS, an out-of-the-box IP/STS service that supports custom IPs, as well as such consolidated and well-known authentication engines as Facebook, Windows Live ID, Google, Active Directory Federation Services (AD FS) 2.0, and more. In this section, you will learn how to take advantage of Windows Azure ACS in SharePoint 2013. Before you begin, either create a Windows Azure account and a subscription, or log in to the management portal of Windows Azure, (https://manage.windowsazure.com/) with your existing account.

In the management portal, focus your attention on the Active Directory group of services. Here, you can create a new ACS namespace. Figure 13 illustrates the controls to use.

Figure 13. The UI for creating a new Windows Azure ACS namespace.

Simply provide a name for the target namespace, choosing a name unique in the Windows Azure ACS world, and a region where your service will be provisioned. Click Create, and the new service instance will be ready to work with. Select it, and click the Manage button in the lower command bar of the management portal, to manage the service. You will be presented with a dedicated web management portal like the one shown in Figure 14.

Figure 14. The home page of the web portal for managing a Windows Azure ACS instance.

The home page of the Windows Azure ACS instance management portal provides links to configure all the various aspects of the service. First, you need to choose and configure the IPs. By default, every ACS service instance is configured to authenticate users using Microsoft Account, but you can configure as many IPs as you want, as long as they fall into one of the following categories:

Imagine that you want to provide authentication services using Facebook users’ credentials or Microsoft Account. To use Facebook, first you must create and configure a Facebook app on the Facebook developer portal: log in to the Facebook developer portal (http://developers.facebook.com) and choose to create a new app. You will have to configure at least the Site URL of your app, which will be the URL of the Windows Azure ACS service instance. Figure 15 shows the Facebook app configuration panel.

Figure 15. The page for managing the configuration of a Facebook app.

At the very top of the page, notice the app ID and the app secret for the current app. You will need these to properly configure the Windows Azure ACS integration with Facebook. Behind the scenes, ACS uses OAuth to talk with Facebook and converts the OAuth context information into claims in a security token that will be provided to SharePoint 2013. After creating the Facebook app, go back to the management site for your ACS service and click the Identity Providers menu on the left side of the home page. Choose to add a new Identity Provider and select Facebook as the type. You will be prompted with a page like the one shown in Figure 16.

Figure 16. The page for adding a new IP based on Facebook.

On this page, you will have to configure the Application ID field with the value of the app ID taken in Facebook, and the Application Secret field with the value of the app secret taken from Facebook. Save the new IP.

The next step is to configure the relying parties. Click the Relying Party Applications menu item on the left of the ACS management portal to access the page shown in Figure 17. Here, you can create as many relying parties as you want. Every single relying party will participate in the unique single-sign-on experience provided by the ACS IP. For this example, simply configure a target SharePoint web application. Let’s say the URL of the target SharePoint web application is http://claims.sp2013.local.

Figure 17. The page for creating a new relying party in Windows Azure ACS.

To configure a SharePoint 2013 relying party, aside from providing a name for the relying party, you must also configure the realm and the return URL targeting the /_trust/default.aspx relative URL. Thus, for the sample web application with URL http://claims.sp2013.local/, you need to provide both for the realm and for the return URL the value of http://claims.sp2013.local/_trust/default.aspx. While configuring a new relying party, you will also have the opportunity to choose which IP will be available for each relying party. In this case, assume the default Windows Live ID and Facebook. Next, choose the format of the SAML token that will be sent back to the relying party. For SharePoint 2013, choose a SAML 1.1 token, unless you do not want to customize the out-of-the-box capabilities of SharePoint.

Figure 18 shows the second part of the page for creating a relying party. Notice the options for configuring the IPs, the SAML token format, and the token lifetime in seconds. The token lifetime should be larger than the corresponding value configured in SharePoint, which by default is 600 seconds. For example you can use a value of 3000 seconds or more. The available range for the token lifetime is between 0 and 86400 (1 day).

Figure 18. The second part of the page for creating a new relying party in Windows Azure ACS.

From the same page, you can define the rules for signing and encrypting the tokens, and you can also provide a custom X.509 certificate dedicated to a specific relying party.

After creating one or more relying parties, you need to configure how Windows Azure ACS will handle and eventually transform the claims received from the external IPs before sending the security tokens to the target relying parties. In fact, ACS can apply transformations and translations of claims before sending the security tokens to the target relying party. By default, you can create a set of automatic rules, but if necessary, you can also define simple translation rules that can read a claim and provide another claim or a fixed value as output. Creating rules is mandatory, and by default ACS has no rules defined. Click the Rule Groups menu item on the left of the management site, and then click the Generate button in the middle of the page. Figure 19 illustrates the page for generating rules.

Figure 19. The page for creating rule groups in Windows Azure ACS.

So far, you have configured the Windows Azure ACS service for SharePoint integration. On the ACS management site, there are some other pages for configuring certificates, signing and encryption keys, assigning identities local to the ACS service, and defining administrators of the ACS service. To federate SharePoint 2013 with ACS, however, you don’t need to bother with these. Simply click the Application Integration menu item to see the URLs that you will have to use to integrate SharePoint with ACS. Figure 20 shows the resulting Application Integration page.

Figure 20. The Application Integration page for integrating external applications with Windows Azure ACS.

From this page, you will have to navigate with a web browser to the WS-Federation Metadata URL. There, you will find the X.509 certificate used by ACS to sign the security tokens that will be sent to SharePoint. As described previously, in the “Trusting the IP/STS” section, you will have to copy the text content of the following node:

EntityDescriptor/RoleDescriptor/KeyDescriptor/KeyInfo/X509Data/X509Certificate

Then you must save the copied text into a file with extension .cer. The last thing to do is execute some PowerShell commands to federate SharePoint 2013 with ACS. A PowerShell script to federate Windows Azure ACS with SharePoint 2013 provides a sample PowerShell script for this task.

Add-PSSnapin Microsoft.SharePoint.PowerShell -erroraction SilentlyContinue
$cert = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2(
    "C:\SP2013DR\Ch-20-Claims-Fed-OAuth\ACS-Certificate.cer")
New-SPTrustedRootAuthority -Name "SP2013 ACS certificate" -Certificate $cert
$map0 = New-SPClaimTypeMapping -IncomingClaimType
    "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier"
    -IncomingClaimTypeDisplayName "NameIdentifier" -LocalClaimType
    "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/username"
$map1 = New-SPClaimTypeMapping -IncomingClaimType
    "http://schemas.microsoft.com/accesscontrolservice/2010/07/claims/identityprovider"
    -IncomingClaimTypeDisplayName "IdentityProvider" –SameAsIncoming
$map2 = New-SPClaimTypeMapping -IncomingClaimType
    "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"
    -IncomingClaimTypeDisplayName "Email" -SameAsIncoming
$realm = "http://claims.sp2013.local/_trust/default.aspx"
$signinurl = "https://sp2013-reference.accesscontrol.windows.net:443/v2/wsfederation"
$ip = New-SPTrustedIdentityTokenIssuer -Name "SP2013 ACS" 
    -Description "SP2013 ACS"
    -Realm $realm -ImportTrustCertificate $cert -ClaimsMappings $map0,$map1,$map2
    -SignInUrl $signinurl -IdentifierClaim $map0.InputClaimType

As you can see, the script is almost the same as the one used in the “Registering the IP and mapping claims” section. Now the ACS IP is ready to be used. In SPCA, edit the authentication providers of a target web application and add the new IP to the list of the trusted IPs. Figure 21 shows the UI with two IPs available: the custom one and the ACS IP.

Figure 21. The page for configuring trusted IPs for a target web application.

As soon as you add the new trusted IP, you will be able to authenticate using Windows Azure ACS. Figure 22 shows the authentication options provided to the end users.

Figure 22. The page for selecting the authentication method for accessing a web application.

Figure 23 shows the logon page provided by Windows Azure ACS, where end users can choose to authenticate using Windows Live ID or Facebook. Be aware that the page provided by Windows Azure ACS is autogenerated with a standard and very simple template. However, you can customize this page with your own layout.

Figure 23. The logon page provided by Windows Azure ACS.

Click the Facebook button and you will be redirected to the standard Facebook login page, which will provide information about the target app that is requesting authentication. In the current example, the Facebook app name is SP2013-Reference. Figure 24 shows the Facebook login page.

Figure 24. The login page of Facebook while authenticating through Windows Azure ACS.

After authenticating, the end users will be prompted with a request to authorize the Facebook app (which in reality will be ACS) to access some of the profile information of the currently authenticated user. The profile information and properties will be those you configured while creating the IP in ACS. Facebook will prompt this page (Figure 25) to each end user only the first time he or she authenticates using that Facebook app.

Figure 25. The page of Facebook for authorizing Windows Azure ACS to access the user’s profile information.

Clicking the Go To App button redirects your end user to ACS and then to SharePoint 2013. Remember that you are using a WS-Federation passive requestor, so the user will be redirected passively back and forth between SharePoint, ACS, and the external IP.

If the user is authorized to access SharePoint, you will be able to find a rich set of claims describing his or her digital identity. Figure 26 shows the home page of the sample web application, which browses all the claims available in the currently logged-in user’s profile. As you can see, there are claims providing information about the email, the name, and the Facebook session ID. If necessary, you will be able to read this information from the identity of the current user, which is of type ClaimsIdentity, and, for example, use the Facebook APIs to retrieve additional information, as long as the user provided you with authorization to do so.

Figure 26. The home page of the sample web application after an end user has been authenticated with ACS and Facebook.

Notice that the current web application is also configured for using the custom claims provider created previously. Thus, in the list of users’ claims, you will still find the Fidelity Program Level claims. This means that the custom claims provider augments the claims of an authenticated user regardless of the IP you used to authenticate him or her.