Using SharePoint Apps with SAML and FBA Sites in SharePoint 2013

Hopefully by now everyone has heard about the new app model in SharePoint 2013.  There’s a lot of documentation out there about it so I won’t go into exactly what it is.  What you should know is that it’s the preferred model for developing applications going forward.  If you’ve done any development with the new app model so far though, one of the things that you may have noticed is that out of the box, we only ship a framework in Visual Studio 2012 for working with SharePoint sites that use Windows authentication.  A frequent request I’ve heard already is how you can build apps that work with sites that use SAML or forms based authentication.  In this post I’m going to walk through exactly how to do that. 

The first thing to understand is that you need to distinguish between the authentication method used in SharePoint, and the authentication method used for your hosted application.  To provide a very specific example, at RTM, SharePoint apps will not work for the scenario where SharePoint is using SAML authentication and the application itself is also hosted in SharePoint.  However it WILL work if the SharePoint site is using SAML authentication and the application is hosted in Azure or provider-hosted (i.e. running on some non-SharePoint web server elsewhere in your organization).   It’s this latter scenario that this post focuses on – your SharePoint site is using either SAML or FBA authentication, and you are using a SAML or FBA provider-hosted application. 

For reasons I’ll explain a little later, there actually is a very loose coupling between the authentication method you use in your SharePoint site and the authentication you use in your provider-hosted application.  What I mean by that is that I can have a SharePoint site that uses SAML authentication for example, but my provider-hosted application could be using FBA.  I can still get those two to integrate and work because of how the OAuth authentication and authorization works between them.  I’ll try and illustrate this point a little later in this post.

So let’s start with my original scenario – SAML secured SharePoint and provider-hosted application.  As we walk through this you’ll see that everything works almost exactly the same for FBA, and then hopefully you’ll see how the two can interoperate irrespective of whether both SharePoint and the provider-hosted app use the same authentication model or not. 

For this scenario then, I’ve created an SPTrustedIdentityTokenIssuer in SharePoint.  The claims mappings for it include email, UPN, and SIP claims, and email is the identity claim.  I’ve created a new web application in SharePoint that is using only that identity token issuer, and authentication happens in ADFS.  For my provider-hosted application, I’ve just created a simple ASP.NET application that also uses SAML claims.  I’ve also created a separate relying party for it in ADFS and that’s where users for the application authenticate.  I also return the email, UPN and SIP claim for users that authentication to my ASP.NET application.  I first test both the SharePoint and ASP.NET application separately to make sure that the SAML configuration is configured correctly and I’m getting the expected claim values in both applications.  Once that’s squared away then I can move onto the next step.

The next thing I’m going to do is to create an SPAppPrincipal for my new application.  I’m not going to go into great detail on this step because I’ve already discussed it in spots and there’s a fair amount of coverage on this topic on TechNet.  If you aren’t sure about how to do this you can look at this post to get you started:   For simplicity’s sake, I created my applications as high trust apps, which means that I created a certificate that I will use to sign my OAuth tokens, and I’ve configured it SharePoint by created a new SPTrustedSecurityTokenIssuer.  With that in place, I just need to run a little PowerShell to create my new SPAppPrincipal:




#1.  Create a new GUID.  Let’s say it is 09E62669-0C55-47C0-B7FD-6645D13E1D1F.

#2.  Paste it into the ClientId element in the AppManifest.xml file.

#3.  Paste it into the ClientId element in the web.config file for your hosted app.

#4.  Run the following PowerShell to create a new appPrincipal:


$clientId = “1b7e2733-9d25-485b-bf67-2479691374dc”

$spurl =””

$spweb = Get-SPWeb $spurl

$realm = Get-SPAuthenticationRealm -ServiceContext $spweb.Site

$fullAppIdentifier = $clientId + ‘@’ + $realm

$appPrincipal = Register-SPAppPrincipal -NameIdentifier $fullAppIdentifier -Site $spweb -DisplayName “SAML App Model”

Now that my App Principal is created, I can create my application in Visual Studio 2012.  In Visual Studio I open my project that has my ASP.NET SAML application and then I add a new application to it.  I select App for SharePoint 2013, then I use the wizard and configure my app to be a Provider-hosted application.  By the way, this is based on using the Office Developer RTM Preview tools; these tools get a necessary update with Preview 2, which I’ll explain a little later.  When the wizard is complete it will add a new SharePoint app project as well as an ASP.NET project.  In this case I’m not going to use the ASP.NET project it added because I already have my SAML site app that I’m going to use.  You can delete the ASP.NET project it adds if you wish, but it doesn’t hurt anything to leave it there.

Now I need to configure the SharePoint app.  To do that I right-click on the AppManifest.xml file and select View Code.  There are two things I need to change here:

  1. Change the ClientId value from * to the $clientid you used in your PowerShell illustrated above.
  2. Change the Start Page for the application to point to the ASP.NET SAML application you created.  You’ll also want to change the query string to add another value you’ll need to include the SharePoint chrome in your ASP.NET application.  Here’s an example of what I used:{StandardTokens}&SPHostTitle={HostTitle}.  In this case then my ASP.NET SAML site is at the Url, and the page I want to display is default.aspx.

You can close the xml file now, but then double-click on it to open it in the designer.  I do this so I can set the permissions I want to use for the application.  In my demo case here I’m just going to pull back the title of the web using CSOM, but I’ve gone ahead and asked for Read rights to the Site Collection scope.  Once I do that, the configuration of my SharePoint app is complete.

The next thing I need to do is work with my ASP.NET SAML application.  The first thing I’m going to do is to add the web.config entries that I need to use the TokenHelper.cs class that is used to create the OAuth token for SharePoint.  To begin with, here’s the entries that I’ve added to my web.config:


    <add key=”ClientId” value=”6a9fef7d-42d4-4fcd-8bef-ac852dfeb3dd”/>

    <add key=”ClientSecret” value=”9LsXrzcHXn4QJl8lImyYTUOffI9CbxA1cpikqgCA2Ug=”/>

    <add key=”ClientSigningCertificatePath” value=”C:\HighTrustCert\spapps.pfx”/>

    <add key=”ClientSigningCertificatePassword” value=”foobar”/>

    <add key=”IssuerId” value=”e9134021-0180-4b05-9e7e-0a9e5a524965″/>

    <add key=”TrustedProviderName” value=”ADFS”/>

    <add key=”MembershipProviderName” value=”FbaMember”/>

                … (other entries here that are used for SAML auth)


Let’s talk about these entries.  The ClientId and ClientSecret you should be familiar with – these are used by all SharePoint apps.  The ClientSigningCertificatePath and ClientSigningCertificatePassword are used when you are using high trust apps.  In my case I’ve created a certificate and SharePoint trusts it because I’ve created my SPTrustedSecurityTokenIssuer.  In order to sign my OAuth tokens with that certificate, I need to let the TokenHelper class know where the PFX is and the password for it.  The next three tags are ones that you probably have not seen before. 

IssuerId is a value that is used starting with the Preview 2 bits version of the TokenHelper class.  This value should be the ID of the SPTrustedSecurityTokenIssuer that you created.  As noted in my other blogs, you MUST use the -IsTrustBroker flag when you create the SPTrustedSecurityTokenIssuer in order to use it with multiple applications like I am here.  If you don’t remember what the ID is, you can just run the Get-SPTrustedSecurityTokenIssuer cmdlet.  The confusing part of this is that you do NOT want the Id value that it displays!  Instead you want just the first part of the RegisteredIssuerName property, up to but not including the ampersand.  For example, my RegisteredIssuerName is e9134021-0180-4b05-9e7e-0a9e5a524965@72ddc737-72e5-4102-8e1e-91cecbc9884c, so my IssuerId as you see above is e9134021-0180-4b05-9e7e-0a9e5a524965.

The next two attributes – TrustedProviderName and MembershipProviderName – are properties that I’ve added to my TokenHelper helper class.  The TrustedProviderName is used when you’re SharePoint site is using SAML authentication; in that case you need to put in the name of your SPTrustedIdentityTokenIssuer.  The MembershipProviderName is used when your SharePoint site is using FBA.  In that case you need to put the name of the “ASP.NET Membership provider name” you set up in the authentication providers dialog for your web application.

Once the web.config is configured, then I need to add the TokenHelper.cs file to my ASP.NET SAML web application.   There’s three distinct steps here:

  1. Add the TokenHelper.cs class that comes with the Preview 2 bits.  I’ve attached a copy of it to this posting to help simplify things.
  2. Change the TokenHelper.cs class by doing these two things (if you are using the one that comes with Preview 2; I’ve already made these changes in the version I attached to this post):
    1. Delete the “namespace” declaration for the class.
    2. Change the class from “public class TokenHelper” to “public partial class TokenHelper”.  This was the least invasive way I could come up with to add the additional functionality for SAML and FBA.
  3. Add the ClaimsTokenHelper.cs class to the App_Code directory too.

In short, what I’ve done here is I’ve added some additional functionality to support TokenHelper with FBA and SAML sites.  To minimize the amount of changes to the TokenHelper.cs class, I created another partial class.  ASP.NET is stupendously cool about taking partial classes and merging them all together to make one class at runtime.  I did this so that when / if TokenHelper.cs changes in the future, you won’t have to try and sync code changes into it for FBA and SAML support.  Instead you can just remove the namespace and change it to a partial class again, and you should be good to go.  That takes care of getting all your helper classes into your ASP.NET SAML application. 

Now that everything’s there, you can write some code.  This fortunately is the really simple part I think.  In this case we’re just going to add this code to the default.aspx code-behind:




            var sharepointUrl = new Uri(Request.QueryString[“SPHostUrl”]);

            var clientContext = TokenHelper.GetS2SClientContextWithClaimsIdentity(sharepointUrl,

                HttpContext.Current.User, TokenHelper.IdentityClaimType.SMTP, TokenHelper.ClaimProviderType.SAML);

            if (clientContext == null)


                Debug.WriteLine(“couldn’t get a client context”);






                HelloLit.Text = “<h2>Web title retrieved using the managed client object model</h2>” +

                    “<p>” + clientContext.Web.Title + “</p>”;




        catch (Exception ex)


            HelloLit.Text = “There was an error: ” + ex.Message;


A few things to note here.  First, the code should be very much like other code on TechNet that describes how to use a high trust application.  Second, the mystery magic here is in this line of code:

var clientContext = TokenHelper.GetS2SClientContextWithClaimsIdentity(sharepointUrl, HttpContext.Current.User, TokenHelper.IdentityClaimType.SMTP, TokenHelper.ClaimProviderType.SAML);

The GetS2SClientContextWithClaimsIdentity is one of the helper methods.  The only two things that are going to vary in your code are the last two parameters.  The IdentityClaimType.SMTP indicates to the helper that I want to use the SMTP claim to identify the user to SharePoint.  The ClaimProviderType.SAML tells the helper class that my ASP.NET site is using SAML authentication; if it were using FBA then the parameter would be TokenHelper.ClaimProviderType.FBA.  Again – this refers to the authentication being used in my provider-hosted site – NOT the SharePoint site.

Once I get the clientContext, then I can make my CSOM call into SharePoint.  I have a Literal control in my default.aspx page called HelloLit and I just plugging in the data I get into that so that is what will be displayed on my app page.  Pretty simple app obviously. 

Now let’s talk a little bit more about the claims piece of this and how it all works.  I mentioned above that in my call to get a clientContext I configured it to retrieve the SMTP claim to identify the user to SharePoint.  What that means is that I’m going to get the SMTP address from the SMTP claim that I receive in my ASP.NET application – for example,  I’m going to add that to my OAuth token that I send to SharePoint.  When SharePoint gets the OAuth token it’s going to grab that SMTP value and it’s going to do a lookup in the user profile application for a user who has that SMTP address –  Assuming it finds a match, it will then figure out all of the claims for that user as described here:  It will take all of the claims for that user and see if any grant access to the resource being requested – in this case the title of a particular web.  If it does, and if the app itself also has rights to that resource, then SharePoint returns the data we requested in our CSOM call.

This process has some important implications.  First, this is why I said earlier that the authentication of the provider-hosted application and the SharePoint application don’t have to match.  Assume I’m still using SAML on my provider-hosted application and I use that to retrieve an email address.  When I send that over to SharePoint it’s just going to look for the user who has that email address; it doesn’t really care how that user authenticates into a SharePoint site.  So if the email address maps to a profile for a Windows user called darrins, then it will retrieve the info for that user and present it to SharePoint.  If the SharePoint site is using Windows authentication and darrins has rights to that site, then everything will work.  (SIDE NOTE:  There are some differences in one of claims your provider-hosted app needs to send to SharePoint to let it know whether you want to access a SAML, FBA or Windows site, that is beyond the scope of this post and not really relevant to the user info.  For more information see the nii claim documentation here:  That being said – in this version of ClaimsTokenHelper it assumes that if you are asking for SAML info, the SharePoint site is using SAML; if you are asking for FBA info, the SharePoint site is using FBA.  If you want to make different assumptions then you will need to modify ClaimsTokenHelper.cs.

Another implication is that means that these identifying properties – really SMTP, UPN and SIP – need to be unique in your entire user profile application.  So you can’t have a Windows user and a SAML user that both have the same email address for example.  They have to be universally unique or your call may fail.  This is important to remember mostly for test environments, where you may have the same values for an SMTP user and a Windows user.

A third implication is that you need to understand how caching works.  When you make an OAuth request, SharePoint will look in its cache first for a match.  So if you’ve already sent over an OAuth token where SMTP address is, it won’t go back and query the user profile application again; instead it will pull it out of its cache. The reason I bring this up is because if you want to test with different values to see what works and what doesn’t, you should NOT test that by just modifying values in the UPA.  Once a profile is cached for a user we aren’t going to go back and re-retrieve it every time you change a value in the UPA.  The key here is just to use multiple user identities when you’re testing, so you can play with different values in the SMTP and SIP fields to see what works and what doesn’t.

Another point worth pointing out is regarding the application pool account used by your provider-hosted application.  When you’re using Windows authentication on a site I’ve found the default app pool for ASP.NET has no problems retrieving the token signing certificate for the SPTrustedSecurityTokenIssuer.  However, when you switch to using SAML or FBA that no longer works. You need to do two things to remedy this.  First, use a domain account for the application pool for your provider-trusted application.  Second, create a new directory to store the token signing certificate and make sure you grant at least read rights to that directory for the app pool account you use.  Otherwise you will errors in the constructor for TokenHelper.cs because the default app pool account doesn’t have rights to read in the token signing certificate.

There’s one last thing to point out here about the sample code supplied with this posting.  The ClaimsTokenHelper class also works with FBA users, but how does it do this?  In SAML it’s simpler because there are standard claim types that hold values for SMTP and SIP claims.  FBA doesn’t have anything like that – it just has roles.  Since there is no standard, I came up with my own way of passing this information in the roles collection.  For each of my users I created three role claims:  one has a value of SMTP:theUsersSmtpAddress, one is UPN:theUsersUpn, and the other is SIP:theUsersSipAddress. In my helper method to extract the SMTP or SIP address of an FBA user I just get the roles collection for that user and look for a role that starts with either SMTP:, UPN: or SIP: and then I do some string parsing to get the actual value.  If you want to do it some other way then you will need to modify the ClaimsTokenHelper class accordingly.

That pretty much wraps it up.  There should be enough information here to understand how OAuth works and how we can pass information about a user between a provider-hosted application and SharePoint for SharePoint to figure out who the user is and what he or she has access to.  Really the only difference between using it when you’re using SAML versus FBA is the last parameter in the GetS2SClientContextWithClaimsIdentity method.  I’ve added a lot of detail in this post to try and help you understand some of the moving parts and implications of that, but at the end of the day if you just want to write some code fairly quick and not worry about any of that, for the most part you should be able to do so.

Final note:  the attached zip includes a Word version of this posting, along with the token helper class and my claims token helper class that I wrote for this posting.  It also includes my provider-hosted FBA and SAML sites that I used in testing this.

UPDATE:  I updated the attachment on 5/23/2013.  There were two primary changes – 1) was to update the ClaimsTokenHelper.cs so to reflect a change of a constant name used in TokenHelper.cs that was modified for the Preview 2 release.  2) was to add an additional parameter to the main method in ClaimsTokenHelper so that you can configure it to use an App Only Token instead of App + User token.  All the samples are updated to reflect these changes.

You can download the attachment here:

18 thoughts on “Using SharePoint Apps with SAML and FBA Sites in SharePoint 2013

  1. Thanks for the great work on this!

    As mentioned a key to making this work is to make sure the user SAML email address is not duplicated in UPA/site collection with another Windows user. In Visual Studio 2013, ClaimsTokenHelper.cs needs to be updated with the application namespace and the following code:

    private const int TokenLifetimeMinutes = 1000000;

    public static void TrustAllCertificates()
    ServicePointManager.ServerCertificateValidationCallback =
    ((sender, certificate, chain, sslPolicyErrors) => true);

    Kirk Evens does a good job breaking down the oAuth request in this blog:


  2. We need assistance usint the S2S and STS in the Sharepoint 2013 security model with ADFS and SAML claims to Ouath for both App only calls to Sharepoint and App plus User context. We aer using ADFS and Shiboleth as our trusted Security Provider. ADFS hands of to Shiboleth who Authenticates, and Shiboleth redirects to a Third Party STS to get the claims associated with the user. These claims are then passed back to sharepoint in a security token. We need to extract the user context and pass it to sharepoint with the app actor token.


  3. Hi Steve,

    I’m having a WCF service which interacts with SharePoint protected with ADFS. Right now I’m getting unauthorized if I follow the exact steps you have to get an app working. Any idea how to do it in case of WCF?


    • What are you trying to get from SharePoint? I’m assuming you are using the app model and oauth; if not then I would say that’s your problem. If you are using those to access SharePoint then it really doesn’t matter what your client is (WCF or anything else).


  4. Hi Steve,

    Thanks for the article.
    My question is: we have SharePoint configured with ADFS now planning to build Provider hosted app. Do I have to add Provider hosted app site as relying party in ADFS.



    • Technically no, but you may want to. It’s a longer story than I can really do in a blog post comment, but in short how you authenticate to a provider hosted app doesn’t have to have any relationship to how you authenticate to SharePoint.


  5. Based on your web.config in source code I have added my SharePoint site as realm. When I click on the app instance it redirects to SharePoint hosted app site then goes to ADFS and redirects SharePoint home page instead of app site. Can you please let me know what am I missing.


  6. Good blog, is the following possible :

    FBA SharePoint site using custom auth provider eg username / passwords stored in custom DB
    Provider App hosted in IIS but allow anonymousness access

    User login to SharePoint
    Navigate to provider app
    Construct a SharePoint Context just with the details passed
    Get the Username from SharePoint via the context API


  7. Thanks a lot of such a article, this information is not present anywhere in internet and hence helped me a lot in understanding authentication part of S2S apps.
    Can you please look into the attachment, looks like it’s broken.


  8. Hi Steve, good blog. We used your information to migrate our SharePoint Online Add-in into a SharePoint 2013 solution in which we are using the High Trust authentication within an FBA enabled environment.
    All things are looking to work fine except one thing…when a user is given permissions through an active directory group we are getting the following error: Access denied. You do not have permission to perform this action or access this resource.
    When we give that user directly access on a SharePoint object it works like a charm but from an Active Directory group we get the above exception.

    DO you have any idea why this is and what can be done about it?


    • Hi Steve, it turned out to be a missing synchronization between the AD groups and the user profile. After a successfull synchronization of AD users and groups and waiting a day for refreshing the tokens it works perfectly.

      Thanks again for the blog and the information!


  9. Hi Steve Peschka, thank you very much for this great detailed post. I followed your blog configuration. I used your customized TokenHelper.cs. It works fine, but sometimes I got a 401 unauthorized error. I am doing some investigation and have a question about your customized TokenHelper.cs file on row number 801. You set there the lifetime of the outer token to 10 minutes. But on row number 778 you set the actor token lifetime to 1000000 minutes. Is this by design?


    • We fixed this issue today by increasing the lifetime of the outer token. The outer token lifetime (10 minutes) needs to be higher than the HighTrustAccessTokenLifetime (12 hours). Another reason why it was not working in our situation, is because we save the SharePointHighTrustSamlContext in the session like they do for SharePointAcsContext and SharePointHighTrustContext. In your situation the tokens will always recreated for each new request and you dont have a dependancy with the lifetime of the tokens.


      • Hi K.H., From your last post are you saying you stopped saving the context to Session? Or was just increasing the out token lifetime more than 12 hours enough? Any info appreciated!


  10. Hi Steve,

    Thank you for the great article and the effort to put all this info in one place!

    It appears I cannot download the attachment files thou. Do you think you can make them available again?

    Thanks in advance!


  11. Be aware that in the sample code it adds the SMTP claim to the actor token (the first part of IssueToken) and SP is now not allowing user claims on the actor token as of the April 2020 updates for on-premise. To fix it just comment out these lines in the creation of the actor token-

    //if (addSamlClaim) {​​​​​​​​
    // actorClaims.Add(new JsonWebTokenClaim(samlClaimType, samlClaimValue));

    The ULS logs have an event id dem4o that gets logged when this code is present, SP just was not doing the security check.


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s