Introduction
By now each and every SharePoint developer out there should spend their time building SharePoint Apps instead of the old trusted friend of ours; Full Trust Code. Ok, Apps doesn’t solve the equivalent of world hunger in SharePoint at the moment, but that’s a discussion for another time. I assume you get my point. We have two types of apps (we used to have three little monkeys jumping in the bed, but one just bumped his head); Provider hosted apps and SharePoint hosted apps. Without going into details, Provider hosted apps are the apps that are hosted outside of SharePoint on a specific location (URL) and SharePoint hosted apps are running on top of SharePoint (using JavaScript) on a “random” location. This location is called the App Web and is a SharePoint SPWeb with a specific randomly generated URL. That URL could look something like this:
https://app-2d4f884a19b8e8.apps.sp03-apps.com/sites/dev/SharePointApp1
In that URL the first part is something that is randomly generated for each and every instance and deployment of that App. That is why we are required to use a Web Application listening on all incoming host headers, SAN wildcard certificates and users are also required to log in if we’re using Windows Authentication and the base App URL isn’t in the Local Intranet Zone.
There is also another interesting issue specifically when we are using SAML Claims Authentication. Originally this did not work at all with SharePoint and specifically not with AD FS 2.0. One of the requirements of running SharePoint hosted apps with SAML claims is that the identity provider, IdP. (AD FS for instance) supports a wildcard return URL and that it uses the wreply parameter [Source]. Whenever you are trying to authenticate with the app you have to visit the IdP to get your claims and then be redirected back to the app, which is on a “random” URL. Using AD FS 2.0 you have to add a relying party trust for each and every app instance (something your IT people really enjoy doing).
Fortunately all this is resolved in AD FS 3.0 that is shipped with Windows Server 2012 R2! Let’s take a look on how to set it up!
Configure AD FS 3.0
The first thing we need to do is to configure our AD FS 3.0 service. I assume you already have set up and installed AD FS 3.0 on a Windows Server 2012 R2 and that you have Claims authentication working for normal SharePoint sites. If you haven’t come this far yet please take a look at Steve Peschkas end-to-end guide for this, its for SharePoint 2010 and AD FS 2.0 but everything is almost the same.
Here’s our scenario: We’re having one Web Application hosting both the Intranet (intranet.sp03.contoso.com) and the My Site host (mysite.sp03.contoso.com). We would like users with Windows Claims and SAML Claims with users from Active Directory and a third party to be able to use SharePoint Hosted Apps.
The traditional way of setting it up in AD FS is to create two Relying Party Trusts; one for the Intranet and one for the My Site, like this:
Each Relying Party Trust has its unique realm. In this case
urn:sharepoint:contoso:sp03:intranet
and
urn:sharepoint:contoso:sp03:mysite
. And on our Trusted Identity Token Issuer in SharePoint we specify an additional Realm for the My Site, which could look similar to below:
$tit = Get-SPTrustedIdentityTokenIssuer fs.contoso.com
$tit.ProviderRealms.Add( (New-Object System.Uri("https://mysite.sp03.contoso.com")),
"urn:sharepoint:contoso:sp03:mysite")
$tit.Update()
It’s a pretty straightforward approach and works fine.
But there is a much better way. Let’s get rid of this additional Relying Party Trust in AD FS and remove the additional Realm on the Trusted Identity Token Issuer. Well that doesn’t work! Now we get “An error has occurred” when trying to log in to the My Site. Fortunately it is very easy to fix.
First head on over to AD FS and your (now single) Relying Party Trust and choose to edit its Properties. In the properties dialog choose the Endpoints tab and then choose to add a new endpoint by clicking on “Add WS-Federation”. As the Trusted URL type in your My Site host URL and add /_trust/ at the end. Once you click OK it should look something similar to this.
Finish it all by clicking OK. If you now try to log you will still see the same error, and if you take a look at the URL you’re being redirected back to you will see that you are redirected to the Intranet URL, which is the Default endpoint for the Relying Party Trust. So we have to do one more thing to get it to work, and this time on the SharePoint side. We need to tell SharePoint to use the WS-Fed wreply parameter.
From the WS-Fed specification: wreply: This optional parameter is the URL to which responses are directed. Note that this serves roughly the same purpose as the WS-Addressing wsa:ReplyTo header for the WS-Trust SOAP RST messages
Use the following PowerShell script to modify the Trusted Identity Token Issuer to use the wreply parameter:
$tit = Get-SPTrustedIdentityTokenIssuer fs.contoso.com
$tit.UseWReplyParameter = $true
$tit.Update()
Now! Let’s try to log in to the My Site once again using one of the providers we have configured in AD FS. If you have given the correct permissions to the user on the My Site host you will actually see it load and you’re golden.
What about them Apps?
Ok, I know I told you that this post was about getting SharePoint hosted apps to work with SAML Claims and I’ve only shown you how to log on to the My Site. Well, you see if you get this to work there is very little extra you have to do to get the SharePoint Hosted Apps to work. If I now was logged in as a SAML Claims user on the My Site and decided to install an app onto My Site (or any site for that matter), once I try to open the app I will get “An error has occurred on the server” and I will be redirected to the Intranet site.
Just as we did get redirected to the Intranet site when not having the additional Endpoint on the Relying Party trust the same will happen with SharePoint Hosted Apps. The SharePoint Hosted Apps lives in these “random” App URLs and AD FS has no idea on how to and where to redirect the user after trying to authenticate on one of those. Now we have two options; add an endpoint for each and every single instance of our SharePoint Hosted Apps or…in AD FS 3.0 use a wildcard endpoint! Let’s try that!
Just as we added the My Site endpoint to the Relying Party Trust let’s add our App Domain as en endpoint. The URL we need to add as a passive endpoint is formatted like this (of course you should use the app domain that you have configured in your SharePoint environment):
https://*.apps.sp03-apps.com/_trust
Notice that I use a * (star) as the wildcard character at the position where the randomly generated app id is used. It is required that you already have configured the Trusted Identity Token Issuer to use the wreply parameter like we did above, without that you will still get redirected to the default endpoint.
Once done your Relying Party Trust should look like this:
If you now install and/or browse to a SharePoint Hosted App within your environment you will get prompted to authenticate and once that is done you should see your app. The picture below shows a user, stored in a third party IdP federated with AD FS, that has installed the default Visual Studio demo SharePoint Hosted App onto his My Site.
Note: Not a single iisreset was required to set this up! That doesn’t happen often!
Summary
In this post I have shown you how to configure AD FS 3.0 in Windows Server 2012 R2 to use a wildcard redirection endpoint to support Claims users to use SharePoint Hosted Apps in SharePoint 2013. A combination of new features in AD FS 3.0 and correct configuration in SharePoint 2013 was all that was needed.