SharePoint 2013 with SAML Claims and SharePoint Hosted Apps

Tags: SharePoint 2013, AD FS, Claims, Windows Server 2012 R2, Apps

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:

AD FS Relying Party Trusts

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.

Relying Party Trust Properties

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:

The App wildcard Endpoint

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.

Just another crappy app

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.

10 Comments

  • Johan Nissjen said

    Very good post, thank you, would it be possible to have one for AD FS 3.0 with Claims and SharePoint Provider-hosted Apps?

  • Johan Nissjen said

    Very good post, thank you, would it be possible to have one for AD FS 3.0 with Claims and SharePoint Provider-hosted Apps?

  • Johan Nissjen said

    Very good post, thank you, would it be possible to have one for AD FS 3.0 with Claims and SharePoint Provider-hosted Apps?

  • Vladimir said

    Hi Wictor

    thank you for your blog post.

    We are using a multi-tenant deployment, and it seems that the apps always use the DefaultProviderRealm paramater.

    We have many Relaying Party Trusts and additional Realm URNs configured for each tenant, and we also utilise the ADFS Home Realm Discovery setting

    Set-AdfsRelyingPartyTrust -TargetName "Tenant1Site" -ClaimsProviderName @("Tenant1")

    it seems this is incompatible with SharePoint apps because of this scenario

    changed default provider realm = apps urn - eg urn:sharepointapps.company.com:sharepoint

    which can't be "homed" to a particular claim trust provider because all our tenants will use it

    then when the app gets hit, it redirects from the current tenant's site to the Default Provider Realm urn (the app realm urn)
    and then ADFS prompts them to select their Home Realm, which is not ideal...

    if they pick their realm, apps seem to work

    I was hoping that the app would use the existing urn: config for that tenant which would resolve this issue

    eg: tenant 1 hits tenant1 site on urn:tenant1site.com:sharepoint

    in there we have the additional endpoint for https://*.sharepointapps.com/_trust/

    then when the app loads, it read that endpoint config which is set to their particular home realm, and they achieve single sign on

    but it seems apps always use the DefaultProviderRealm in the SPTrustedIdentityTokenIssuer which doesn't work well in a hosted multi-tenant enviornment

    any suggestions, or any plans to address this ?

    Regards,
    Vladimir

  • Anuj Jain said

    Hi Wictor,

    We have done the configuration as suggested here. Single sign in works perfectly. We are facing an issue with Single Sign out (Logout) when we have multiple share point sites covered by a single wild card WS-Fed entry in the relying party. On logout, the ADFS initiates the cleanup request for just the url which was browsed for signing in. All other sharepoint sites do not get a clean up request and hence still allow user to browse them freely, whereas, they should have been signed out.

    Have you made single sign out work with Wild Card WS-Fed endpoints?

    Regards,
    Anuj Jain

Comments have been disabled for this content.

About Wictor...

Wictor Wilén is the Nordic Digital Workplace Lead working at Avanade. Wictor has achieved the Microsoft Certified Architect (MCA) - SharePoint 2010, Microsoft Certified Solutions Master (MCSM) - SharePoint  and Microsoft Certified Master (MCM) - SharePoint 2010 certifications. He has also been awarded Microsoft Most Valuable Professional (MVP) for seven consecutive years.

And a word from our sponsors...