Configuring SharePoint Hosted Apps with SAML Authentication in SharePoint 2013
NOTE: This is a sampling of some content we're preparing for working with SharePoint Apps and SAML authentication. More content will be coming, and once everything is packaged up and a distribution channel determined I'll post a general announcement on the Share-n-Dipity blog.
The concept of using SAML authentication with SharePoint-hosted apps was been a painful proposition when SharePoint 2013 first shipped. The big stumbling block has been that because of the way the host names are created for SharePoint-hosted apps - each application installed gets its own unique host name - it required an identity provider that supported a wildcard reply Url. At the time SharePoint shipped, we did not have such an identity provider. Fortunately, when ADFS 3.0 came out with Windows Server 2012 R2, it included this functionality. That now enables us to configure an environment in which we can use SharePoint-hosted apps on web applications that are secured with SAML authentication. What I'm going to show here is sort of a medium level overview of what needs to be done. I'm going to attach a Word document to this post that also includes pictures at each main step along the way, so download the document to get (literally) a clearer picture of how to do each of these things. Now, here are the steps to get this working:
- Follow the standard steps to create a SAML-secured zone on a web application: create an SPTrustedIdentityTokenIssuer, create a new web app (if necessary, or another zone on an existing web app), and create one or more site collections. Login to at least one site collection to validate that ADFS is configured correctly for your web application zone. NOTE: You MUST use ADFS 3.0 or later; prior versions will not work.
POWERSHELL TO CREATE SPTRUSTEDIDENTITYTOKENISSUER:
$cert = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2("c:\ adfs_tokensigning.cer")
New-SPTrustedRootAuthority -Name "ADFS Token Signing Certificate" -Certificate $cert
$map = New-SPClaimTypeMapping -IncomingClaimType "https://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress" -IncomingClaimTypeDisplayName "EmailAddress" -SameAsIncoming
$map2 = New-SPClaimTypeMapping -IncomingClaimType "https://schemas.microsoft.com/ws/2008/06/identity/claims/role" -IncomingClaimTypeDisplayName "Role" -SameAsIncoming
$map3 = New-SPClaimTypeMapping -IncomingClaimType "https://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn" -IncomingClaimTypeDisplayName "UPN" -SameAsIncoming
$realm = "urn:sharepoint:spsamlapps"
$ap = New-SPTrustedIdentityTokenIssuer -Name "ADFS v3" -Description "ADFS v3" -realm $realm -ImportTrustCertificate $cert -ClaimsMappings $map,$map2,$map3 -SignInUrl "https://yourAdfsFarm.yourDomain.com/adfs/ls" -IdentifierClaim "https://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"
- Follow the standard steps to configure your environment to support SharePoint-hosted apps, including but not limited to creating a new web application with no host header that will listen for incoming app requests.
- Create an app catalog for the web application referred to in the first step above if you have not already done so.
- Configure the web application that listens for SharePoint-hosted apps to use only SAML authentication, and configure it to use the same SPTrustedIdentityTokenIssuer that you used to secure the web application described in the first step above.
- Configure the SPTrustedIdentityTokenIssuer to use the wreply parameter, with PowerShell script such as the following:
POWERSHELL TO HAVE SPTRUSTEDIDENTITYTOKENISSUER USE WREPLY:
$ap = get-sptrustedidentitytokenissuer -identity "ADFS v3"
$ap.UseWReplyParameter = $true
$ap.Update()
- Add an additional WS-Federation endpoint to the relying party in ADFS that your SPTrustedIdentityTokenIssuer is using. Add the Url as a wildcard prefix for the Url of your web application that is listening for SharePoint-hosted apps. For example, in this scenario the Url of the listener web application was https://ltapps.vbtoys.com, so we added an endpoint of https://*. ltapps.vbtoys.com/_trust/. The “/_trust/” is added to the end because that’s where ADFS needs to redirect the user to after he or she has been authenticated, and is standard configuration for SharePoint with SAML authentication.
NOTE: An important distinction in the configuration for this scenario is that, unlike when you have a second content web application use an SPTrustedIdentityTokenIssuer, you do not need to add the URI for the app’s listener web application to the ProviderRealms property of the SPTrustedIdentityTokenIssuer, nor do you need to create a second relying party in ADFS.