Federated Identity for SharePoint Applications

The Premise | Goals and Requirements | Overview of the Solution | Inside the Implementation - Token Expiration and Sliding Sessions, SAML Token Expiration in SharePoint, Sliding Sessions in SharePoint, Closing the Browser, Authorization Rules, Home Realm Discovery | Questions | More Information

In previous chapters, you saw ways that federated identity can help companies share resources with their partners. The scenarios have included small numbers of partners as well as large numbers of constantly changing partners, sharing web applications and web services, and supporting multiple client platforms. These scenarios share an important feature: they all use claims.

In Chapter 11, "Claims-Based Single Sign-On for Microsoft SharePoint 2010," you saw how Adatum could expand its single sign-on domain to include Microsoft® SharePoint® services web applications. The SharePoint web applications at Adatum used claims-based authentication, using claims from an external token issuer Microsoft Active Directory® Federation Services (ADFS).

In this chapter, you’ll learn how Adatum lets employees at one of its customers, Litware, use the a-Portal SharePoint application that was introduced in Chapter 11, "Claims-Based Single Sign-On for Microsoft SharePoint 2010."

Adatum wants to allow selected partners access to its SharePoint a-Portal web application.

The Premise

The a-Portal SharePoint application has given Adatum sales personnel access to up-to-date and accurate product information during the sales process, which has resulted in improved customer satisfaction. However, there have been complaints from customers who make purchases through of Adatum's partners that some of the product information has been out of date. This is because Adatum's partners are responsible for keeping the product information that they use up to date. One of these sales partners is Litware. Rick, the CIO of Litware, has seen the a-Portal SharePoint application and he is keen for his sales staff to use a-Portal instead of their own copy of the product information. Adatum has already claims-enabled the a-Portal SharePoint application (for further information see Chapter 11, "Claims-Based Single Sign-On for Microsoft SharePoint 2010") and made it available to Adatum employees who work remotely on the Internet. Litware has already deployed ADFS, so most of the required federation infrastructure is already available.

Goals and Requirements

The primary goal of this scenario is to show how to create a SharePoint site that uses federated identities, so that users from Litware can access the Adatum a-Portal SharePoint application without having to sign in again to the Adatum security realm. The types of claims issued by Litware are not the same types as the claims used by a-Portal at Adatum, so it's necessary to include some claims transformation logic to convert the claims issued by Litware. Adatum anticipates that other sales partners will also want to use the a-Portal application, so the solution must be able to accommodate multiple identity providers.

The solution should also ensure that partners are kept isolated. For example, there may be some product information that only Adatum and not Litware sales personnel should see.

For security, Adatum wants to have SharePoint automatically sign users out of the a-Portal application after a period of inactivity. In addition, because users will be accessing the a-Portal application on computers outside the Adatum corporate network, when a user closes the browser and then re-opens it, the user must re-authenticate to gain access to the a-Portal web application.

Overview of the Solution

Figure 1 shows an overview of the solution adopted by Adatum and Litware. It shows a new trust relationship between Adatum's issuer, and Litware's issuer. In addition to acting as an identity provider (IdP) for Adatum employees, the Adatum ADFS instance now functions as a federation provider (FP) for partners such as Litware.

Bharath Says:
	Adatum has deployed an ADFS proxy to support authenticating users outside of the Adatum corporate network.

Figure 1

Federating identity with Litware

When Rick, a user from Litware, browses to the a-Portal SharePoint web application, SharePoint detects that Rick is not authenticated, and redirects his browser to the Adatum federation provider. The Adatum federation provider then redirects Rick's browser to the Litware issuer.

Note

For details about how to customize the way that SharePoint redirects a user to a token issuer, see the section "The Sign-In Page" in Chapter 11, "Claims-Based Single Sign-On for Microsoft SharePoint 2010."

The numbers in the following list correspond to the numbers in Figure 1.

1. Rick authenticates with the Litware identity provider and obtains a SAML token with claims issued by Litware.
2. Rick's browser redirects back to the Adatum issuer. This federation provider can apply some custom claims mapping rules to the set of claims from Litware to create a set of claims suitable for the a-Portal web application. The federation provider issues this new set of claims as a SAML token.
3. Rick's browser redirects back to SharePoint. SharePoint validates the token, checks any authorization rules that apply to the page that Rick requested, and if Rick has permission, displays the page.

Adatum considered two alternative models for federating with partners. The first, which is the one that Adatum selected, is shown in Figure 2.

Figure 2

The hub model

In the hub model, SharePoint has a single trust relationship with the Adatum federation provider. The Adatum federation provider then trusts the partners' issuers. The Adatum federation provider can apply rules to the claims from the different identity providers to create claims that the SharePoint web application understands.

Figure 3 shows the alternative model.

Figure 3

The direct trust model

In the direct trust model, SharePoint manages a trust relationship with each issuer directly, and uses custom claims providers to manipulate the incoming claims to a common set of claims that the a-Portal web application understands.

The advantages of the hub model adopted by Adatum are that:

1. It's easier to manage multiple trust relationships in ADFS rather than SharePoint.
2. It's simpler to manage a single trust relationship in SharePoint and it avoids the requirement for multiple custom claims providers.
3. You can reuse the trust relationships in the federation provider with other relying parties.
4. You can leverage ADFS features such as integration with auditing tools to track token issuing.
5. ADFS supports the Security Assertion Markup Language protocol (SAMLP) in addition to WS-Federation.

Bharath Says:
	An advantage of the SAMLP protocol over WS-Federation is that it supports initializing the authentication process from the identity provider instead of the relying party, which avoids the requirement for either the relying party (RP) or the federation provider to perform home-realm discovery.

The disadvantage of the hub approach is its performance: it requires more hops to acquire a valid SAML token. With this in mind, Adatum made some changes to the token caching policy in the a-Portal web application to reduce the frequency at which it's necessary to refresh the SAML token. However, Adatum is using session cookies rather than persistent cookies to store the SAML token references so that if the user closes his browser, then he will be forced to re-authenticate when he next visits the a-Portal web application.

Markus Says:
	Strictly speaking, the session cookie doesn't contain the SAML token, it contains a reference to the SAML token in the SharePoint token cache.

Adatum implemented sliding sessions for users of the a-Portal web application: after a token issuer authenticates a user, the user can continue using the a-Portal web application without having to re-authenticate if he remains active. If a user becomes inactive in the web application for more than a defined period, then he must re-authenticate with the claims issuer and obtain a new SAML token. With the sliding-sessions solution in place:

• Provided a user remains active in the a-Portal web application, SharePoint will not interrupt the user and require him to re-authenticate with the SAML token issuer.
• The a-Portal web application remains secure because users who become inactive must re-authenticate when they start using the application again.

It's important that the sliding-session implementation is compatible with the single sign-out solution that Chapter 11, "Claims-Based Single Sign-On for Microsoft SharePoint 2010," describes.

Inside the Implementation

The following sections describe the key configuration steps that Adatum performed in order to implement the scenario that this chapter describes. The hub model that Adatum selected meant that the changes in SharePoint were minimal: there is still a single trust relationship with the Adatum issuer.

Poe Says:
	The main configuration changes were in ADFS: adding the trust relationship with Litware and adding the rules to convert Litware claims to Adatum claims.

The following sections describe the changes Adatum made to the a-Portal web application in SharePoint to support access from partner organizations.

Token Expiration and Sliding Sessions

One of the Adatum requirements was that the a-Portal application automatically sign users out after a defined period of inactivity, but allow them to continue working with the application without re-authenticating so long as they remain active. To achieve this, Adatum implemented a sliding-session mechanism in SharePoint that can renew the SharePoint session token. For performance reasons, Adatum wanted to be able to extend the lifetime of the session token without having to revisit ADFS (the federation provider) or the partner's token issuer.

Note

A cookie (usually named FedAuth) that can exist either as a persistent or in-memory cookie represents the SharePoint session token. This cookie contains a reference to the SAML token that SharePoint stores in its token cache. The SAML token contains the claims issued to the user by any external identity and federation providers, and by the internal SharePoint security token service (STS).

Before showing the details of how Adatum implemented sliding sessions, it will be useful to understand how token expiration works by default in SharePoint.

SAML Token Expiration in SharePoint

This section describes the standard behavior in SharePoint as it relates to token expiration.

When Rick from Litware first tries to access the a-Portal web application, his browser performs all of the following steps in order to obtain a valid SAML token:

1. Rick requests a page in the a-Portal web application.
2. Rick's browser redirects to the SharePoint STS.
3. Because Rick is not yet authenticated, the SharePoint STS redirects Rick's browser to the Adatum issuer to request a token.
4. The Adatum issuer redirects Rick's browser to the Litware issuer to authenticate and obtain a Litware token.
5. Rick's browser returns to the Adatum issuer to transform the Litware token into an Adatum token.
6. Rick's browser returns to the a-Portal web application to sign in to SharePoint.
7. Rick's browser returns to the page that Rick originally requested in the a-Portal web application to view.

All SAML tokens have a fixed lifetime that the token issuer specifies when it issues the token; in the Adatum scenario, it is the Adatum ADFS that sets this value. Once a token has expired, the user must request a new SAML token from the token issuer. For Rick at Litware, this means repeating the steps listed above. Because this takes time, Adatum does not want users such as Rick to have to reauthenticate too frequently. However, using a token with a long lifetime can be a security risk because someone else could use Rick's computer while he wasn't there and access the a-Portal web application with Rick's cached token.

Jana Says:
	When Rick's SAML token expires he may, or may not, need to re-enter his credentials at the token issuer (ADFS): this depends on the configuration of the issuer. In ADFS, you can specify the web single sign-on (SSO) lifetime that determines the lifetime of the ADFS SSO cookie.

The following table describes the two configuration options that directly affect when SharePoint requires a user to get a new SAML token from the issuer.

Configuration value	Notes
SAML token lifetime	The token issuer sets this value. In ADFS, you can configure this separately for each relying party by using the Set-ADFSRelyingPartyTrust PowerShell command. Once the SAML token expires, the SharePoint session expires, and the user must re-authenticate with the token issuer to obtain a new SAML token. By default, SharePoint sets the session lifetime to be the same as the SAML token lifetime.
LogonTokenCacheExpirationWindow	This SharePoint configuration value controls when SharePoint will consider that the SAML token has expired and ask the user to re-authenticate with the issuer and obtain a new token. SharePoint checks whether the SAML token has expired at the start of every request. For example, if ADFS sets the SAML token lifetime to ten minutes, and the LogonTokenCacheExpirationWindow property in SharePoint is set to two minutes, then the session in SharePoint will be valid for eight minutes. If the user requests a page from SharePoint seven minutes after signing in, then SharePoint checks whether the session is set to expire during the time in minutes represented by LogonTokenCacheExpirationWindow: in this case the answer is no because seven plus two is less than ten. If the user requests a page from SharePoint nine minutes after signing in, then SharePoint checks whether the session is set to expire during the time in minutes represented by LogonTokenCacheExpirationWindow: in this case the answer is yes because nine plus two is greater than ten.

Poe Says:
	Make sure that the value of the LogonTokenCacheExpirationWindow property is always less than the SAML token lifetime; otherwise, you'll see a loop whenever a user tries to access your SharePoint web application and keeps being redirected back to the token issuer.

The following script example shows you how to change the lifetime of the SAML token issued by the "SharePoint Adatum Portal" relying party in ADFS to 10 minutes.

Add-PSSnapin Microsoft.ADFS.PowerShell
Set-AdfsRelyingPartyTrust –TargetName "SharePoint Adatum Portal" –TokenLifeTime 10

The following script example shows you how to change the LogonTokenCacheExpirationWindow in SharePoint to two minutes.

$ap = Get-SPSecurityTokenServiceConfig
$ap.LogonTokenCacheExpirationWindow = (New-TimeSpan -minutes 2)
$ap.Update();
IIsreset

These two configuration settings will cause SharePoint to redirect the user to the issuer to sign in again eight minutes after the user last authenticated with ADFS.

The sequence diagram in Figure 4 shows how SharePoint manages its session lifetime and the SAML token that it receives from the token issuer.

Figure 4

Standard token expiration in SharePoint

Note

Figure 4 shows a simplified view of the sequence of interactions. In reality, SharePoint and the WS-Federation protocol use browser redirects and automatic posts to manage the interactions between the various components so that all of the requests go through the browser.

In the sequence diagram, TR represents the time from when ADFS issues the SAML token to when SharePoint will try to renew the token. Based on the configuration settings described above, TR is set to eight minutes.

The following notes refer to the numbers on the sequence diagram:

1. This is the first time that the user visits the a-Portal web application; there is no valid session so SharePoint redirects the user to begin the sign-in process.
2. SharePoint creates a session for the user. The lifetime of the session is the same as the lifetime of the SAML token issued by ADFS.
3. SharePoint uses the session lifetime and the LogonTokenCacheExpirationWindow property to determine when the user must sign in again. At this point, the session is still valid. While the session is valid, the user can continue to visit pages in the SharePoint web application.
4. SharePoint uses the session lifetime and the LogonTokenCacheExpirationWindow property to determine when the user must sign in again. At this point, SharePoint determines that the session has expired, so it begins the sign-in process again. If the ADFS SSO cookie has expired, Rick will have to enter his credentials to obtain a new SAML token.

Note

To force users to re-enter their credentials whenever they are redirected back to ADFS, you should set the web SSO lifetime in ADFS to be less than or equal to SAMLtokenlifetime minus the value of LogonTokenCacheExpirationWindow. In the Adatum scenario, the web SSO lifetime in ADFS should be set to eight minutes to force users to re-authenticate when SharePoint redirects them to ADFS.

Sliding Sessions in SharePoint

Adatum wanted to implement sliding sessions so that SharePoint can extend the lifetime of the session if the user remains active. Adatum wanted to be able to define an inactivity period, after which SharePoint forces the user to re-authenticate with ADFS. In other words, a user will only need to sign in again if the session is allowed to expire or if the SAML token expires. In this scenario, the session lifetime will be less than the SAML token lifetime.

To implement this behavior, Adatum first configured ADFS to issue SAML tokens with a lifetime of eight hours. The following Microsoft Windows® PowerShell® command-line interface script shows how you can configure this setting in ADFS for the SharePoint Adatum Portal relying party.

Add-PSSnapin Microsoft.ADFS.PowerShell
Set-AdfsRelyingPartyTrust –TargetName "SharePoint Adatum Portal" –TokenLifeTime 480

By setting the LogonTokenCacheExpirationWindow value to 470 minutes, Adatum can effectively set the session duration to 10 minutes.

$ap = Get-SPSecurityTokenServiceConfig
$ap.LogonTokenCacheExpirationWindow = (New-TimeSpan -minutes 470)
$ap.Update();
IIsreset

Adatum then modified the way that SharePoint manages its sessions. SharePoint now recreates a new session before the existing session expires (as long as the user visits the SharePoint web application before the existing session expires). A user can continue to recreate sessions up to the time that the SAML token finally expires; in this scenario, the user could continue using the a-Portal web application for eight hours without having to re-authenticate. If the user doesn't visit the web application before the session expires, then on the next visit he must sign in again. The Microsoft Visual Studio® development system solution, SlidingSessionModule, found in the 10SharePoint folder from https://claimsid.codeplex.com includes a custom HTTP module to deploy to your SharePoint web application that includes this functionality. The following code sample from the Adatum custom HTTP module shows the implementation.

Markus Says:
	Remember: A reference to the SAML token in the SharePoint token cache is stored in the session. The session is represented by the FedAuth cookie.

public void Init(HttpApplication context)
{
  // Sliding session
  FederatedAuthentication.SessionAuthenticationModule.SessionSecurityTokenReceived += 
    SessionAuthenticationModule_SessionSecurityTokenReceived;

  …
} 

private void SessionAuthenticationModule_SessionSecurityTokenReceived(
  object sender, SessionSecurityTokenReceivedEventArgs e)
{
  double sessionLifetimeInMinutes =
                (e.SessionToken.ValidTo - e.SessionToken.ValidFrom).TotalMinutes;
  var logonTokenCacheExpirationWindow = TimeSpan.FromSeconds(1);
  SPSecurity.RunWithElevatedPrivileges(delegate()
  {
    logonTokenCacheExpirationWindow =
      Microsoft.SharePoint.Administration.Claims.SPSecurityTokenServiceManager
      .Local.LogonTokenCacheExpirationWindow;
  });

  DateTime now = DateTime.UtcNow;
  DateTime validTo = e.SessionToken.ValidTo - logonTokenCacheExpirationWindow;
  DateTime validFrom = e.SessionToken.ValidFrom;

  if ((now < validTo) && 
      (now > validFrom.AddMinutes((validTo - validFrom).TotalMinutes / 2)))
  {
    SessionAuthenticationModule sam = 
      FederatedAuthentication.SessionAuthenticationModule;
    e.SessionToken = sam.CreateSessionSecurityToken(e.SessionToken.ClaimsPrincipal, 
      e.SessionToken.Context, now, now.AddMinutes(sessionLifetimeInMinutes), 
      e.SessionToken.IsPersistent);

    e.ReissueCookie = true;
  }
}

This method first determines the valid from time and valid to time of the existing session, taking into account the value of the LogonTokenCacheExpirationWindow property. Then, if the existing session is more than halfway through its lifetime, the method uses the SPSessionAuthenticationModule instance to extend the session. It does this by creating a new session that has the same lifetime as the original, but which has a ValidFrom property set to the current time.

The sequence diagram in Figure 5 shows how SharePoint handles Adatum's sliding-sessions implementation.

Figure 5

Sliding sessions in the a-Portal web application

Note

The sequence diagram shows a simplified view of the sequence of interactions. In reality, SharePoint and the WS-Federation protocol use browser redirects and automatic posts to manage the interactions between the various components so all of the requests go through the browser.

In the sequence diagram, TF represents the session lifetime. The session lifetime also defines the inactivity period, after which a user must re-authenticate with ADFS.

The following notes refer to the numbers on the sequence diagram:

1. This is the first time that the user visits the a-Portal web application; there is no valid session so SharePoint redirects the user to begin the sign-in process.
2. SharePoint creates a session for the user. The effective lifetime of the session is the difference between the lifetime of the SAML token issued by ADFS and the value of the LogonTokenCacheExpirationWindow property. For Adatum, the lifetime of the session is 10 minutes: the lifetime of the SAML token is 480 minutes, and the value of the LogonTokenCacheExpirationWindow property is 470 minutes.
3. SharePoint checks the age of the session. At this point, although the session is still valid, it is nearing the end of its lifetime so SharePoint creates a new session, copying data from the existing session.
4. SharePoint checks the age of the session. At this point, it is still near the beginning of its lifetime so SharePoint continues to use this session.
5. SharePoint checks the age of the session. At this point, the session has expired so SharePoint initiates the process of re-authenticating with the identity provider.

Closing the Browser

The default behavior for SharePoint is to use persistent session cookies. This enables a user to close the browser, re-open the browser, and re-visit a SharePoint web application without signing in again. Adatum wants users to always re-authenticate if they close the browser and then re-open it and revisit the a-Portal web application. To enforce this behavior, Adatum configured SharePoint to use an in-memory instead of a persistent session cookie. You can use the following PowerShell script to do this.

$sts = Get-SPSecurityTokenServiceConfig 
$sts.UseSessionCookies = $true 
$sts.Update() 
iisreset

Authorization Rules

With multiple partners having access to the a-Portal SharePoint web application, Adatum wants to have the ability to restrict access to documents in the SharePoint document library based on the organization that the user belongs to. Adatum wants to be able to use the standard SharePoint groups mechanism for assigning and managing permissions, so it needs some way to identify the organization a user belongs to.

Adatum achieves this objective by using claims. Adatum has configured ADFS to add an organization claim to the SAML token it issues based on the federated identity provider that originally authenticated the user. You should not rely on the identity provider to issue the organization claim because a malicious administrator at a partner organization could add an organization claim with another partner's value and gain access to confidential data.

Chapter 11, "Claims-Based Single Sign-On for Microsoft SharePoint 2010," describes how to add the organization claim to the SharePoint people picker to make it easy for site administrators to set permissions based on the value of the organization claim.

Home Realm Discovery

If Adatum shares the a-Portal web application with multiple partners, each of those partners will have its own identity provider, as shown in Figure 2 earlier in this chapter. With multiple identity providers in place, there must be some mechanism for selecting the correct identity provider for a user to use for authentication, and that's the home-realm discovery process.

Adatum decided to customize the home-realm discovery page that ADFS provides. The default page in ADFS (/adfs/ls/HomeRealmDiscovery.aspx) displays a drop-down list of the claims provider trusts configured in ADFS (claims provider trusts represent identity providers in ADFS) for the user to select an identity provider. ADFS then redirects the user to the sign-in page at the identity provider. It's easy to customize this page with partner logos to make it easier for users to select the correct identity provider. In addition, this page in ADFS has access to the relying party identifier in the wtrealm parameter so it can customize the list of identity providers based on the identity of the SharePoint relying party web application. After a user has selected an identity provider for the first time, ADFS can remember the choice so that in the future, the user bypasses the home-realm discovery page and redirects the browser directly to the identity provider's sign-in page.

Claims provider trusts represent identity providers in ADFS.

Note

For details about how to customize the ADFS home-realm discovery page and configure how long ADFS will remember a user's selection, see this page on the MSDN® web site: https://msdn.microsoft.com/en-us/library/bb625464(VS.85).aspx.

Adatum also considered the following options related to the home-realm discovery page.

• Automatically determine a user's home realm based on the user's IP address. This would remove the requirement for the user to specify her home realm when she first visits ADFS; however, this approach is not very reliable, especially with mobile and home workers and does not provide any additional security because IP addresses can be spoofed.
• Perform the home-realm discovery in SharePoint instead of ADFS. Adatum could customize the standard SharePoint login page (usually located at C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\14\template\identitymodel\login\default.aspx) to display the list of identity providers, and then append a whr parameter identifying the user's home realm to the address of the ADFS sign-in page. However, the SharePoint login page only displays to the user if multiple authentication types are configured in SharePoint; Adatum only has a single authentication type configured for the a-Portal web application so Adatum would need to override the behavior of the standard login page so that it always displays. By default, all SharePoint web applications share this login page, so SharePoint would display the same list of identity providers regardless of the SharePoint web application the user is accessing. You can override this behavior and display a separate login page for each SharePoint web application.

Poe Says:
	You should be sure to keep your SharePoint environment up to date with the latest patches from Microsoft.

Questions

1. In the scenario described in this chapter, Adatum prefers to maintain a single trust relationship between SharePoint and ADFS, and to maintain the trust relationships with the multiple partners in ADFS. Which of the following are valid reasons for adopting this model?
   1. It enables Adatum to collect audit data relating to external sign-ins from ADFS.
   2. It allows for the potential reuse of the trust relationships with partners in other Adatum applications.
   3. It allows Adatum to implement automatic home realm discovery.
   4. It makes it easier for Adatum to ensure that SharePoint receives a consistent set of claim types.
2. When must a SharePoint user reauthenticate with the claims issuer (ADFS in the Adatum scenario)?
   1. Whenever the user closes and then reopens the browser.
   2. Whenever the ADFS web SSO cookie expires.
   3. Whenever the SharePoint FedAuth cookie that contains the SAML token expires.
   4. Every ten minutes.
3. Which of the following statements are true with regard to the Adatum sliding session implementation?
   1. SharePoint tries to renew the session cookie before it expires.
   2. SharePoint waits for the session cookie to expire and then creates a new one.
   3. When SharePoint renews the session cookie, it always requests a new SAML token from ADFS.
   4. SharePoint relies on sliding sessions in ADFS.
4. Where is the organization claim that SharePoint uses to authorize access to certain documents in the a-Portal web application generated?
   1. In the SharePoint STS.
   2. In the identity provider's STS; for example in the Litware issuer.
   3. In ADFS.
   4. Any of the above.
5. Why does Adatum rely on ADFS to perform home realm discovery?
   1. It's easier to implement in ADFS than in SharePoint.
   2. You can customize the list of identity providers for each SharePoint web application in ADFS.
   3. You cannot perform home realm discovery in SharePoint.
   4. You can configure ADFS to remember a user's choice of identity provider.

More Information

For information about Windows Identity Foundation (WIF) and sliding sessions see this post: https://blogs.msdn.com/b/vbertocci/archive/2010/06/16/warning-sliding-sessions-are-closer-than-they-appear.aspx.

For more information about automated home-realm discovery, see Chapter 6, "Federated Identity with Multiple Partners," and Chapter 7, "Federated Identity with Multiple Partners and Microsoft Azure Access Control Service."

Next | Home