And I know that my user a1@adfs has permissions because I have the role "ADFS test users" in my visitors group and I know that the user can access it the site without problems! And I even checked some days before and SharePoint showed that the user had permissions to the site.

So, how come SharePoint is telling me now that the user doesn't have permissions?

SharePoint's external token

SharePoint stores in the content database a token of the user, per site collection, where it saves a set of claims that represent the user. This set of claims contains, among other things, what groups/roles the user is a member of. As you might be guessing now, when we check the permissions of a user, we use this set of claims to compute the permissions. 

Other non-interactive operations like alerts, not only "Check permissions", use this token of the user when doing security trimming.

The external token has also a timestamp of when it was last updated. We don't want to have stale tokens in our databases, so we will update it from time to time. How often it is updated depends on the operation that forces the refresh.

In one of my previous posts (SharePoint 2013 authentication lifetime settings) I explained how often we refresh this token (token-timeout) and how that value can be changed.

How does SharePoint refresh the external token?

At this point, you can guess that if we are not getting the expected results when we check the permissions of a user, then it means that the external token of the user doesn't have all of the user's groups/roles in it and that's why the dialog is showing less permissions than expected. But why is the external token missing the roles?

When SharePoint retrieves the token from the database and decides that it needs to update the token (the last token update is beyond the token timeout), it asks the local STS to build a new token of the user. When the web application uses Windows authentication, the local STS just needs to contact the AD domain where the user account resides and it gets all the information it needs from there, builds the new token and saves it in the content database. This is why when the web application uses Windows authentication, it just works. There is a scenario where it may not: the user was just added to a group right after the token was updated.

However, in our original scenario, we are using ADFS authentication, so when the local STS tries to get the information about the user, it just doesn't know where to look for it and then it can only build the minimal token it can with the little information he can get from the user. This means that the token will not contain any roles and thus it will make "Check permissions" fail to compute the correct permissions.

Does this mean that the external token will always be missing the roles? How come it sometimes work? As I said above, we are dealing here with non-interactive logons of the user. In the case of an interactive logon (i.e., the user is actually accessing the site), the interactive identity of the user holds all the claims of the user, and if the login happens to trigger a refresh of the token (by default, if the token is older than 60 minutes), then the token will be refreshed with this interactive identity and then it will contain all the claims as expected. From this point, "Check permissions" will work as expected until the token is refreshed again.

But why?

What the local STS actually does when building the token (either in a interactive or not logon) is the following:

• It gets all of the registered claim providers and keeps those providers that can do claim augmentation (SPClaimProvider.SupportsEntityInformation returns true).
• For each of those providers that do augmentation, then calls their FillClaimsForEntity() method.
• The providers will return a list of claims to add to the identity and the STS will aggregate them in the final token.

The problem with SharePoint's default claim providers is that none support augmenting the claims of an trusted provider identity. If you think about it, it makes sense because there is no certain way to understand where the information of this user comes from, so it's impossible to know who to contact to get it when we are refreshing the token of the user.

These are the default claim providers in an out-of-the-box SharePoint farm:

SharePoint 2010

Name                  SupportsEntityInformation

----                  -------------------------

System                                     True

AD                                        False

AllUsers                                  False

Forms                                     False

SharePoint 2013

Name                        SupportsEntityInformation

----                        -------------------------

System                                           True

AD                                              False

AllUsers                                        False

Forms                                           False

User Profile Claim Provider                      True

As you can see, only System supports claims augmentation. In SharePoint 2013 we also have User Profile Claim Provider that supports claims augmentation, but it only works on Windows identities, so it cannot help with our problem.

The solution

In this case, the solution is to create a custom claim provider that will understand how our farm is built and will do the claims augmentation. The general idea of such a claim provider would be:

• When it gets the identity to augment, understand if it has to do the augmentation or not.
• If it does, get the information from the user. This can be as simple as getting this information from AD with DirectoryServices or maybe do a LDAP query to whatever directory stores the information.
• When it has the information from the user, build the role claims from it and return them to STS.

I have created a sample Visual Studio project with a claim provider that does the above. You can find the code here: https://github.com/jesusfer/FedRolesCP

For the cases explained above, the custom claim provider can be the starting point for a more specific provider. The example can be directly used in an environment such as:

• The SharePoint farm and the users reside in the same forest.
• The ADFS server is configured with Active Directoy as authentication and user backend.

The master branch of the project is compatible with SharePoint 2013. However, there is a tag with a SharePoint 2010 compatible version.

Several of our customers have already implemented successfully a custom claim provider starting from this code to solve problems with alerts, when checking user's permissions and even with SharePoint 2013 Apps authentication. Nearly everywhere where trusted role identities are involved.

This project aims to solve this problem by creating a custom timer job that will download the ADFS federation metadata and check if the primary token signing certificate has changed. If it has changed, then it'll udpate SharePoint with the new certificate.

The project currently includes:

• A custom timer job definition.
• A custom admin page in Central Administration that allows an admin to select which providers to update.
• Custom ULS logging.

You can find the code in the following Github project: https://github.com/jesusfer/ADFSCertificateUpdater

One of the caveats when using ADFS as authentication provider in SharePoint is that out-of-the-box there is no way to automatically update the ADFS token signing certificate when it's changed in the ADFS server. Many times, the ADFS admins leave the ADFS certificate auto rollover enabled. This means that ADFS will automatically create a new self-signed certificate and will change the primary certificate some days before the current one expires. Unless the SharePoint admin knows when the certificate rollover will happen, which isn't usually the case, it will most probably render the ADFS authentication with SharePoint broken until the SharePoint admin realizes the certificate was changed and updates the certificate in the ADFS settings.

A workaround

At the end of this post, you can find a PowerShell script that can be run in a scheduled task. What this function does is:

1. Using the AD FS Diagnostics PowerShell module, request a Security Token from the ADFS server in order to get the current primary signing certificate.
2. If the current primary certificate is not already in the SharePoint trust store, it will add it to the store.
3. Then, if the current primary certificate in ADFS is different from the current signing certificate in the ADFS login provider in SharePoint, it will update the provider to use this new certificate.

• FederationServer: this is the host name of the ADFS server, for example, fs.contoso.com
• TrustedProvider: this is the name of the AD FS login provider in SharePoint, something like "Contoso ADFS". The following PowerShell will output the names of the trusted providers configured in SharePoint: Get-SPTrustedIdentityTokenIssuer | ft Name

Last thoughts

Even if you are not using the auto certificate rollover feature in ADFS and you manually update the token signing certificate, the above PowerShell can also help to update the certificate.

Finally, the requested Security Token only includes the last certificate in the certificate chain. This means that, if the ADFS signing certificate is not self-signed, then only the last certificate in the chain will be imported into SharePoint. SharePoint documentation says that you need to import all the certificates in the chain. However, this should have been done when initially configuring the ADFS provider in SharePoint so it's not something you should need to care about when updating the certificate, unless you have changed the CA that issues the certificate.

Get the script from GitHub: Update-AdfsSigningCertificate.ps1

In the times of classic authentication, you could only grant permissions to users by grouping them into Active Directory groups or by granting permissions directly to users. With claims authentication we can now virtually use any claim that the users have to grant permissions.

The high level view of this process would be:

1. Identify which claims the users have and which one you want to use.
2. Build the claim value you will use to grant permissions.
3. Add the claim to the item permissions.

Identify the current claims

Depending on the authentication provider configured in the web application the users will have some claims when they log in. After login, SharePoint augments those claims with several claim providers which add more claims to the user identity. One of these claim providers is the User Profile application and this is why it makes sense to have a running User Profile Application to keep the user properties up to date. 

You can use the following PowerShell to get the installed claim providers in the farm:

Get-SPClaimProvider | ft -auto DisplayName,IsEnabled,IsUsedByDefault,IsVisible

DisplayName                 IsEnabled IsUsedByDefault IsVisible

-----------                 --------- --------------- ---------

System                           True            True      True

Active Directory                 True           False      True

All Users                        True            True      True

Forms Auth                       True           False      True

User Profile Claim Provider      True            True      True

LDAPCP                           True            True      True

The way to check which claims a user has, would be to use a custom web part to show those claims based on the current user. This is an example of such a web part (Helloitsliam.ClaimsViewerWebPart.wsp, can't find the current link for download):

In the example I'm going to use for this post, I want to be able to give permissions to sites using the Department the users have in Active Directory. My lab uses AD FS to authenticate the users.

If you check the screenshot above, you can see that there is no Department claim that we can use to grant permissions so we are going to have to add the claim there.

Adding a custom claim

This is the overview of the steps we need to do to make AD FS forward a new claim to SharePoint and make SharePoint use that claim when authenticating the user:

1. Check if AD FS supports the claim we want to use. If not, create a new Claim description.
2. Modify the AD FS Relying Party to add the claim to the token sent to SharePoint.
3. Modify the trust relationship in SharePoint to accept this new claim and use it in the Claims Identity.

Adding a Claim description in AD FS

We open the AD FS Management console and go to AD FS -> Service -> Claim Descriptions. Here we can find the list of claims supported by AD FS. I don't see a Department claim, so we are going to have to add it.

A new Claim description can be added directly via the console or with PowerShell. My preferred method is always PowerShell so we use the following command:

Add-AdfsClaimDescription -Name Department -ShortName department -ClaimType http://custom-claims/department -IsAccepted $true -IsOffered $true

You can find the documentation of this command here.

After this, we can see the claim in the list and use it in our relying party:

Add the new claim to the Relying party

Just like any LDAP attribute, we need to modify the current Claim rules in the Relying party to pass this claim to SharePoint. Just open the current claim rules and add the new claim to the current rules. You will most probably have a "Send LDAP attributes as claims" so you can directly add the new claim there or add a new rule if you want.

From now on, every new login will include the new claim.

Add the claim to the SharePoint trust

Now that the security token sent by AD FS includes the new token, we need to make SharePoint aware of this new claim.

When we set up AD FS in SharePoint, we create a Trusted Identity Token Issuer. In this issuer object, we define the claims accepted by SharePoint from it and define some mappings from the claim type to the internal claim type.

So, what claim types are currently accepted by SharePoint? As usual, we use PowerShell for this:

Get-SPTrustedIdentityTokenIssuer | % { Write-Host $_.Name; $_.ClaimTypes | ft -auto }

And this is the current output:

ADFS UPN

http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress

http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn

http://schemas.microsoft.com/ws/2008/06/identity/claims/role

http://schemas.microsoft.com/ws/2008/06/identity/claims/primarysid

To add the new claim type we do the following:

$ctype = "http://custom-claims/department"

# First, we need to define the new encoding character for this new claim

# Make sure that your character is not used in another encoding, it is above 500 (0x01F5) and not an uppercase or whitespace character.

New-SPClaimTypeEncoding -EncodingCharacter ([Convert]::ToChar(501)) -ClaimType $ctype

# Add the mapping

$ti = Get-SPTrustedIdentityTokenIssuer "ADFS UPN"

$ti.ClaimTypes.Add($ctype)

$map = New-SPClaimTypeMapping -IncomingClaimType $ctype -IncomingClaimTypeDisplayName "Department" –SameAsIncoming

Add-SPClaimTypeMapping –Identity $map –TrustedIdentityTokenIssuer $ti

# Confirm the mapping works, the following should return an encoded claim.

(New-SPClaimsPrincipal -TrustedIdentityTokenIssuer "ADFS UPN" -ClaimValue "Dept 1" -ClaimType "http://custom-claims/department").ToEncodedString()

From now on, SharePoint accepts the incoming Department claim from AD FS and adds it to the claims identity that represents the logged in user.

We could even check the claims viewer webpart again and we will now see the new claim in the identity:

Granting permissions using the new claim

The next step, once the claim we want to use is available, is to grant permission using this claim. Ideally, we would like to directly type the value of the new claim in People Picker and get it correctly resolved by People Picker. Unfortunately, SharePoint does not do this out of the box and we will need to use a custom claim provider if we want this feature.

Out of the box we can use PowerShell to grant permissions.

$web = Get-SPWeb https://team.2013.net

# This will use the Claim Provider used by the TrustedIdentityTokenIssuer

$claim = New-SPClaimsPrincipal -TrustedIdentityTokenIssuer "ADFS UPN" -ClaimValue "Dept 1" -ClaimType "http://custom-claims/department"

## If there is no Claim Provider that can resolve the claim, New-SPUser will fail but we can directly grant permissions using RoleAssignments

# Example: directly grant Read permissions on the web

[Microsoft.SharePoint.SPRoleAssignment] $roleAssignment = New-Object Microsoft.SharePoint.SPRoleAssignment($claim.ToEncodedString(), "", "Department 1", "")

$roleAssignment.RoleDefinitionBindings.Add($web.RoleDefinitions["Read"])

$web.RoleAssignments.Add($roleAssignment)

# Example: add the claim to a SharePoint group

$group = $web.Groups["members"]

$group.AddUser($claim.ToEncodedString(), "", "Department 1", "")

However, the best and more user friendly approach is to use a custom claim provider that can be configured to resolve custom claims. LDAPCP is truly awesome.

With it, we just have to configure a new claim mapping…

 …and People Picker will work like a charm:

The issue

If you are using SharePoint with AD FS, you may know how these two products interact. The following summarizes the login process:

1. When the user is not logged in, SharePoint will redirect the user to the AD FS login page.
2. The user enters his credentials.
3. AD FS validates the credentials and creates a Security Token with the user's claims.
4. AD FS makes the user's browser or client POST this token to SharePoint's /_trust endpoint.
5. SharePoint validates the digital signature on the token and stores the token in the Distributed Cache.
6. SharePoint creates a FedAuth cookie with some information about the session. The contents of the cookie are Base 64 encoded and sent to the client. Inside the cookie we can find the user identity claim, the scope, expiration and a couple more things.

For example, this is the content of a FedAuth cookie in my lab.

 <?xmlversion="1.0" encoding="utf-8"?><SP>05.t|adfs email|a1@email.local,05.t|adfs email|a1@email.local,130866957906607856,True,[signature],https://adfs.2013.sps/</SP>

Depending on the configuration of the AD FS provider in SharePoint, one of the claims in the AD FS token will be used as identity claim in SharePoint. This claims will be used to uniquely identify the user in SharePoint and thus it's very important to choose a property of the user that's unique. Most organizations choose the e-mail address or the User-Principal-Name.

Some organizations may want to use a different identity claim like the social security number or another fiscal information of the user. These organizations may consider this kind of information sensitive and they even may want to protect this information.

Since anybody can decode Base64, anybody can see the contents of the FedAuth cookie. In the one above, I have highlighted the identity claim. One way to protect this information would be to encrypt the value of the cookie.

The solution

SharePoint does not offer cookie encryption out of the box so if you want to encrypt this value, custom code needs to be created.

One possible solution could be a custom HttpModule that will encrypt the cookie when set by SharePoint and decrypt it when SharePoint receives it.

The custom HttpModule would attach to:

• BeginRequest: to decrypt any FedAuth cookie that may come with the client's request.
• EndRequest: to encrypt any FedAuth cookie that may be set by SharePoint to the client.

How should we encrypt the value?

I'm my opinion, a symmetric algorithm would be ideal over an asymetric. Symmetric algorithms are usually faster and don't require a key pair to work, just a password. How to choose a proper password and salt would be the interesting part. It has to be a password/salt combination that doesn't change between application pool recycles and both need to be the same in every web server. As an example, the code below uses a password and salt stored in the web.config of the application.

The code

The code consists of two parts: the custom HttpModule and a utility class to handle the encryption. This utility class I got from the following link: http://www.superstarcoders.com/blogs/posts/symmetric-encryption-in-c-sharp.aspx

This should be compiled to a DLL. The easiest way to install it would be to copy the DLL into the bin folder of the web application and then add the module with IIS Manager.

HttpModule

using System;

using System.Collections.Generic;

using System.Linq;

using System.Security.Cryptography;

using System.Text;

using System.Web;

using System.Web.Configuration;

namespace jesusfer.SharePoint.FedAuthEncryptionModule

{

    /// <summary>

    /// This is a HttpModule that will encrypt the value of a certain cookie when it's set by the server and will decrypt it when sent by the client.

    ///

    /// This is helpful in cases when the FedAuth cookie includes an identity claim that can be considered sensitive.

    /// </summary>

    public class FedAuthEncryptionModule : IHttpModule

    {

        private string m_CookieName = "FedAuth";

        // If true, unencrypted FedAuth cookies will still be allowed.

        // If false, unecrypted FedAuth cookies will be removed, which will force SPS to ask the user to authenticate again.

        private bool m_AllowUnencryptedCookies;

        private bool m_Enabled;

        private string m_Password;

        private string m_Salt;

        /*

         * These are the expected settings keys in the web.config:

         *

         * <configuration>

         * ...

         *    <appSettings>

         *       <add key="FedAuthEncryptionEnabled" value="true"/>

         *       <add key="FedAuthEncryptionPassword" value="FedAuthEncryptionPassword"/>

         *       <add key="FedAuthEncryptionSalt" value="FedAuthEncryptionSalt"/>

         *       <add key="FedAuthEncryptionAllowUnencryptedCookies" value="true"/>

         *    </appSettings>

         * ...

         * </configuration>

         * */

        public String ModuleName

        {

            get { return "CookieEncryptModule"; }

        }

        public void Dispose() { }

        public void Init(HttpApplication application)

        {

            // Read configuration

            m_Enabled = bool.Parse(WebConfigurationManager.AppSettings["FedAuthEncryptionEnabled"]);

            m_AllowUnencryptedCookies = bool.Parse(WebConfigurationManager.AppSettings["FedAuthEncryptionAllowUnencryptedCookies"]);

            m_Password = WebConfigurationManager.AppSettings["FedAuthEncryptionPassword"];

            m_Salt = WebConfigurationManager.AppSettings["FedAuthEncryptionSalt"];

            // Attach to the BeginRequest event so that we can check if the cookie is encrypted to decrypt it

            application.BeginRequest += new EventHandler(this.Application_BeginRequest);

            // Attach to the EndRequest event so that we can encrypt the coookie when it's set by SharePoint

            application.EndRequest += new EventHandler(this.Application_EndRequest);

        }

        /// <summary>

        /// This method will encrypt the cookie when it's set by SharePoint

        /// </summary>

        /// <param name="sender"></param>

        /// <param name="e"></param>

        private void Application_EndRequest(object sender, EventArgs e)

        {

            HttpApplication application = (HttpApplication)sender;

            HttpContext context = application.Context;

            if (m_Enabled && context.Response.Cookies.AllKeys.Contains(m_CookieName))

            {

                try

                {

                    // Try encrypting the cookie value and setting it as the new value

                    string plain = context.Response.Cookies[m_CookieName].Value;

                    string encrypted = CipherUtility.Encrypt<AesManaged>(plain, m_Password, m_Salt);

                    context.Response.Cookies[m_CookieName].Value = encrypted;

                }

                catch

                {

                    // Do nothing

                }

            }

        }

        /// <summary>

        /// This method will decrypt the cookie when sent by the client

        /// </summary>

        /// <param name="sender"></param>

        /// <param name="e"></param>

        private void Application_BeginRequest(object sender, EventArgs e)

        {

            HttpApplication application = (HttpApplication)sender;

            HttpContext context = application.Context;

            // m_enabled can be added as a condition here too, but that will break any FedAuth cookie that is encrypted and still valid

            if (m_Enabled && context.Request.Cookies.AllKeys.Contains(m_CookieName))

            {

                try

                {

                    // Try decrypting the cookie value and setting it as the new value

                    string encryped = context.Request.Cookies[m_CookieName].Value;

                    string decrypted = CipherUtility.Decrypt<AesManaged>(encryped, m_Password, m_Salt);

                    context.Request.Cookies[m_CookieName].Value = decrypted;

                }

                catch

                {

                    // We can choose to remove the cookie if decryption failed

                    if (!m_AllowUnencryptedCookies)

                    {

                        context.Request.Cookies.Remove(m_CookieName);

                    }

                }

            }

        }

    }

}

Utility Class

using System;

using System.Collections.Generic;

using System.IO;

using System.Linq;

using System.Security.Cryptography;

using System.Text;

namespace jesusfer.SharePoint.FedAuthEncryptionModule

{

    /// This class was copied from http://www.superstarcoders.com/blogs/posts/symmetric-encryption-in-c-sharp.aspx

    public class CipherUtility

    {

        public static string Encrypt<T>(string value, string password, string salt) where T : SymmetricAlgorithm, new()

        {

            DeriveBytes rgb = new Rfc2898DeriveBytes(password, Encoding.Unicode.GetBytes(salt));

            SymmetricAlgorithm algorithm = new T();

            byte[] rgbKey = rgb.GetBytes(algorithm.KeySize >> 3);

            byte[] rgbIV = rgb.GetBytes(algorithm.BlockSize >> 3);

            ICryptoTransform transform = algorithm.CreateEncryptor(rgbKey, rgbIV);

            using (MemoryStream buffer = new MemoryStream())

            {

                using (CryptoStream stream = new CryptoStream(buffer, transform, CryptoStreamMode.Write))

                {

                    using (StreamWriter writer = new StreamWriter(stream, Encoding.Unicode))

                    {

                        writer.Write(value);

                    }

                }

                return Convert.ToBase64String(buffer.ToArray());

            }

        }

        public static string Decrypt<T>(string text, string password, string salt) where T : SymmetricAlgorithm, new()

        {

            DeriveBytes rgb = new Rfc2898DeriveBytes(password, Encoding.Unicode.GetBytes(salt));

            SymmetricAlgorithm algorithm = new T();

            byte[] rgbKey = rgb.GetBytes(algorithm.KeySize >> 3);

            byte[] rgbIV = rgb.GetBytes(algorithm.BlockSize >> 3);

            ICryptoTransform transform = algorithm.CreateDecryptor(rgbKey, rgbIV);

            using (MemoryStream buffer = new MemoryStream(Convert.FromBase64String(text)))

            {

                using (CryptoStream stream = new CryptoStream(buffer, transform, CryptoStreamMode.Read))

                {

                    using (StreamReader reader = new StreamReader(stream, Encoding.Unicode))

                    {

                        return reader.ReadToEnd();

                    }

                }

            }

        }

    }

}

When built, the token gets a lifetime that depends on the authentication provider used by the user to authenticate. For Windows and Forms (FBA) authentication, the lifetime is a fixed amount of time that is set on the Security Token Service configuration. For trusted providers like AD FS, the lifetime depends on the validity of the security token POSTed to SharePoint's /_trust/ endpoint.

This lifetime has a direct impact in how often the user will need to authenticate. When the user makes a request, the token in the cache is checked and if it is expired, then the user needs to authenticate again.

As explained above, the lifetime can be configured in the STS for Windows and Forms authentication. The current values can be reviewed with Get-SPSecurityTokenServiceConfig.

WindowsTokenLifetime

This lifetime applies to user sessions authenticated with Windows Integrated Authentication (NTLM/Kerberos).

The default value is 10 hours.

$sts = Get-SPSecurityTokenServiceConfig

$sts.WindowsTokenLifetime = New-TimeSpan -Hours 10

$sts.Update()

FormsTokenLifetime

The same as above but applies to Forms/FBA authentication sessions.

The default value is also 10 hours.

$sts = Get-SPSecurityTokenServiceConfig

$sts.FormsTokenLifetime = New-TimeSpan -Hours 10

$sts.Update()

LogonTokenCacheExpirationWindow

The lifetime of a token in the cache is deducted the window value when checking if it is expired. This means that the real lifetime of the token will be less than expected. The following diagram can be helpful to understand when a token is valid and the roles the lifetime and window play in the expiration.

The default value for the expiration window is 10 minutes.

$sts = Get-SPSecurityTokenServiceConfig

$sts.LogonTokenCacheExpirationWindow = New-TimeSpan -Minutes 10

$sts.Update()

CookieLifetime

When using FBA or a trusted provider, SharePoint will set a cookie on the client called FedAuth. I'll not go into the details of what's inside the FedAuth cookie. Of course, the FedAuth cookie will have by default a certain lifetime. Session cookies can be configured too making the cookie invalid after the closing the browser and then bypassing the value in this settings.

The default value is 5 days.

$sts = Get-SPSecurityTokenServiceConfig

$sts.CookieLifetime = New-TimeSpan -Days 5

$sts.Update()

So, if we are using a trusted provider, for example, AD FS, how do we control how long the token will be valid? It will depend on how you can configure the STS that creates the token but if it is AD FS then you can set this in the Relying Party configuration.

ADFS RP's TokenLifetime

This setting will change for how long the security token created by AD FS is valid. SharePoint will use this lifetime and set its security token lifetime to the same value.

The default value is 60 minutes (which appears as 0 if the setting has not been changed in the RP).

You can check the current settings with:

Get-AdfsRelyingPartyTrust | ft -auto Name,TokenLifetime

And to change the value for a RP:

Set-AdfsRelyingPartyTrust -TargetName "SharePoint 2013" -TokenLifetime 30

These are the main settings related to session lifetimes when dealing with user authentication. There are other values for applications and services but are kind of exotic and you won't usually need to change those.

There is one extra setting that is interesting to have in mind although it does not affect the authentication of a user.

Token-timeout

SharePoint stores in the content database a token of the user that includes some claims like group memberships. This token needs to be refreshed from time to time to make features like "Check permissions" and other some security trimmed features work as expected.

These tokens will be refreshed at least every 24 hours. Some operations that require having a fresher token, like "Check permissions", will refresh the token at least every 60 minutes.

TokenTimeout will change the default 24 hours timeout to a greater or smaller amount. If the value is still greater than 60 minutes, some operations will still use 60 minutes as minimum.

$cs = [Microsoft.SharePoint.Administration.SPWebService]::ContentService

$cs.TokenTimeout = New-TimeSpan -Minutes 5

$cs.Update()

This new feature can only be managed via PowerShell:

• New-SPWebApplicationAppDomain
• Get-SPWebApplicationAppDomain
• Remove-SPWebApplicationAppDomain

How does it work?

 Let’s suppose you already have a web application working and you are using some apps and these apps use an app web. This means that the app web URL will be something similar to:

<app prefix> - <app id>.<app domain>

Say that your SharePoint farm was being used only in your company’s network with an internal URL but now you want to publish it via a reverse proxy. To do this, you are extending the current web application to a new Zone so you are adding a new public URL to the web application. In RTM, there was no way to configure SharePoint to use several URLs for your Apps which meant that you needed to use a real public App domain.

Now, it is possible to have AAMs for Apps!

My test web application uses http://2013.test.local as the public URL in the Default zone. I have configured the app domain as test-apps.local and I have followed Configure an environment for apps for SharePoint (SharePoint 2013) to configure my farm.

Right now, if I access my test App the URL it uses is the following:

http://app-f28aaf39627eed.test-apps.local/AppWithWeb/Pages/Default.aspx

Since this domain uses an internal TLD it won’t be possible to access the App from outside the corporate network.

What if you use a reverse proxy that rewrites the URL? Then, you might be able to access the App’s web but other things like Javascript object model might not work correctly.

How do you add a new App domain?

You can find the steps in the following Technet article: Enable apps in AAM or host-header environments for SharePoint 2013

Going back to our test lab, I now want to publish my web application so that my site will now be also available with the URL https://2013.test.net. I will use a reverse proxy to do the SSL termination here. I won’t explain how to do the SSL termination but this are my new AAM collection for this web application after extending:

After extending the web application and configuring my reverse proxy to proxy all requests from https://2012.test.net to http://2013.test.net:81, I got access to the site with the new URL. However, when I click in the App, I still get redirected to http://app-f28aaf39627eed.test-apps.local.

We need to do two things to have a different URL:

1. Create the URL/Zone mappings.
2. Enable the mapping feature in the ContentService.

1. Creating the mappings

First, we need to use the New-SPWebApplicationAppDomain cmdlet to assign the URLs. We will be adding the URL for the Default zone and then add the URL for the new Extranet zone.

New-SPWebApplicationAppDomain -AppDomain test-apps.local -WebApplication http://2013.test.local

New-SPWebApplicationAppDomain -AppDomain test-apps.net -WebApplication http://2013.test.local -Zone Extranet -SecureSocketsLayer -Port 82

If we now do a Get-SPWebApplicationappDomain we’d get both URLs:

Why did I choose to use SSL and port 82 on the new URL?

1. I chose to use SSL because I want every communication in the apps to be secure, no OAuth token flying around unencrypted, but mainly, because I want the URL of the App web to use HTTPS so that it matches my web application URL that it’s also using HTTPS.
2. Then, I chose to use port 82 because I’m using SSL. If we don’t specify the port, then it’ll use the same port that the extended web application uses. In my case it would be 81. However, I’m doing SSL offloading so my IIS binding in the Extranet zone is actually HTTP/81. Since I don’t want SSL termination for my Apps, I need a HTTPS binding and for this I need another port to bind to.

This also means that if you use a different port that the zone’s, this cmdlet will actually add the binding to the IIS site. And if you are using SSL, then you’ll need to configure the encryption certificate manually in the IIS bindings. Of course, the certificate should be a wildcard certificate for *.test-apps.net (or whatever new domain you are using for this zone)

After running the cmdlet, these are the bindings in my web server:

 2. Enabling the feature

This step is as simple as running these PowerShell cmdlets:

$contentService = [Microsoft.SharePoint.Administration.SPWebService]::ContentService

$contentService.SupportMultipleAppDomains = $true

$contentService.Update()

 After adding the mappings and enabling the feature, you need to do an IISReset in all your web servers.

Aftermath

After this configuration, now I can access my web application via my reverse proxy and when I open my App, the URL it now uses is the expected one and Javascript CSOM works flawlessly!

Some limitations worth mentioning

• The zone you are adding an app domain to must exist and the web application must be extended to it.
• You can share app domains between web applications, but the web applications must use the same application pool identity, zone and authentication provider.
• If you use SSL in the app domain, then you must use a different port from the web application SSL port. Mainly because you need to have two different certificates, however, you might be able to use separate IPs for different certificates although I haven’t tested this.