Claims-Based Single Sign-On for Microsoft SharePoint 2010

The Premise | Goals and Requirements | Overview of the Solution - Authentication Mechanism, End-to-End Walkthroughs, Visiting Two Site Collections in a SharePoint Web Application, Visiting Two SharePoint Web Applications, Authorization in SharePoint, The People Picker, Single Sign-Out | Inside the Implementation - Relying Party Configuration in ADFS, SharePoint STS Configuration, Create a New SharePoint Trusted Root Authority, Create the Claims Mappings in SharePoint, Create a New SharePoint Trusted Identity Token Issuer, SharePoint Web Application Configuration, People Picker Customizations, Single Sign-Out Control, Displaying Claims in a Web Part, User Profile Synchronization | Setup and Physical Deployment - FedAuth Tokens, ADFS Default Authentication Method, Server Deployment | Questions | More Information

This chapter walks you through an example of integrating two Microsoft® SharePoint® services web applications into a single-sign on (SSO) environment for intranet and extranet web users who all belong to a single security realm. These users can already access other ASP.NET web applications in the SSO environment. You'll see examples of SharePoint applications that Adatum has made claims-aware so that Adatum employees can access the SharePoint applications from the company intranet or from the web.

This basic scenario doesn't show how to establish a trust relationship between enterprises that would allow users from another company to access the SharePoint site; that is discussed in Chapter 12, "Federated Identity for SharePoint Applications." Instead, this chapter focuses on how to implement single sign-on and single sign-off within a security domain as a preparation for sharing resources with other security domains, and how to configure SharePoint to use claims-based authentication and authorization. In short, this scenario contains the commonly used elements that will appear in all claims-aware SharePoint applications. For further information about integrating ASP.NET web applications into an SSO environment and making them claims-aware, you should read Chapter 3, "Claims-Based Single Sign-On for the Web."

Bharath Says:
	Most of what you'll see described in this chapter about SharePoint and claims could be achieved without needing to claims-enable SharePoint. However, the claims-based infrastructure that this chapter introduces forms the basis of more advanced scenarios, such as the federated scenario described in the next chapter, which can only be implemented using claims.

For additional information about SharePoint and claims-based identity, see Appendix F, "SharePoint 2010 Authentication Architecture and Considerations."

The Premise

Adatum is a medium sized company that uses Microsoft Active Directory® to authenticate the employees in its corporate network. Adatum is planning to implement two applications as SharePoint 2010 web applications that employees will access from both the intranet and the Internet:

1. One application is a portal, named a-Portal, where Adatum stores the product documentation that's used by its sales force when they engage with customers. This SharePoint web application consists of a single site collection based on the "Team Site" template.
2. The other is a web application, named a-Techs, where field staff access scheduling information, tasks, and technical data. It also includes a blog where field technicians can capture tips and techniques to share with other team members (and possibly partners in the future). This SharePoint web application consists of two site collections; one based on the "Team Site" template, and one based on the "Blog" template. This web application also uses SharePoint user profile data.

Adatum has already established an SSO environment that includes existing ASP.NET web applications such as the a-Order and a-Expense applications. As part of this environment, Adatum has configured Active Directory Federation Services (ADFS) to act as an identity provider (IdP).

Goals and Requirements

The goals of this scenario are to show how to configure a SharePoint environment to use a claims-based identity model to control access, and how to customize SharePoint to provide a way for a SharePoint farm administrator to effectively manage access to the claims-enabled SharePoint applications.

Configuring a SharePoint environment to use claims includes configuring the trust relationship between SharePoint and ADFS and configuring which claims ADFS passes to SharePoint.

Users must be able to access the SharePoint web applications from both the intranet and Internet as part of an SSO realm that includes other ASP.NET web applications. The environment should also support single sign-out, so that logging out from any ASP.NET or SharePoint web application logs the user out from all applications that are part of the SSO domain.

SharePoint site collection administrators should be able to control access to site collections and sites based on role memberships defined in AD. For example, only users in the Sales role should have access to the a-Portal web application and only users in the Team Leader role should be able to post to the blog in the a-Techs application.

Overview of the Solution

Adatum has created two claims-enabled SharePoint web applications: one for salespersons and one for field technical employees. These applications are available on the intranet and Internet. The following diagram shows the main components of the solution suggested by Adatum.

Figure 1

Claims-enabled SharePoint applications at Adatum

In SharePoint, you configure an STS by creating a SharePoint trusted identity token issuer.

Authentication Mechanism

Adatum has configured both SharePoint web applications to use ADFS as a Trusted Identity Provider. Adatum has also configured ADFS to use different authentication types depending on where the user is accessing the applications from: intranet users will sign-in automatically using Integrated Windows Authentication, and Internet users will enter their Adatum Windows credentials into a web form. In this way, all users authenticate with Active Directory through ADFS.

Markus Says:
	During development, it's useful to be able to see the set of claims that a user has. See the section "Displaying Claims in a Web Part" for one way to do this.

An alternative approach that Adatum considered was to configure two authentication types in each web application in SharePoint. SharePoint 2010 allows you to configure multiple authentication mechanisms for a single web application; for example, you could configure a SharePoint web application to use both Windows Authentication and a trusted identity provider. Figure 2 shows the two alternative routes by which user attributes from Active Directory become claims belonging to a SharePoint user in this alternative scenario. The SharePoint security token service (STS) is an instance of a SharePoint trusted identity token issuer; the custom claims providers are optional components.

Figure 2

Building a user's claims collection

Jana Says:
	You can use the claims augmentation offered by the custom claims providers to programmatically add additional claims to a user's claims set.

The difficulty with this approach is that although both authentication mechanisms result in a set of claims for the IClaimsPrincipalInstance associated with the user, without additional code they are unlikely to generate the same types of claims. For example, the claims from Windows authentication will include groupsid claims, while the claims from the trusted identity provider will include role claims. An additional complexity of this approach is that you'll probably want to customize the page that SharePoint displays, offering users a choice of authentication provider.

Note

For an example of how a custom claims provider converts SIDs to group names, see this blog post: https://blogs.technet.com/b/speschka/archive/2010/09/12/a-sharepoint-2010-claims-provider-to-convert-role-sids-to-group-names.aspx.
For an example of how to customize the default SharePoint page that presents a choice of authentication providers to the user, see this blog post: https://blogs.msdn.com/b/brporter/archive/2010/05/10/temp.aspx.

For these reasons, Adatum selected the first approach that uses a single trusted identity provider in SharePoint so that they can use the claims-mapping rules in ADFS and ensure that a consistent set of claims reach SharePoint.

End-to-End Walkthroughs

The following sections outline two scenarios for a user who accesses a claims-enabled SharePoint environment: the first scenario describes what happens when a user accesses two different site collections in the same SharePoint web application, the second scenario describes what happens when a user accesses two SharePoint web applications hosted in the same domain.

The walkthroughs below describe the experience of Internet users who must provide their username and password to ADFS in order to authenticate. ADFS will not prompt intranet users (inside the corporate firewall) for their credentials, but will authenticate them using Integrated Windows Authentication: intranet users will not see the sign-in page for ADFS.

Visiting Two Site Collections in a SharePoint Web Application

In this walkthrough, John visits the Document Library and then the Team Site in the a-Techs SharePoint web application.

1. John browses to the Team site in the a-Techs SharePoint web application.
2. John has not yet been authenticated so SharePoint redirects his browser to ADFS. There are several intermediate steps—the SharePoint authentication endpoint and the SharePoint sign-in endpoint—before it arrives at ADFS.
3. John enters his Adatum domain credentials; ADFS validates the credentials, creates a token that contains John's claims, and redirects the browser to the SharePoint STS (the "/_trust/" endpoint in the SharePoint web application references the trusted identity token issuer).
4. The SharePoint STS validates the token from ADFS and issues a FedAuth cookie for the a-Techs SharePoint web application. This cookie contains a reference to the token that contains John's claims; the token itself is stored in the SharePoint token cache.
5. SharePoint checks that John has adequate permissions to access to the Team site collection, and redirects his browser to the site (the "/_layouts/Authenticate.aspx" endpoint in the SharePoint web application performs the permissions check).
6. John browses to the Blog site in the a-Techs SharePoint web Application. He does not require a new token for this site collection because it is part of the same SharePoint web application.

Note

In Chapter 12, "Federated Identity for SharePoint Applications," you can see a sequence diagram that illustrates this process in relation to sliding sessions.

Visiting Two SharePoint Web Applications

In this walkthrough, John visits the a-Portal SharePoint web application and then visits the a-Techs SharePoint web application.

1. John visits the a-Portal SharePoint web application.
   1. John browses to the Team site in the a-Portal SharePoint web application.
   2. John has not yet been authenticated, so SharePoint redirects his browser to ADFS.
   3. John enters his Adatum domain credentials; ADFS validates the credentials, issues a SAML token that contains his claims, and redirects the browser to the SharePoint STS (the "/_trust/" endpoint in the SharePoint web application). ADFS also creates an SSO cookie so that it can recognize if it has already authenticated John.
   4. The SharePoint STS validates the token from ADFS and issues a FedAuth cookie for the a-Portal SharePoint web application that contains a reference to John's claims in the SharePoint token cache.
   5. SharePoint checks that John has access to the Team site collection, and redirects his browser to the site.
2. John visits the a-Techs SharePoint web application.
   1. John browses to the Team site in the a-Techs SharePoint web application.
   2. John has not yet been authenticated for this SharePoint web application so SharePoint redirects his browser to ADFS.
   3. ADFS detects the SSO cookie that it issued in step 1-c, and redirects the browser with a new SAML token to the SharePoint STS.
   4. The SharePoint STS validates the token from ADFS and issues a FedAuth cookie for the a-Techs SharePoint web application that contains a reference to John's claims in the SharePoint token cache.
   5. SharePoint checks that John has sufficient permissions to access to the Team site collection, and redirects his browser to the site.

Note

In this example, it's important to ensure that each SharePoint web application uses its own FedAuth token. If the web applications have different host names, this will happen automatically. However, if in a test environment the web applications share the same host name, the second web application will try to use the existing FedAuth token, which will not be valid for that web application. Each web application must have its own FedAuth token. See the section, "Setup and Physical Deployment," in this chapter for more details.

Authorization in SharePoint

This scenario uses standard SharePoint groups to control access to the sites in the two SharePoint web applications. The following table summarizes the permissions.

Site	SharePoint Group	Permission level	Role Claim
a-Portal Team site	SalesSite Members	Contribute	sales
a-Techs Team site	TechSite Members	Contribute	techleaders
a-Techs Team site	TechSite Members	Contribute	techs
a-Techs Blog site	TechBlog Members	Contribute	techleaders
a-Techs Blog site	TechBlog Visitors	Read	techs

In SharePoint, a site administrator can add users to a SharePoint group to grant those users the permissions associated with the group. In a claims-based environment, a site administrator can add users to a SharePoint group based on the users' claims; for example, a site administrator could add all authenticated users in the sales role to the SharePoint Site Members group by using the Site Permissions Tools.

Note

Mapping claims to SharePoint groups simplifies the administration tasks in SharePoint. There is no need to add individual users to SharePoint groups.

Adatum has modified the SharePoint People Picker to make it easier for site administrators to map role and organization claims to SharePoint groups.

If your identity provider does not provide the claims that you need to implement your authorization rules, you can use claims augmentation in the SharePoint STS to modify existing claim values or to add additional claims to an authenticated user.

The People Picker

It is difficult for site administrators at Adatum to use the default people picker to reliably assign permissions in the a-Portal and a-Techs web applications. The default behavior of the people picker is to allow the user to enter part of a user name or group name and then use the search function to locate the user or group. In a claims-enabled SharePoint web application this does not work as expected because there is no repository of users and groups for the people picker to search; the only information SharePoint has is the claims data associated with the current user. The default people picker implementation works around this by always finding a match and resolving the name even if the name is incorrect, which makes it easy for an administrator to make a mistake. For example, let's say the site administrator would like to assign a permission to anyone in the techs role. If he makes a typing mistake and searches for techz in the people picker he will get a match and be able to assign a permission to a non-existent role.

Bharath Says:

In a claims-enabled application, the application receives a set of claims from a trusted issuer about the person accessing the application. This contrasts with the approach whereby the application queries a directory service to discover information about the user. The claims-based approach is much more flexible: the claims can come from many different issuers and be used in a federated identity environment. However, in a claims-based scenario the application may not have direct access to lists of users in a directory.

To prevent this type of error, Adatum implemented a custom SPClaimsManager component that can search for role and organization values in a pre-defined list of valid values. Figure 3 shows the overall architecture of the solution that Adatum adopted. There is a central store of valid role and organization names that both ADFS and the SharePoint people picker use: this way Adatum can configure ADFS to issue role and organization claims that the SharePoint people picker will recognize.

Figure 3

Architecture of the Adatum people picker solution

SharePoint and ADFS both run inside the Adatum corporate network. If SharePoint is running in a separate network from ADFS and the store, then a slightly more complex solution is needed. This might arise if SharePoint is running in the cloud, or if SharePoint needs to resolve values used by a partner's directory services. In this case, the architecture might include a lookup service as shown in Figure 4; in SharePoint you can use Business Connectivity Services to make the call to the lookup service, which introduces a useful layer of indirection into the architecture.

Figure 4

People picker solution architecture including a query claims lookup service

Adatum plans to use role and organization claims to assign permissions in SharePoint, and wants to avoid assigning permissions to individual users. However, some organizations may prefer to use names or email addresses to assign permissions in some circumstances. It is still possible to do this in a claims-enabled SharePoint site, but with the standard people picker component, site administrators will face the same problem whereby the people picker resolves both valid and invalid names. To work around this problem you can again create a custom people picker component that resolves name and emailaddress claim values against your directory service.

Poe Says:
	In the long run, it's more maintainable to manage permissions based on roles (and organizations) rather than on individuals in SharePoint. You can use Active Directory and ADFS to manage an individual's role and organization membership, while in SharePoint you can focus on mapping roles and organizations to SharePoint groups.

Single Sign-Out

For a SharePoint web application to participate in the single sign-out process, it must be able to handle the following scenarios. For more information about single sign-out and the WS-Federation protocol see Chapter 3, "Claims-Based Single Sign-On for the Web and Microsoft Azure."

1. The user should be able to initiate the single sign-out from within the SharePoint web application. Adatum modified the behavior of the standard sign-out process to send the WS-Federation wsignout message to the token issuer. In the Adatum scenario, this token issuer is ADFS.
2. SharePoint web applications should handle WS-Federation wsignoutcleanup messages from the issuer and invalidate any security tokens for the application. For this to work in SharePoint you must configure the SharePoint security token service to use session cookies rather than persistent cookies.

Note

If the user is signing in using Windows authentication in ADFS, then revisits the web application after having signed out, he or she will be signed in automatically and silently. Although the single sign-out has happened, the user won't be aware of it.

By default, SharePoint uses persistent cookies to store the session token, and this means that a user can close the browser and re-open it and get back to the SharePoint web application as long as the cookie has not expired. The consequence of changing to session cookies is that if a user closes the browser, she will always be required to authenticate again when she next visits the SharePoint web application. Adatum prefers this behavior because it provides better security.

Poe Says:
	The default name for the session cookie is FedAuth.

Inside the Implementation

The following sections describe the key configuration steps that Adatum performed in order to implement the scenario that this chapter describes.

Relying Party Configuration in ADFS

Each SharePoint web application is a separate relying party (RP) from the perspective of ADFS. Adatum has configured each of the relying parties to use the WS-Federation protocol and to issue the emailaddress and role claims for users that it authenticates, passing the values of these claims through from Active Directory. The following table shows the mapping rules that Adatum configured for each relying party in ADFS.

LDAP Attribute	Outgoing claim type
E-Mail-Addresses	E-Mail Address
Token-Groups – Unqualified Names	Role

It's important that the claims issued to SharePoint by ADFS (or any other claims issuer) are SAML 1.x compliant. For a description of the correct name format for claims that will be consumed by SharePoint, see this blog post: https://social.technet.microsoft.com/wiki/contents/articles/ad-fs-2-0-the-admin-event-log-shows-error-111-with-system-argumentexception-id4216.aspx.

ADFS must be able to identify which relying party a request comes from so that it can issue the correct set of rules. The sample scenario uses the identifiers shown in the following table:

Relying Party	Identifiers
a-Portal SharePoint web application	urn:adatum-portal:sharepoint
a-Techs SharePoint web application	urn:adatum-techs:sharepoint

Poe Says:
	SharePoint will send these identifier values in the wtrealm parameter. It's important to make sure that these identifiers match the configuration in SharePoint. These examples show the recommended format for these identifiers; however, there is no specific required format.

As part of the configuration in ADFS, you must specify the URL of the relying party WS-Federation protocol endpoint: this URL will be the "/_trust/" path in your SharePoint web application.

Note

You must enter the required information in ADFS manually (or create Windows® PowerShell® command-line interface scripts); SharePoint does not expose a FederationMetadata.xml document that you can use to automate the configuration.

SharePoint STS Configuration

You must configure the SharePoint STS to trust the ADFS issuer, and map the incoming claims from ADFS to claims that your SharePoint applications will use. The following sections describe the steps you must perform to complete this configuration.

Note

Remember to install the SharePoint PowerShell snap-in before attempting to run any SharePoint PowerShell scripts. You can do this with the following PowerShell command:
Add-PSSnapin Microsoft.Sharepoint.Powershell

Create a New SharePoint Trusted Root Authority

ADFS signs the tokens that it issues with a token signing certificate. You must import into SharePoint a certificate that it can use to validate the token from ADFS. You can use the following PowerShell commands to import a certificate from the adfs.cer file:

$cert = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2("C:\adfs.cer ")
New-SPTrustedRootAuthority 
-Name "Token Signing Cert" 
-Certificate $cert

You can export this certificate from ADFS using the certificates node in the ADFS 2.0 Management console.

Note

If the signing certificate from ADFS has one or more parent certificates in its certificate chain, you must add these to SharePoint as well. You can use the same SharePoint command to do this.
Notice that you must import any certificates that SharePoint uses into SharePoint; SharePoint does not use the trusted root authorities in the certificate store on the local machine.

Create the Claims Mappings in SharePoint

To map the incoming claims from ADFS to claims that SharePoint uses, you must create some mapping rules. The following PowerShell commands show how to create rules to pass through the incoming emailaddress and role claims.

$map = New-SPClaimTypeMapping 
-IncomingClaimType "https://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress" 
-IncomingClaimTypeDisplayName "EmailAddress" 
-SameAsIncoming

$map2 = New-SPClaimTypeMapping 
-IncomingClaimType "https://schemas.microsoft.com/ws/2008/06/identity/claims/role" -IncomingClaimTypeDisplayName "Role" 
–SameAsIncoming

You can choose to perform your claims mapping either as a part of the relying party definition in ADFS, or in the SharePoint STS. However, the rules-mapping language in ADFS is the more flexible of the two.

For an example of how to add additional claim types, see the "People Picker Customizations" section later in this chapter.

Create a New SharePoint Trusted Identity Token Issuer

A SharePoint trusted identity token issuer binds together the details of the identity provider and the mapping rules to associate them with a specific SharePoint web application. The following PowerShell commands show how to add the configuration settings for the scenario that this chapter describes. This script uses the $cert, $map, and $map2 variables from the previous script snippets.

$ap = New-SPTrustedIdentityTokenIssuer 
-Name "SAML Provider" 
-Description "Uses Adatum ADFS as an identity provider" 
-Realm "urn:adatum-portal:sharepoint" 
-ImportTrustCertificate $cert 
-ClaimsMappings $map,$map2 
-SignInUrl "https://DC-adatum/adfs/ls/" 
-IdentifierClaim https://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress

$uri = New-Object System.Uri("https://adatum-sp:31242/")

$ap.ProviderRealms.Add($uri, "urn:adatum-techs:sharepoint")
$ap.Update()

Markus Says:
	Don't forget to call the Update method to save the changes that the ProviderRealms.Add method makes.

The following table describes the key parameters in the PowerShell commands.

Parameter/command	Notes
-Realm	The realm is the value of the relying party identifier in ADFS. In this example, the realm parameter identifies the a-Portal SharePoint web application. The Add method of the ProviderRealms object adds the identifier for the a-Techs SharePoint web application. The URI is the address of the SharePoint web application.
-ImportTrustCertificate	This associates the token-signing certificate from ADFS with the token issuer.
-ClaimsMappings	This associates the claims-mapping rules with the token issuer.
-SignInUrl	This identifies the URL where the user can authenticate with ADFS.
-IdentifierClaim	This identifies which claim from the identity provider uniquely identifies the user.

Note

This example uses the email address as the identifier. You may want to consider alternative unique identifiers because of the possibility that email addresses can change.

Figure 5 summarizes how the SharePoint trusted identity token issuer uses the configuration data to issue a SAML token to the SharePoint web application.

Figure 5

The SharePoint trusted identity token issuer

When a SharePoint web application requests a token from a trusted identity provider, the SharePoint trusted token issuer first looks up the unique identifier of the web application. It passes this identifier to the external token issuer in the wtrealm parameter of the request. When the external token issuer returns a SAML token, the SharePoint trusted identity token issuer verifies the signature, applies any mapping rules, and places the new SAML token in the SharePoint token cache. It also creates a FedAuth cookie that contains a reference to the SAML token in the cache. Whenever the user access a page in the SharePoint web application, SharePoint first checks if a valid SAML token exists for the user, and then uses the claims in the token to perform any authorization checks.

There is a one-to-one mapping between SharePoint trusted identity token issuers and trust certificates from the external token issuer. You cannot configure a new SharePoint trusted identity token issuer using a token-signing certificate that an existing SharePoint trusted identity token issuer uses.

SharePoint Web Application Configuration

Each web application in SharePoint defines which authentication mechanisms it can use. In the scenario described in this chapter, Adatum has configured both SharePoint web applications to use a SAML-based trusted identity provider. Both intranet and internet users use the SAML-based trusted identity provider.

Poe Says:
	You can configure the authentication methods that SharePoint will use for a web application in the "SharePoint 2010 Central Administration" site. Just navigate to Manage Web Applications, select the application you want to change, and click on Authentication Providers.

People Picker Customizations

To customize the behavior of the standard people picker to enable site administrators to reliably select role and organization claims, Adatum created a custom claim provider to deploy to SharePoint. The Microsoft Visual Studio® development system solution, SampleClaimsProvider, in the 10SharePoint folder from https://claimsid.codeplex.com includes a custom claim provider that demonstrates how Adatum extended the behavior of the people picker. For reasons of simplicity, this sample does not use a store to maintain the list of role and organization claims that Adatum uses, the lists of valid claims are maintained in memory. In a production-quality claims provider you should read the permissible claims values from a store shared with the identity provider. For more information, see the section "The People Picker" earlier in this chapter.

Note

Use a custom SPClaimProvider class to override the default people picker behavior.

The SampleClaimsProvider class extends the abstract SPClaimProvider class and overrides the methods FillHierarchy, FillResolve, and FillSearch. The SPTrustedClaimsIssuer class, which derives from the SPClaimProvider class, implements the default UI behavior in the people picker.

The GetPickerEntry method is responsible for building an entry that will display in the people picker. The following code sample shows this method.

private PickerEntity GetPickerEntity(string ClaimValue, string claimType, string GroupName)
{
  PickerEntity pe = CreatePickerEntity();

  var issuer = SPOriginalIssuers.Format(
    SPOriginalIssuerType.TrustedProvider, TrustedProviderName);
  pe.Claim = new SPClaim(claimType, ClaimValue, 
    Microsoft.IdentityModel.Claims.ClaimValueTypes.String, issuer);
  pe.Description = claimType + "/" + ClaimValue;
  pe.DisplayText = ClaimValue;
  pe.EntityData[PeopleEditorEntityDataKeys.DisplayName] = ClaimValue;
  pe.EntityType = SPClaimEntityTypes.Trusted;
  pe.IsResolved = true;
  pe.EntityGroupName = GroupName;

  return pe;
}

This method uses the ClaimValue, claimType, and GroupName strings to create a claim that the people picker can display. The TrustedProviderName variable refers to the name of the SharePoint trusted identity token issuer that you are using: the SPOriginalIssuers.Format method returns a string with the full name of the original valid issuer that you must use when you create a new claim.

Note

Notice that a claim definition includes the claim issuer as well as the claim type and value. SharePoint will check the source of a claim as a part of any authorization rules.
If you are creating an identity claim, you must ensure that the claimType that you pass to the SPClaim constructor matches the identity claim type of your trusted identity token issuer, and that you set the EntityType property to SPClaimEntityTypes.User.

The people picker uses the value of the Description property to display a tooltip in the UI when a user hovers the mouse over a resolved claim.

If you deploy this solution to SharePoint, then the people picker will display search results from this custom claim provider in addition to results from the default, built-in claim provider. This means that if a site administrator searches for a non-existent role or organization claim, then the default claim provider will continue to resolve this non-existent claim value. To prevent this behavior, you can make your custom claim provider the default claim provider. If the name of the trusted identity token issuer is "SAML Provider" and the name of the custom claim provider is "ADFSClaimProvider," then the following PowerShell script will make the custom claim provider the default.

Adatum made the custom claim provider the default claim provider in the SharePoint web applications.

$ti = Get-SPTrustedIdentityTokenIssuer "SAML Provider"
$ti.ClaimProviderName = "ADFSClaimsProvider"
$ti.Update()

It's also important to ensure that the claim types that the site administrator will use in the custom people picker exist in the trusted identity token issuer. You can use the following PowerShell script to list the claims that are present in the configuration.

$i = Get-SPTrustedIdentityTokenIssuer "SAML Provider"
$i.ClaimTypes

You can add claim types to an existing trusted identity token issuer using the technique shown in the following PowerShell script.

$map = New-SPClaimTypeMapping -IncomingClaimType  
  "https://schemas.microsoft.com/ws/2008/06/identity/claims/organization" 
  -IncomingClaimTypeDisplayName "Organization" -LocalClaimType 
  "https://schemas.microsoft.com/ws/2008/06/identity/claims/organization"
$ti = Get-SPTrustedIdentityTokenIssuer "SAML Provider"
$ti.ClaimTypes.Add(
  "https://schemas.microsoft.com/ws/2008/06/identity/claims/organization")
Add-SPClaimTypeMapping -Identity $map -TrustedIdentityTokenIssuer $ti

This script maps an incoming claim and defines the new claim type in the trusted identity token issuer.

Single Sign-Out Control

To implement single sign-out behavior, you must be able to send the WS-Federation wsignout message to the token issuer when the user clicks either the "Sign out" or "Sign in with a different user" link on any page in the a-Portal or a-Techs SharePoint web applications. Adatum implemented the single sign-out logic in the SessionAuthenticationModule'sSignedIn and SigningOut events. The Visual Studio solution, SingleSignOutModule 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 shows the DoFederatedSignOut method that the SigningOut event handler invokes to perform the sign-out.

private void DoFederatedSignOut()
{
  string providerName = GetProviderNameFromCookie();
  SPTrustedLoginProvider loginProvider = null;
  SPSecurity.RunWithElevatedPrivileges(delegate()
  {
    loginProvider = GetLoginProvider(providerName);
  });

  if (loginProvider != null)
  {
    string returnUrl = string.Format(
      System.Globalization.CultureInfo.InvariantCulture,
      "{0}://{1}/_layouts/SignOut.aspx",
      HttpContext.Current.Request.Url.Scheme,
      HttpContext.Current.Request.Url.Host);
      HttpCookie signOutExpiredCookie =
        new HttpCookie(SignOutCookieName, string.Empty);
      signOutExpiredCookie.Expires = new DateTime(1970, 1, 1);
      HttpContext.Current.Response.Cookies.Remove(SignOutCookieName);
      HttpContext.Current.Response.Cookies.Add(signOutExpiredCookie);
      WSFederationAuthenticationModule.FederatedSignOut(
        loginProvider.ProviderUri, new Uri(returnUrl));
  }
}

Markus Says:
	This method reads the provider name from a custom sign-out cookie rather than from the IClaimsIdentity object associated with the current user: this is because if the user's session has expired, there will be no IClaimsIdentity object. Also, it's not safe to read the provider name from the FedAuth cookie.

This method performs the sign-out by calling the SharePoint SPFederationAuthenticationModule.FederatedSignOut method, passing the address of the claims provider and the address of the SharePoint web application's sign-out page as parameters. To discover the address of the claims provider, it uses an SPTrustedLoginProvider object: however, to get a reference to the SPTrustedLoginProvider object it needs its name, and it discovers the name by reading the custom sign-out cookie.

This method uses the SPSecurity.RunWithElevatedPrivileges method to invoke the GetLoginProvider method with "Full Control" permissions.

The following code sample shows how Adatum creates the custom sign-out cookie in the Session_SignedIn event.

private const string SignOutCookieName = "SPSignOut";
void WSFederationAuthenticationModule_SignedIn(object sender, EventArgs e)
{
 IClaimsIdentity identity = 
      HttpContext.Current.User.Identity as IClaimsIdentity;
        
  if (identity != null)
  {
    foreach (Claim claim in identity.Claims)
    {
      if (claim.ClaimType == SPClaimTypes.IdentityProvider)
      {
        int index = claim.Value.IndexOf(':');
        string loginProviderName = claim.Value.Substring(
                  index + 1, claim.Value.Length - index - 1);
        HttpCookie signOutCookie = new HttpCookie(SignOutCookieName,  
        Convert.ToBase64String(
                  System.Text.Encoding.UTF8.GetBytes(loginProviderName)));
        signOutCookie.Secure = FederatedAuthentication.SessionAuthenticationModule
                  .CookieHandler.RequireSsl;
        signOutCookie.HttpOnly = FederatedAuthentication
                  .SessionAuthenticationModule.CookieHandler.HideFromClientScript;
        signOutCookie.Domain = FederatedAuthentication
                  .SessionAuthenticationModule.CookieHandler.Domain;
        HttpContext.Current.Response.Cookies.Add(signOutCookie);
        break;
      }
    }
  }
}

Note

The custom sign-out cookie is not encrypted or signed. It is transported using SSL, and only contains the name of the user's login provider.

Jana Says:

One of the key reasons that Adatum selected this approach for handling single sign-out was its compatibility with the sliding-sessions implementation that Adatum chose to use. The sign-out process must be initiated when the user is inactive for more than the defined period of inactivity and when the user's SAML token ValidTo time is reached. For details about how Adatum implemented sliding sessions in the a-Portal web application see Chapter 12, "Federated Identity for SharePoint Applications."

You can find a complete listing of the global.asax file that Adatum use in the a-Portal web application at the end of this chapter.

Displaying Claims in a Web Part

When you're developing a claims-enabled SharePoint solution, it's useful to be able to view the set of claims that a user has when he visits a SharePoint web application. The Visual Studio solution called DisplayClaimsWebPart in the 10SharePoint folder from https://claimsid.codeplex.com includes a SharePoint Web Part that displays claims data for the current user. The Web Part displays the following claims data:

• The claim type.
• The claim issuer (this is typically SharePoint).
• The original claim issuer (this might be a trusted provider or the SharePoint STS).
• The claim value.

This is a standard Web Part that you can deploy to a SharePoint web application directly from Visual Studio or through the SharePoint UI. After the Web Part is deployed to SharePoint you can add it to any SharePoint web page. It does not require any further configuration.

User Profile Synchronization

A claims-enabled SharePoint environment can synchronize user profile data stored in the SharePoint profile store with profile data that is stored in directory services and other business systems in the enterprise. The important difference in the way that user profiles work in a claims-enabled web application such as the Adatum a-Techs SharePoint application is how SharePoint identifies the correct user profile from the claims data associated with an SPUser instance.

To make sure that SharePoint can match up a user profile from the current SPUser instance, you must ensure that three user properties are correctly configured.

Property name	Property value
Claim User Identifier	This is the unique identifier for a user. For Adatum, this is the value it used for the IdentifierClaim parameter when it configured the SharePoint trusted identity token issuer: https://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress.
Claim Provider Identifier	This identifies the trusted identity token issuer. For Adatum this value is "SAML Provider." This value is set automatically when you configure the user profile synchronization service.
Claim Provider Type	This specifies the token provider type. For Adatum this value is "Trusted Claims Provider Authentication." This value is set automatically when you configure the user profile synchronization service.

Poe Says:
	To test this, you must have SharePoint 2010 Server (not Foundation) installed in Farm (not Standalone) mode.

Setup and Physical Deployment

To run this scenario in a lab environment you may want to change some of the default configuration options in SharePoint and ADFS.

FedAuth Tokens

Each SharePoint web application must have its own FedAuth cookie if it is to function correctly in an single sign-on environment. In a production environment, this is not normally an issue because each SharePoint web application has a separate host name: for example, a-portal.adatum.com, and a-techs.adatum.com. However, in a lab environment you may not want to configure the necessary DNS infrastructure to support this; if your SharePoint web applications share the same host name, for example lab-sp.adatum.com:31242 and lab-sp.adatum.com:40197, then you must make a configuration change to make sure that each application uses a different name for the FedAuth cookie. You can change the name of the FedAuth cookie in the microsoft.IdentityModel section of the Web.config file. The following snippet shows how to change the token name to "techsFedAuth" from its default name of "FedAuth."

<federatedAuthentication>
  …
  <cookieHandler mode="Custom" path="/" name="techsFedAuth">
  …
</federatedAuthentication>

ADFS Default Authentication Method

By default, an Active Directory Federation Services (ADFS) server installation uses Integrated Windows Authentication, and an ADFS proxy installation uses an ASP.NET form to collect credentials. In a lab environment, if you do not have an ADFS proxy installation, you may want to change the default behavior of the ADFS server to use an ASP.NET form. To change this, edit the Web.config file in the /adfs/ls folder. The following snippet shows "Forms" at the top of the list, making it the default. This means that in a simple lab environment you will always need to sign in explicitly.

<microsoft.identityServer.web>
<localAuthenticationTypes>
  <add name="Forms" page="FormsSignIn.aspx" />
  <add name="Integrated" page="auth/integrated/" />
  <add name="TlsClient" page="auth/sslclient/" />
  <add name="Basic" page="auth/basic/" />
</localAuthenticationTypes>
…
</microsoft.identityServer.web>

Server Deployment

ADFS enables you to deploy proxy instances that are intended to handle authentication requests from the web rather than the internal corporate network which are handled by the main ADFS server instances. This provides an addition layer of security because the main ADFS server instances can be kept inside the corporate firewall. For more information about deploying ADFS servers and ADFS server proxies, see this section on the TechNet website: https://technet.microsoft.com/en-us/library/gg982491(WS.10).aspx. You will also need to ensure that your SharePoint web application is exposed to the internet to allow Adatum employees to access it remotely.

Questions

1. Which of the following roles can the embedded STS in SharePoint perform?
   1. Authenticating users.
   2. Issuing FedAuth tokens that contain the claims associated with a user.
   3. Requesting claims from an external STS such as ADFS.
   4. Requesting claims from Active Directory through Windows Authentication.
2. Custom claim providers use claims augmentation to perform which function?
   1. Enhancing claims by verifying them against an external provider.
   2. Enhancing claims by adding additional metadata to them.
   3. Adding claims data to the identity information in the SPUser object if the SharePoint web application is in "legacy" authentication mode.
   4. Adding additional claims to the set of claims from the identity provider.
3. Which of the following statements about the FedAuth cookie in SharePoint are correct?
   1. The FedAuth cookie contains the user's claim data.
   2. Each SharePoint web application has its own FedAuth cookie.
   3. Each site collection has its own FedAuth cookie.
   4. The FedAuth cookie is always a persistent cookie.
4. In the scenario described in this chapter, why did Adatum choose to customize the people picker?
   1. Adatum wanted the people picker to resolve role and organization claims.
   2. Adatum wanted the people picker to resolve name and emailaddress claims from ADFS.
   3. Adatum wanted to use claims augmentation.
   4. Adatum wanted to make it easier for site administrators to set permissions reliably.
5. In order to implement single sign-out behavior in SharePoint, which of the following changes did Adatum make?
   1. Adatum modified the standard signout.aspx page to send a wsignoutcleanup message to ADFS.
   2. Adatum uses the SessionAuthenticationModule SigningOut event to customize the standard sign-out process.
   3. Adatum added custom code to invalidate the FedAuth cookie.
   4. Adatum configured SharePoint to use a session-based FedAuth cookie.

More Information

For more information about SharePoint and claims-based identity, see Appendix F, "SharePoint 2010 Authentication Architecture and Considerations."

For a detailed, end-to-end walkthrough that describes how to configure SharePoint and ADFS, see this blog post: https://blogs.technet.com/b/speschka/archive/2010/07/30/configuring-sharepoint-2010-and-adfs-v2-end-to-end.aspx.

The following resources are useful if you are planning to create a custom people picker component for your SharePoint environment:

• People Picker overview (SharePoint Server 2010): https://technet.microsoft.com/en-us/library/gg602068.aspx
• Custom claims providers for People Picker (SharePoint Server 2010): https://technet.microsoft.com/en-us/library/gg602072.aspx
• Creating Custom Claims Providers in SharePoint 2010: https://msdn.microsoft.com/library/gg615945.aspx
• Claims Walkthrough: Writing Claims Providers for SharePoint 2010: https://msdn.microsoft.com/en-us/library/ff699494.aspx
• How to Override the Default Name Resolution and Claims Provider in SharePoint 2010: https://blogs.technet.com/b/speschka/archive/2010/04/28/how-to-override-the-default-name-resolution-and-claims-provider-in-sharepoint-2010.aspx

For further information about using profiles in a claims-enabled SharePoint environment, see this blog post: https://blogs.msdn.com/b/brporter/archive/2010/07/19/trusted-identity-providers-amp-user-profile-synchronization.aspx.

Next | Home