Claims Architecture and Scenarios for SharePoint 2010 Developers
Summary: Learn how claims-based authentication in Microsoft SharePoint 2010 enables you to support advanced scenarios that require custom development.
Applies to: Business Connectivity Services | Open XML | SharePoint Designer 2010 | SharePoint Foundation 2010 | SharePoint Online | SharePoint Server 2010 | Visual Studio
Provided by: Javier Dalzell, Schakra Inc
Contents
Overview of Advanced Claims-Based Authentication Scenarios
Creating Custom Login Pages Used by the Forms-Based Authentication Feature
Customizing Authentication Selection Pages to Provide Additional Information
Adding Context-Based Claims to the User's Claims Token
Authenticating from a Client Application by Following the Pattern of Passive Authentication
Migrating ISAPI-Based Authentication Schemes to SharePoint 2010
Supporting Claims Tokens Issued by SharePoint 2010 in Claims-Aware Web Services
Enabling High-Security Authentication (2FA) in SharePoint 2010
Conclusion
About the Author
Additional Resources
Overview of Advanced Claims-Based Authentication Scenarios
An important aspect of claims-based authentication in Microsoft SharePoint 2010 is that solution developers can use its power programmatically to enable more advanced authentication scenarios.
This article walks you through different scenarios that involve the following tasks:
Creating custom login pages
Customizing the authentication selection page
Adding context-based claims to the user's claims token
Authenticating from a client application
Migrating authentication schemes to SharePoint 2010 that are based on Internet Server API (ISAPI)
Supporting the claims token that is issued by SharePoint 2010 in claims-aware web services
Enabling high-security authentication, including two-factor authentication (2FA), in SharePoint 2010
This article assumes that you are familiar with claims-based authentication in SharePoint 2010.
To learn more about claims-based authentication, see Claims Tips 1: Learning About Claims-Based Authentication in SharePoint 2010.
Although this article does not provide a walkthrough or code samples, it can help you understand the concepts behind each of the tasks in the previous list. For walkthroughs with sample code, see Claims and Security Technical Articles for SharePoint 2010.
Understanding Authentication Flows in SharePoint 2010
When you configure a SharePoint 2010 web application in claims mode, different authentication options are available. These options determine the flow of the authentication process. To learn more about authentication options, see Authorization and Authentication.
Figure 1 shows the steps in the authentication process. It explains, in order, the different routes that the authentication process flow can have, based on the authentication options that are available in SharePoint 2010.
Figure 1. High-level architecture of the claims-based authentication process
Steps in the Authentication Process
The client requests a SharePoint resource.
As part of the request pipeline, if the request is not authenticated, the authentication components route the request based on the authentication settings for that zone.
The request is then processed by the authentication components. When more than one authentication method is configured for the given zone, the authentication selection page enables the user to choose the authentication method. If only one authentication method is specified, the request is processed directly by the specified authentication method.
The user is authenticated by the identity provider.
If authentication succeeds, the SharePoint security token service (STS) generates a claims-based token for the user with the information provided by the identity provider. If additional claims providers are configured, the STS augments the user's token with the claims given by the claims provider. For more information about claims providers, see Claims Tips 2: Learning About Claims-Based Authentication in SharePoint 2010.
The claims-based token of the user is sent back to the authentication components.
The authentication components redirect the request back to the resource address, with the claims-based token issued for the user.
The rest of the request pipeline is executed and a response is sent back to the requestor (client). As part of the request pipeline, the authorization is completed.
As mentioned previously, the flow of the authentication process is defined by the options that you select during the configuration of the zone. The following figures show how these options define the flow of the authentication.
Figure 2. Authentication flow
Each of the authentication types follows a specific pipeline. Figures 3, 4, and 5 can help you understand how each authentication type works.
Windows Authentication Pipeline
When Windows authentication is the only authentication type enabled in a zone, users are silently authenticated by using NTLM or Negotiate (Kerberos protocol) during the request pipeline. After a user is authenticated, a claims-based token is requested from the SharePoint STS and a claims identity is created. After this point, SharePoint continues processing the request, including making the proper access checks.
Figure 3. Windows authentication flow
When the Windows authentication type is enabled along with one or more other authentication types, the user is redirected to the authentication selection page. If the user selects the option that uses Windows authentication, the user request is redirected to the Windows authentication page, which is silent (no other UI is displayed to the user to indicate that the user is being redirected, unless basic authentication is configured). On the Windows authentication page, when the user is authenticated, a claims-based token is requested and the user is sent back to the requested resource. Because the request contains a claims-based token that was issued by SharePoint STS, a claims identity is created and the request process continues.
Figure 4 shows the Windows authentication process flow and lists the authentication steps in order.
Figure 4. Windows authentication process
Understanding the Windows Authentication Process
The user requests a SharePoint 2010 resource.
User authentication (NTLM challenge/Kerberos negotiation) occurs.
The claims-based token request is sent to the SharePoint 2010 STS.
SharePoint STS gets the user's security groups from the Windows token and adds them as user claims in the token.
Note
The group SID is what is added in the claims token.
The SharePoint STS gets additional claims for the user (if an additional claims provider is registered for that web application/zone).
The claims-based token is issued.
The request is processed by the rest of the components in the pipeline.
The response is sent back to the user.
Forms-Based Authentication Pipeline
In the case of forms-based authentication, the user is redirected to the SharePoint forms-based login page. If additional authentication types are configured, the user is redirected to the authentication selection page first, and then to the login page if the user selects the option that is linked to the forms-based authentication type.
The SharePoint forms-based login page collects the credentials of the user, which are then sent to the SharePoint 2010 STS. The STS calls the membership provider that is associated with that web application, to validate the user's credentials. If this succeeds, the STS retrieves the roles that the user belongs to and adds these as claims in the claims-based token that is sent back to the login page.
From the login page, after the claims-based token is issued, the user is sent back to the request resource and the process continues in the same way as in Windows authentication.
Figure 5. Forms-based authentication process
Understanding the Forms-Based Authentication Process
The user requests a SharePoint 2010 resource.
SharePoint redirects the user to the forms-based authentication login page.
The username and password are collected from the user and sent to the SharePoint 2010 STS.
STS validates the user's credentials with the membership provider and, if validation succeeds, STS requests all the roles that the user belongs to and adds those claims to the user's token.
The SharePoint STS gets additional claims for the user (if an additional claims provider is registered for that web application/zone).
The claims-based token is issued to the user.
The request is processed by the rest of the components in the pipeline.
The response is sent back to the user.
SAML Token-Based Authentication Pipeline
Out-of-the box, with the default implementation of Active Directory Federation Services (AD FS), when SAML token-based authentication is enabled in the zone settings, users are redirected to a "silent" authentication page, which then redirects the user to the login page, as specified in the SAML-based authentication provider. (However any other AD FS configuration, or any other identity provider may not behave this way). To learn more about SAML authentication providers, see the "Implementing SAML token-based authentication" section in Plan Authentication Methods (SharePoint Foundation 2010) on Microsoft TechNet.
If more than one SAML-based authentication provider or additional authentication types are enabled in the web application, the user is redirected first to the authentication selection page, and then to the corresponding login page.
After the user is authenticated by the authentication provider, a SAML token is issued, and the user is redirected back to the SharePoint 2010 SAML token–based authentication page. The SAML token is then included in the request with the redirect. This process is known as "passive profiles". To learn more about passive profiles, see the blog post Windows Identity Foundation 101's : WS-Federation Passive Requestor Profile (Part 1 of 2).
The SAML authentication page requests a claims-based token from the SharePoint 2010 internal STS; the token request contains the original SAML token that was issued by the authentication provider. SharePoint STS then validates the token and issues the user token. This user token is then added to the request and the SAML authentication page redirects the user back to the original resource. After this point, the same process follows as in the other authentication flows.
Figure 6. SAML claims-based authentication process
Understanding the SAML Claims-Based Authentication Process
The user requests a SharePoint 2010 resource.
SharePoint redirects the user to the SAML authentication page.
Based on the configuration of the trusted login provider, the request is redirected to the enterprise STS login page or to the federated STS login page.
The user provides credentials and STS issues a SAML claims-based token.
The external STS issues the user claims-based token.
A claims-based token for the user is requested from the SharePoint STS, and the token from the external STS is used as the authentication proof.
SharePoint STS gets additional claims for the user (if an additional claims provider is registered for that web application or zone).
SharePoint STS issues the claims-based token.
The request is processed by the rest of the components in the pipeline.
The response is sent back to the user.
The identity provider is configured in SharePoint 2010 as a trusted login provider. Depending on the scenario, the identity provider could be the enterprise STS or an external STS in the case of a federated login provider. Some examples of federated login providers are a partner STS (to authenticate a partner user that does not exist in the enterprise user repository) or an external authentication provider like Windows Live ID.
Although a trusted login provider could be an external identity provider (partner STS) in SharePoint 2010, we recommend that you federate the authentication through your enterprise STS, instead of establishing the trust directly in SharePoint 2010. Then, configure the trusts with the other STS in the enterprise STS. This has the benefit of having only one entry point, where all corporate policies can be enforced. Another benefit is that most identity management systems that support claims offer better tools for managing trusts with the federated STS. If you have multiple SharePoint 2010 farms, using your enterprise STS as your "identity provider hub" enables you to manage the trusts in one place instead of in multiple places (in each SharePoint farm).
Important
In all authentication types, the SharePoint internal STS calls any claims provider that is enabled for that web application or zone, and augments the user token with any claims that are given by the claims provider. To learn more about claims providers, see Claims Tips 1: Learning About Claims-Based Authentication in SharePoint 2010.
Now that you have learned about the authentication process flow, you can explore different authentication scenarios and the options that you have to address these scenarios.
The following scenarios represent typical cases that help demonstrate problems and give implementation alternatives. Analyze your scenario and, based on the specifics of your environment, decide which solutions fit best.
Creating Custom Login Pages Used by the Forms-Based Authentication Feature
SharePoint 2010 includes a default login page that is used by the forms-based authentication feature. As described in the following scenarios, in some cases you have to make changes to this default login page.
Note
Although it is possible to change the behavior of the login page to enable high-security authentication schemes like two-factor authentication, it is not recommended. Instead, you should follow the approach described in the Enabling High-Security Authentication (2FA) in SharePoint 2010 section later in this article.
There are many scenarios that could require you to make changes in the login page; some of them are discussed in the following sections.
Addressing Authentication in Extranet Scenarios
There are multiple ways to address authentication in extranet scenarios. When possible, you should take advantage of the networking infrastructure by, for example, using a reverse proxy or using enterprise STS. In some situations this is not possible; one alternative is to use forms-based authentication.
When forms-based authentication is used for an extranet, it becomes more important to customize the login page to provide more information to the user, similar to what you see on the Microsoft Outlook Web Access login page.
In extranet scenarios where partners should have access to SharePoint sites, and when the partner does not support federated authentication, forms-based authentication is an alternative. Similar to the case described previously, it is useful to customize the login page to show more information to the user.
Branding Login Pages
A common scenario is to want to brand the login page to match the UI guidelines of the enterprise or to add information for the user, like a privacy notice, term of use, and instructions for how to log in or how to register as a new user.
Creating a "Remember Me" Capability
In some cases, you may want to enable users to have an option for remembering the user name and/or password, similar to what can be found on login pages like the Windows Live ID login pages.
Consider these additional cases where login page customization could be useful:
Troubleshooting forms-based authentication
Adding "new user registration" logic
Implementing a CAPTCHA mechanism
Adding privacy notices
Implementing "accept term of use" logic
Adding antiphishing mechanisms (for example, site image verification)
For more information about how to create a custom login page for forms-based authentication, see Writing a Custom Forms Login Page for SharePoint 2010 and How to Create Custom Login Page for SharePoint 2010 Form Based Authentication (FBA).
Customizing Authentication Selection Pages to Provide Additional Information
As explained previously, when more than one authentication provider is configured in a zone, users are redirected to a page where they can select which authentication provider to use. When the user gets to this page, the page shows only a selection control (see Figure 7).
Figure 7. Default authentication selection page
In some cases, you may want to provide additional information to aid the user in selecting the correct authentication provider. Another improvement that you can make is to add the logic for smart home realm discovery, so that users within a specific IP range are automatically redirected to the proper identity provider. There are other alternatives for smart home realm discovery; the best implementation depends on your specific scenario, and also on how you implement the home realm discovery.
Figure 8. Example of a home realm discovery page
Adding Context-Based Claims to the User's Claims Token
Contextual claims are assertions that are given to the user based on a rule. For example, a contextual claim might contain the location of the client, such as the main corporate campus or a subsidiary. In this case, the value of the claim is calculated depending on where the client connects. Later on, during authorization, this information could be used to grant or deny permissions for a resource.
In high-security scenarios, these contextual claims can provide valuable information that can be used to restrict access to resources.
Using SharePoint 2010, you can accomplish this by:
Taking advantage of the claims provider infrastructure during claims augmentation.
Implementing the rules of the contextual claims in the enterprise STS (or external STS).
We recommend implementing the rules of contextual claims in the enterprise STS for the following reasons:
Provides a central point for managing the rules
Eliminates the need to register and manage claims providers across multiple SharePoint farms
Minimizes the risk of opening a security hole due to an improperly configured claims provider
Note
The downside of implementing the rules of contextual claims in the enterprise STS is that you have to create a claims mapping in SharePoint 2010 for each of the claims that you want to use. If you decide that you want to use different claims in SharePoint 2010, you have to go through a multistep process to remove the SPTrustedIdentityTokenIssuer from all zones that are using it, delete it, recreate it with the correct claim mappings, and then re-add it to all zones that were using it. Using a claims provider is more flexible and easier to change. A claims provider is also generally more powerful to use to connect to other systems, because you are just writing Microsoft .NET Framework code.
Authenticating from a Client Application by Following the Pattern of Passive Authentication
There are scenarios where you may have to create a client application or add-in for the Microsoft Office client that is authenticating to SharePoint 2010. As you have learned in this article, the SharePoint 2010 authentication model is based in the WS-Federation passive profile that enables claims authentication scenarios for passive clients like Internet Explorer. Microsoft Office also uses this model when authenticating to SharePoint 2010.
To authenticate a call to SharePoint 2010, you have to follow the pattern that is used by passive authentication. To learn more about how to implement this pattern, see Remote Authentication in SharePoint Online Using Claims-Based Authentication. Alternatively, you can use the pattern that is described in the blog post Using the Client Object Model with a Claims Based Auth Site in SharePoint 2010.
Migrating ISAPI-Based Authentication Schemes to SharePoint 2010
In previous versions of SharePoint, additional authentication schemes were implemented in SharePoint by using the forms-based authentication flow and using custom ISAPI filters that handled the authentication process.
SharePoint 2010 implements the Internet Information Services 7 integrated pipeline, which does not support ISAPI filters. In addition to this, when a web application is configured for forms-based authentication, SharePoint 2010 makes an explicit call to the membership provider to validate the user's credentials. This causes some ISAPI-based authentication solutions to not work in SharePoint 2010.
SharePoint 2010 claims-based authentication gives you an authentication extensibility point by using the SAML claims–based authentication and the WS-Federation protocol.
Figure 9. Local security token service
As Figure 9 shows, the authentication is done outside SharePoint 2010 in the identity provider STS. The custom authentication scheme can be implemented on the identity provider (or become the identity provider).
For more information about SAML authentication, see Configure Authentication Using a SAML Security Token on TechNet.
Supporting Claims Tokens Issued by SharePoint 2010 in Claims-Aware Web Services
One of the key requirements for collaboration scenarios is being able to share data. In most cases, the data that you want to use when collaborating comes from other systems. You can take advantage of the benefits of claims-based authentication to delegate the identity of the current user to the system where the information resides. For this to work, your system must be claims-aware and must support the WS-Federation protocol. If your system is not claims-aware, you can create a middle-tier that exposes the data via a claims-aware web service.
After you have the data exposed via a claims-aware web service, you can use the Microsoft Business Connectivity Services (BCS) in SharePoint 2010 to expose the data in SharePoint 2010. To learn more about how to enable this scenario, see Consuming a Claims-Enabled WCF Web Service as a SharePoint 2010 External Content Type.
Enabling High-Security Authentication (2FA) in SharePoint 2010
Advanced authentication schemes like two-factor authentication (2FA) and client certificate–based authentication can be implemented in SharePoint 2010 by using SAML authentication. Identity management products, like AD FS 2.0, support high-security authentication, including 2FA. In this scenario, and similar to the previous scenario, the external STS is used to authenticate the user via any of the authentication methods that are supported by the provider.
For more information about configuring SharePoint 2010 for client certificate–based authentication, see Configure Client Certificate Authentication (SharePoint Server 2010) on TechNet.
To learn more about configuring SharePoint 2010 with SAML authentication, see Configure Authentication Using a SAML Security Token on TechNet.
For information about configuring AD FS 2.0, see AD FS 2.0 Deployment Guide on TechNet.
Conclusion
As explained in this article, you can take advantage of the benefits of claims-based authentication to enable different authentication scenarios. You can also make customizations to improve the user experience when collaborating through SharePoint 2010.
About the Author
Javier Dalzell works in the product solutions division of Schakra Inc, a company that provides solutions for SharePoint 2010, Office 365, cloud computing, and the mobile segment. Prior to joining Schakra, Javier worked with the Microsoft SharePoint 2010 team.
Additional Resources
For more information, see the following resources:
Security Blogs, Resource Centers, Code Samples, and SharePoint Forums
Claims Tips 1: Learning About Claims-Based Authentication in SharePoint 2010
Claims Walkthrough: Writing Claims Providers for SharePoint 2010
Claims Walkthrough: Creating Claims Providers for Trusted Login Providers for SharePoint 2010
Forms Authentication in SharePoint Products and Technologies (Part 1): Introduction
Planning, Upgrade, Migration, Administration, Configuration and Setup