The claims-based authentication mode was introduced with SharePoint 2010. It employs the concept of claims identity, representing each user’s identity as tokens made of claims. A claim is a statement, asserted by an issuer, about a subject, which is assumed to be true by the reader, due to a trust relationship between the reader and the issuer. The statement can be about any kind of information. For example, it could be the name, the identity, a role membership, a user preference, or anything else. Claims are issued by a claim provider and packaged into a security token, which is emitted by a security token service, which can also be an identity provider or can use an external identity provider. The identity provider is a service that authenticates the end users, based on a specific set of credentials. For example, an identity provider could be Microsoft Windows Live, Facebook, your Active Directory infrastructure with AD FS on top of it, and so on. The target of the security token is a service provider, which can be a website, a web service, or whatever else. The entity described by the security token is called Subject; in general, this is a user, a server, a service, or anything else that can have an identity of its own.

The power of claims-based authentication arises from the fact that claims-based identities are cross platform and can lead your solutions to provide single-sign-on capabilities on multiple platforms using a standard, secure, and reliable protocol. You can use claims to federate your company with customers, resellers, external service providers, and other third parties. Using claims-based authentication and external security token services and identity providers allows you to federate and trust external systems without duplicating users’ credentials and passwords. Only the identity providers will manage credentials and passwords, while all the various service providers will trust the intermediary identity providers and the security tokens emitted by the security token services.

Each claim consists of a ClaimType property, which in general is a URI that uniquely defines the type of the claim; a ClaimValue property, which is the real content of the claim; and a ClaimValueType property, which defines the data type of the ClaimValue property. Each claim can also be described by some other information, such as the Issuer and the target Subject properties.

The capability to describe an identity as a set of claims (a set of true and trustable information) allows supporting any kind of authentication mechanism. In fact, with the claims-based mode, you can use Windows Authentication, but you can also use FBA or any third-party trusted identity provider.

If you use Windows Authentication in claims-based authentication mode, the Windows identities will be converted to a set of claims representing the current user. You can still take advantage of integrated authentication, because the Windows identity of the current user will be translated into claims at no cost to you. In addition, a Windows user authenticated using classic mode is almost the same as a user authenticated with claims-based mode, because internally in SharePoint the user identity is the same (an instance of type SPUser). On the back end, SharePoint 2013 always uses claims identities—regardless of the mode you selected on the front end—to communicate between the front-end servers and the servers (within the same farm) hosting service applications.

In your code, the current user’s identity and principal will be instances of type ClaimsIdentity and ClaimsPrincipal, available in the assembly Microsoft.IdentityModel released with Windows Identity Foundation (WIF) 1.0.

When you are migrating a SharePoint 2010 web application that uses classic-mode authentication to claims-based mode in SharePoint 2013, you can use the PowerShell cmdlet Convert-SPWebApplication. The syntax is as follows:

Convert-SPWebApplication -Identity <SPWebApplicationPipeBind>
    -To <String> 
    [-Force <SwitchParameter>] 
    [-RetainPermissions <SwitchParameter>]

where the Identity argument identifies the web application to convert. The To argument declares the target authentication mode, which by now can only assume the literal value of Claims. There is also an optional Force argument that is useful to keep permissions (RetainPermissions) while migrating. For example, if you want to migrate the web application published at the URL http://migrated.intranet.local/ to claims-based authentication, you can use the following syntax:

Convert-SPWebApplication -Identity http://migrated.intranet.local
    -To Claims –RetainPermissions -Force

The command converts the web application’s authentication mode to Windows Claims authentication mode, which is the most similar to Windows Classic, and migrates the user accounts in the content database to claims-encoded values, keeping their assigned permissions. To execute the migration, you must be a member of the securityadmin role of the target SQL Server database server, a member of the db_owner role of all the content databases that need to be upgraded, and a member of the Administrators group of the server on which you are running the PowerShell script.

After migration, check in the ULS (Unified Logging System) log for any user accounts that are no longer in the Active Directory database (defined in the converted content databases), because they will not be migrated.

If you want to convert only a subset of users to claims-based authentication, such as only those who use a specific content database, PowerShell can help. Specifically, use the MigrateUsersToClaims method provided by the SPWebApplication class. You can find further details about this method at http://msdn.microsoft.com/en-us/library/jj171669.aspx.

In terms of capabilities, Windows Authentication is almost the same as the old-style classic mode. Backstage, however, the user’s identity is translated into a set of claims. If you develop a custom control or Web Part for writing a user’s identity, you will see that the current user’s identity is a ClaimsIdentity. The set of claims that comprise the user’s identity by default are

To extract the value of the claims, you can use code such as in Extracting claims from a current user’s identity.

ClaimsIdentity ci = this.Page.User.Identity as ClaimsIdentity;
if (ci != null) {
    this.Controls.Add(new LiteralControl("<h2>Claims</h2>"));
    foreach (Claim c in ci.Claims) {
        this.Controls.Add(new LiteralControl(
            String.Format(
             "<div>ClaimType: {0} - ClaimValue: {1} - ClaimValueType: {2}</div>",
              c.ClaimType, c.Value, c.ValueType)));
    }
}

In this example, it suffices to cast the current user’s identity (this.Page.User.Identity) to the ClaimsIdentity type of the Microsoft.IdentityModel namespace. Assuming the cast is successful, you will be able to enumerate the Claims property and extract each individual Claim instance.

When you configure FBA, you gain the capability to authenticate your users against an external repository of users. By default, this can be an LDAP or Microsoft SQL Server database built using the standard SQL Membership Provider of ASP.NET. Of course, you can also develop custom membership providers of your own, querying any kind of users’ repository. In the next section, you will learn how to configure SharePoint 2013 to support FBA with the standard SQL Membership Provider. For now, consider the default set of claims that make up the user’s identity when using FBA:

To configure SharePoint to support FBA with SQL Membership Provider, you first need to create a SQL Server database file that supports your environment. To help you, ASP.NET provides a tool called ASPNET_REGSQL.EXE, which is available in the Microsoft .NET Framework folder. You invoke ASPNET_REGSQL.EXE within the Microsoft Visual Studio command prompt, and it creates a SQL Server database file. The tool is organized as a wizard (see Figure 19-4) with four main pages:

Figure 19-4. The Select The Server And Database page of the ASPNET_REGSQL.EXE wizard.

After you create the database, you need to configure some users and groups to use in SharePoint. For this purpose—and for the sake of simplicity—you can create a new ASP.NET Empty Website project in Visual Studio.

You can configure the website by going to Project | ASP.NET Configuration, which brings up the ASP.NET Web Site Administration Tool. This is a well-known tool with which every ASP.NET developer should be familiar. From there, you can use the Security Setup Wizard to configure your site for supporting FBA using the previously created SQL database. You can also manually configure the web.config file, if you like. After completing this task, the web.config file of the sample site will look like the XML excerpt illustrated in The web.config file of the sample site for configuring FBA in Visual Studio.

<configuration>
  <connectionStrings>
    <add name="SharePointFBA" connectionString="server=SP2013SQL;database=SP2013_Farm_FBA;integrated security=SSPI;"/>
  </connectionStrings>
  <system.web>
    <compilation debug="true" targetFramework="4.0" />
    <authentication mode="Forms" />
    <authorization>
      <deny users="?"/>
    </authorization>
    <membership defaultProvider="FBASQLMembershipProvider">
      <providers>
        <add connectionStringName="SharePointFBA" applicationName="/"
             passwordAttemptWindow="5" enablePasswordRetrieval="false"
             enablePasswordReset="false" requiresQuestionAndAnswer="true"
             requiresUniqueEmail="true" passwordFormat="Hashed"
             name="FBASQLMembershipProvider"
             type="System.Web.Security.SqlMembershipProvider, System.Web, 
Version=4.0.0.0,Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a" />
      </providers>
    </membership>
    <roleManager enabled="true" defaultProvider="FBASQLRoleManager">
      <providers>
        <add connectionStringName="SharePointFBA" applicationName="/"
             name="FBASQLRoleManager"
             type="System.Web.Security.SqlRoleProvider, System.Web, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a" />
      </providers>
    </roleManager>
  </system.web>
</configuration>

These configuration elements will be useful when configuring SharePoint 2013 for FBA. While you’re in the Security Setup Wizard, you can also configure some users and groups, for testing purposes. In the sample code that accompanies this chapter, the following roles have been created:

In addition, the following users have been created:

As their names imply, each user belongs to the corresponding role. For example, you can give them a password value of Passw0rd!. You should test your authentication infrastructure by writing a couple of sample pages for logging in and logging out.

Now that you have a working configuration for you site, you are ready to apply that configuration to SharePoint. First, you need to locate the web.config file of the web application where you will configure FBA. By default, the root folder of a SharePoint web application is located in the C:inetpubwwwrootwssVirtualDirectories folder of every front-end server.

Next, you need to copy the connectionStrings/add element that defines your SQL Server membership database into the connectionStrings element of the target web.config file. Be careful while editing the web.config file, and make a backup copy of it before applying any kind of change. If the connectionStrings section is missing, you must create it from scratch, adding it after the configSections element of the web.config file, as shown:

<connectionStrings>
    <add name="SharePointFBA" connectionString="server=SP2013SQL;database=SP2013_Farm_FBA;integrated security=SSPI;"/>
  </connectionStrings>

Then you need to locate the Membership and RoleProvider sections, within the system.web section of the target web.config file. There, you need to copy only the providers’ configuration, without changing the default providers that were already configured by SharePoint. The result should look like the following:

<membership defaultProvider="i">
  <providers>
    <add name="i" type="Microsoft.SharePoint.Administration.Claims.SPClaimsAuthMembershipProvider, Microsoft.SharePoint, Version=15.0.0.0, Culture=neutral,       PublicKeyToken=71e9bce111e9429c" />
    <add connectionStringName="SharePointFBA" applicationName="/"
          passwordAttemptWindow="5" enablePasswordRetrieval="false"
          enablePasswordReset="false" requiresQuestionAndAnswer="true"
          requiresUniqueEmail="true" passwordFormat="Hashed"
          name="FBASQLMembershipProvider"
          type="System.Web.Security.SqlMembershipProvider, System.Web, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a" />
  </providers>
</membership>
<roleManager defaultProvider="c" enabled="true" cacheRolesInCookie="false">
  <providers>
    <add name="c" type="Microsoft.SharePoint.Administration.Claims.SPClaimsAuthRoleProvider, Microsoft.SharePoint, Version=15.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" />
    <add connectionStringName="SharePointFBA" applicationName="/"
          name="FBASQLRoleManager"
          type="System.Web.Security.SqlRoleProvider, System.Web, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a" />
  </providers>
</roleManager>

In the previous example, the code highlighted in bold shows that SharePoint 2013 already has a default membership provider named i and a default role provider named c. These are the providers that manage the claims-based infrastructure.

After you have configured the web.config file of the target web application, you need to configure the web.config file of the SPCA web application in the same way, as well as the web.config file of the internal SharePoint STS. The SPCA web application must be configured so that you can manage users defined in the FBA database from within the administrative pages, as well. You can still find its web.config file in a folder in the C:inetpubwwwrootwssVirtualDirectories path of every front-end server. The STS web application needs to have access to the FBA database in order to retrieve claims and information about the authenticated users during identity normalization. You can find the STS service of SharePoint and its web.config file in the SharePoint15_RootWebServicesSecurityToken folder.

To take full advantage of the authentication infrastructure that you have just configured, the application pools of SharePoint need to have access to the SQL Server database you configured for FBA. Thus, you need to properly configure the database’s permissions. This is a simple but fundamental task. To carry it out, you need to enable the Windows identities configured for the following:

All three need the following database role memberships:

You are almost done. Now you simply need to configure the FBA providers—for example, through the SPCA interface. To access the list of available web applications, click Application Management, then click Manage Web Applications, and then choose the FBA target. On the ribbon, click the Authentication Providers command, and in the window that appears, click the Default Configuration link. The Edit Authentication configuration page will open.

Select the Enable Forms Based Authentication (FBA) check box, and provide the name for the membership provider and role provider to use. Figure 19-5 shows the configuration dialog box, completed with information based on the current sample scenario.

Figure 19-5. The Edit Authentication configuration page of SPCA.

The last step in configuring FBA is to enable some users or roles to access the site collections defined in your target web application. You can accomplish this task either from SPCA or from the People And Groups page of the target site.

Notice that if you now try to browse for users or roles, you will be able to browse both Windows and FBA users within the same browsing windows. From the perspective of SharePoint 2013, all the users are claims identities, regardless of the authentication provider that was used. Notice how searching for users in Figure 19-6 returns one result in the role repository of FBA and three more results in the security groups of Windows.

Figure 19-6. The Share dialog box with multiple authentication providers configured, during a search for users.