SharePoint Experts, Information Architects, Expert Witness

We provide consulting in a broad array of business and technology from architecture to design to deployment of global systems with a focus on surfacing data in the enterprise. Specialists in Microsoft, we are a premier provider of SharePoint Expertise (including 2016 and Office 365). We also provide Expert Witness/Legal Expert in eDiscovery, source discovery, patent infringement, piracy and more! We also have established SICG DLDS s.a. - our counterpart in Costa Rica that specializes in water systems (http://www.crwatersolutions.com) - Contact me direct: david_sterling@sterling-consulting.com or call 704-873-8846 x704.

Search This Blog

Sunday, May 19, 2013

Setting up Forms Based Authentication for Active Directory (SP2013/SP2010)


Setting up Forms Based Authentication for Active Directory

I've seen a number of posts on setting FBA for AD; most however leave out one or two details to actually get it to work - the following guide should assist you! Note that while this is based on 2010, it applies to 2013 as well.

BE FOREWARNED: There are very subtle differences between the web.config files so be very careful as you do this - also MAKE A BACKUP BEFORE YOU EDIT a web.config file (failing to do so will create a major headache if you have to reset to scratch!).

The setup of Forms Based Authentication (FBA) within SharePoint is based on the application setup using Claims Based Authentication and by making modifications of the web.config files on all front-end servers.
NOTE: While the setup of the application is done through the User Interface (Central Administration), changes to the web.config files can be done programmatically or more simply, editing the files. This can pose a challenge in some farm environments - SharePoint stores web.config settings within the database and depending on the circumstances, will ‘overwrite’ these files, usually when a system has been rebooted or an IISReset has been run. To make changes directly, it is recommended to use the SPWebConfigModification class and write your own feature to do these changes since once made, SharePoint will manage the changes and add them should a new server be added.


Be forewarned – SPWebConfigModification has a ‘Permanent’ setting; this really means permanent so this should never be used (SharePoint must be uninstalled to actually remove these entries).

Part 1 – Settings

Three settings are required for the process:
  1. The LDAP Path used for Active Directory
  2. The name to use for the AD Connection
  3. The name to use for the Membership Provider

The LDAP Path

Most important is the Lightweight Directory Access Protocol (LDAP) path – this can be assumed based on the domain – for example, demo.com but should be double checked via the Active Directory management console. LDAP is actually not that complicated – it’s simply a ‘path’ to identify a user, computer, etc. The path is used to identify the specific ‘object’:


For this process, the only thing to be concerned about is the OU and DC’s needed for the connection. Login to the Domain Control and open Active Directory Users and Computers – from there the DC’s (and OU’s) can be determined:


From the example above, the LDAP path is quite simple: dc=gglportmon,dc=com (note, never use spaces). If an Organization Unit (OU) was in use, for example “SPUsers”, it would appear as a folder (like Users shown) and is included in the path, for example ou=SPUsers,dc=gglportmon,dc=com.

The AD Connection

The AD connection is the connection to the LDAP path that will be added to the web.config files for the SharePoint Site – the name is not important but must be consistent across all entries made. In this example, “adconn” is used.

The Membership Provider

The membership provider is simply a name that will be used when setting up a SharePoint Claims Based site. This can be any name though like the AD Connection, it must be consistent. In this example, “admembers” is used.



Part 2 – Setting up the Security Token Service

The Security Token Service (STS) is a specialized Web service that is designed to respond to requests for security tokens and provide identity management. This service is specifically used for trusted claims based authentication and can use simple to complex types of authentication. See the overall background here: http://technet.microsoft.com/en-us/library/ee806864(v=office.14).aspx
For the purposes of setting up “AD based FBA” however, the only changes required are adding entries to the web.config file of the STS Application. While the SPWebConfigModification method should be used, in this example, it is done manually.
First, locate the ‘root’ folder of the STS application; while it is usually in the same place, it should be checked since it may not be. To check this, login to the SharePoint Web Front End (WFE) hosting the SharePoint Central Administration site – once there, open the Internet Information Services (IIS) management console.  Right click on the SharePoint Web Service and select Explore:

By default, this should open the folder <drive>:\Program Files\Common Files\Microsoft Shared\Web Server Extenisons\14\WebServices\SecurityToken:


In this folder is the ‘web.config’ file to be edited (note that by default, the file extension is not shown). Before ANY editing, make a backup of this file (above, a simple zip was created).  Two completely new sections need to be added to this file – the connectionStrings and system.web sections. These are added directly in between the </system.net> end tag and the </configuration> end tag in the existing file as follows:
      <connectionStrings>
            <add name="adconn"
                   connectionString="LDAP://gglportmon.com/DC=gglportmon,DC=com" />
      </connectionStrings>
      <system.web>
            <membership defaultProvider="admembers">
                  <providers>
                        <add name="admembers"
                               type="System.Web.Security.ActiveDirectoryMembershipProvider, System.Web, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a"
                               connectionStringName="adconn"
                               enableSearchMethods="true"
                               attributeMapUsername="sAMAccountName" />
                  </providers>
            </membership>
      </system.web>

Note that in these entries, the “AD Connection” name (adconn) and the “Membership Provider” name (admembers) are specified. Visually in the file, this should look like this:

Once these changes are made, save and close the file. To double check the service, run IISReset then browse to Central Administration. Use the IIS Management Console to ensure that the SharePoint Web Service site has not stopped – if it has it means an error in the web.config file; double check the entries and in worst case, restore the web.config from the backup and try again.

NOTE: If other sites have different kinds of authentication (FBA, etc.), there MAY ALREADY be <connectionStrings> section - if so, add ONLY the <add name="adconn" INSIDE the section following any others - for example:

<connectionStrings>
   <add name="SQLConnectionString" connectionString="Data Source=MySQL;Initial Catalog=MyFBA;Integrated Security=true;" />


   <add name="adconn" connectionString="LDAP://gglportmon.com/DC=gglportmon,DC=com" />


</connectionStrings>

In addition, there MAY ALREADY be a <system.web> section - in this case, place the place the             <membership defaultProvider="admembers"> entry just before the </system.web> tag after the last </membership> tag in the file.



Part 3 – Setting up Central Administration

Setting up the Central Administration web.config requires three entries; remember that all naming must match for the connection and membership provider; as always, make a backup of the web.config before modifying it.

First Update

The first part to add is the connection string – this is added directly after the </SharePoint> tag:
<connectionStrings>
   <add name="adconn" connectionString="LDAP://gglportmon.com/DC=gglportmon,DC=com" />
</connectionStrings>
Visually in the file, this should look like this:


NOTE: If other sites have different kinds of authentication (FBA, etc.), there MAY ALREADY be <connectionStrings> section - if so, ONLY add the <add name="adconn" INSIDE the section - for example:

<connectionStrings>
   <add name="SQLConnectionString" connectionString="Data Source=MySQL;Initial Catalog=MyFBA;Integrated Security=true;" />


   <add name="adconn" connectionString="LDAP://gglportmon.com/DC=gglportmon,DC=com" />


</connectionStrings>

Second Update

The next section is to update the “PeoplePicker” section of the web.config – this enables the SharePoint People Picker dialog box to find the AD users via the new connection. In the file search for the “PeoplePickerWildcards” section then under the <clear /> tag, add a new key value:
      <add key="admembers" value="%" />

Visually in the file, this should look like this:


NOTE: Again, there may be other keys included! Be sure to simply add the proper key line as highlighted.

Third Update

The last update is to create the membership section – this will create the actual “provider” and make it accessible for Central Administration. This section updates the existing one in the CA web.config file (located directly below the </roleManager> end tag. By default, this section looks like this:
        <membership>
              <providers>
              </providers>
        </membership>

Edit this and add the new provider as shown:
        <membership defaultProvider="admembers">
              <providers>
                    <add name="admembers"
                           type="System.Web.Security.ActiveDirectoryMembershipProvider, System.Web, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a"
                           connectionStringName="adconn"
                           enableSearchMethods="true"
                           attributeMapUsername="sAMAccountName" />
              </providers>
        </membership>

Visually in the file, this should look like this:

Once these changes are made, save and close the file. To double check the service, run IISReset then browse to Central Administration. If there are any problems with the web.config, it will be reported. Double check the entries and try again. Worst case, restore from the backup file and try again.

NOTE: If other sites have different kinds of authentication, there may ALREADY BE providers listed in the <providers> section, if that is the case, you ONLY want to add the provider entry above the </providers> tag:

                    <add name="admembers"
                           type="System.Web.Security.ActiveDirectoryMembershipProvider, System.Web, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a"
                           connectionStringName="adconn"
                           enableSearchMethods="true"


                           attributeMapUsername="sAMAccountName" />

Be aware that the name indicated by the "defaultProvider" may be set - you should leave this 'as is' OR if 'admembers' will be the default, change it.

Trouble Shooting:

Depending on the setup, an error may redirect to the default SharePoint error page thus masking what the real issue may be. To properly ‘debug’ the issue it is necessary to enable debugging in SharePoint. In the SharePoint Hive (usually c:\program files\common files\microsoft shared\web server extensions\14, but the installation may be different), open that folder and locate and open the TEMPLATE folder then the LAYOUTS folder. In this folder, there is also a web.config file. Edit this file and locate the <customErrors tag and change the mode from “On” to “Off”:


Run an IISReset then attempt to browse to Central Administration again – this time the full ‘stack trace’ of the error will appear. Any specifics on errors in the web.config file will be displayed.



Part 4 – Setting up the Site

The next activity is to setup the actual site (through CA) and to modify the web.config of that site to accommodate the AD membership provider.

Creating the new Application – Part 1

Navigate to the Central Administration site then click Manage Web Applications; when there, click New Application. On the New Application page, select Claims Based Authentication then set the Port number the site will run under (set the number then click outside of the box). If desired, specify a different name than the default:

Creating the new Application – Part 2

Scroll down the New Application page to the “Claims Authentication Types” section. For the initial setup, it is recommended that ‘Enable Windows Authentication’ be left checked – when working, this will enable either Windows or FBA to be selected when logging in. When the site has been tested, this can be disabled (see Part 4 below).
Click to select ‘Enable Forms Based Authentication (FBA)’ then under the ASP.NET Membership provider name, enter the name used for updating the web.config files – in this example, ‘admembers’ as shown:

Scroll down to the Sign In Page URL, click the radio button for "Custom Sign In Page" then enter the URL of /_forms/default.aspx. If you do not do this, the default setting will be to "/_login/default.aspx" - this virtual directory points to a common login page (i.e. for ALL sites) located here: c:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\14\template\identitymodel\login\default.aspx - it is NOT recommended that you modify that login page.

Scroll down and select to create or use an existing application pool then set the Database name as desired (the default will be “WSS_Content” or “WSS_Content_<SiteGuid>”); it is recommended this be done so that the database is easily identified in SQL Server (i.e. “WSS_Content_Site80).
Click OK to create the application. When done, navigate to the “Inetpub” directory – by default, SharePoint sites are created under the folder c:\inetpub\wwwroot\wss\VirutalDirectories\<port number> - in the example above, port 80 was used:

Notice that a folder called _forms is under this folder and the site web.config has been created. The _forms folder is where the site Login Page is stored (called ‘default.aspx’) – this file can be modified to add branding, etc. Note that if this file is modified in a multi-server farm that is already configured, the modified file must be copied to all front end servers. If modified during setup, it will be copied automatically when additional servers are added.

Creating the new Application – Part 3

The next activity is to update the newly created site web.config file. The changes here are similar to those made for the Central Administration web.config.

Updating the Web.confg –Part 1

Make a backup of the web.config in the site folder (under inetpub) then open in an editor. Find the </SharePoint> end tag and add the following between the </SharePoint> and <system.web> tags:
  <connectionStrings>
    <add name="adconn" connectionString="LDAP://gglportmon.com/DC=gglportmon,DC=com" />
  </connectionStrings>
Visually in the file, this should look like this:

Updating the Web.config – Part 2

The next section is to update the “PeoplePicker” section of the web.config – this enables the SharePoint People Picker dialog box to find the AD users via the new connection. In the file search for the “PeoplePickerWildcards” section then under the <clear /> tag, add a new key value:
      <add key="admembers" value="%" />

Visually in the file, this should look like this:

Updating the Web.config – Part 3

The final change in the web config.is to update the Membership provider section; this section is added when Forms Based Authentication was set when creating the application. In the web.config file, search for the <providers> tag. Under the <add name=”I” line already included, added the following:

        <add name="admembers"
                   type="System.Web.Security.ActiveDirectoryMembershipProvider, System.Web, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a"
                   connectionStringName="adconn"
                   enableSearchMethods="true"
                   attributeMapUsername="sAMAccountName" />

Be SURE that the name used (admembers) is the same as was used when creating the application (and added to the other web.config files). Visually in the file, this should look like this:


Creating the new Application – Part 4

Use of Windows Authentication can be removed after the site is operating properly. Disabling this is done by navigating to the Central Administration Site, clicking Manage Web Applications. On the Web Applications page, click to select the site created then in the ribbon click “Authentication Providers”. Click the ‘Default’ link on the popup to open the Web Application page. Scroll down the New Application page to the “Claims Authentication Types” section, uncheck ‘Enable Windows Authentication’ then scroll down to click OK. Opening the site (to show the Login Page), the ‘drop down’ will no longer appear indicating that the site is only using FBA.