Configuring Forms Authentication in SharePoint 2007

08 May 2007
by Damon Armstrong

SharePoint 2007 is the latest release of Microsoft's enterprise collaboration suite, which
tightly integrates with the Microsoft Office Suite and allows organizations to establish well-
managed corporate knowledge from the darkest depths of informational chaos. At least
that's Microsoft unbiased opinion. In my experience, SharePoint 2007 is a major
improvement over its predecessor, but it still takes a bit of know-how to make it work.

The latest rendition of SharePoint is built on top of ASP.NET 2.0, so ASP.NET developers
should feel right at home developing against, and customizing, SharePoint 2007. In fact,
some of the "latest technologies" in SharePoint, like Master Pages and Forms
Authentication, are "not-quite-the-latest technologies" from ASP.NET. In this article, I'll
cover some of the quirks to Forms Authentication that you will doubtless encounter when
trying to set it up in SharePoint.

A step-by-step guide to configuring Forms
authentication in SharePoint 2007

Following is a checklist for setting up Forms Authentication in SharePoint 2007

1. Setup the membership data store
2. Add a new user to the membership data store
3. Configure SharePoint Central Administration web.config
4. Configure the SharePoint site's web.config
5. Enable Forms authentication on the SharePoint site
6. Authorize the Forms-based user to access the site
7. Login

In this article, we will be using the SQL Server membership provider to authenticate
users, but you can use any membership provider that you so choose. The steps involved
will be about same, but the specifics of those steps may change depending on your
provider. I'm also assuming that you've already installed SharePoint and created the
SharePoint site on which you're trying to enable forms authentication.

Step 1: Setup the membership data store

Before you can use the SQL Server membership provider, you have to set up the database
that the provider uses to store member and role information. Microsoft ships a handy tool
named the ASP.NET SQL Server Setup Wizard along with the .NET Framework, which will
guide you through the process of creating the table structure and stored procedures
required for the provider. You can launch the wizard by running aspnet_regsql.exe from
the .NET Framework folder, which is normally found in the following location:

<WindowsDirectory>\Microsoft.NET\Framework\<version>\aspnet_regsql.exe

C:\Windows\Microsoft.NET\Framework\v2.0.50727\aspnet_regsql.exe

When you launch the wizard, the "Welcome" screen appears and tells you all sorts of useful
things about what the wizard does and the command line parameters you can use to get
more options. It makes for great reading. When you've satisfied your literary pallet, click the
Next button to display the "Select a Setup Option" screen (Figure 1).

Strona 1 z 12

Configuring Forms Authentication in SharePoint 2007

2008-03-10

http://www.simple-talk.com/content/print.aspx?article=389

Figure 1 – ASP.NET SQL Server Setup Wizard – Select a Setup Option screen

From the "Select a Setup Option" screen, choose the "Configure SQL Server for application
services" option button. This lets the wizard know you want to add new tables and stored
procedures to a membership database. You can also use the wizard to remove the table
structure and delete all data in the database, but we don't need to deal with that right now.
If you accidentally add the structure to the wrong dataset, you may have to deal with it later.
Click "Next" to move to the "Select the Server and Database" screen (Figure 2).

Strona 2 z 12

Configuring Forms Authentication in SharePoint 2007

2008-03-10

http://www.simple-talk.com/content/print.aspx?article=389

Figure 2 – ASP.NET SQL Server Setup Wizard – Select the Server and Database
screen

Enter the name of your database server in the Server textbox to let the wizard know which
SQL Server it needs to access. Then enter or select a database name in the Database
combo box. The combo box displays a drop down containing a list of existing databases. If
you want to add the tables and stored procedures for the provider to an existing database,
select the database from the list. If you want to create a new database, then just type the
name of the new database directly in the combo box and the wizard will create the
database automatically. You may also need to enter SQL Server authentication credentials
if you connect to the database using SQL Server authentication instead of Windows
authentication. These credentials are not used outside of the wizard, so it won't affect your
SharePoint configuration one way or the other. Click the Next button to continue to the
"Confirm Your Settings" screen.

The "Confirm Your Settings" screen displays a summary of the epoch-defining choices
you've made thus far in the wizard. In other words, the server and database name. If you're
feeling hesitant about either, then this is your chance to back out. When you've got your
courage built up, click the Next button.

In about a second, or about one and half seconds if you're using a Virtual PC image (like
me), the wizard creates all of the tables and stored procedures required by the membership
provider. If it takes longer than that, you've entered a setting incorrectly and the wizard is
waiting to time out (or you have a really slow machine). The wizard then displays a final
status screen indicating success or failure. If the wizard fails, it details the reasons why so
you can fix the problem. There are only six settings in the entire wizard (if you count option
buttons as "settings") so you should have a sporting chance at troubleshooting the problem.
The success screen just tells you that everything worked and to click the Finish button.

Strona 3 z 12

Configuring Forms Authentication in SharePoint 2007

2008-03-10

http://www.simple-talk.com/content/print.aspx?article=389

At this point, the database you selected is populated with the proper table structure and
stored procedures required by the provider, so now you can add a user to the membership
database.

Step 2: Add a user to the membership data store

In IIS 7.0, there is a convenient "Add User" feature that uses the membership provider
configured for the website to create a user. Unfortunately, IIS 7.0 isn't available for
Windows Server 2003 so, in a production environment, you're probably stuck with IIS 6.0,
which doesn't have a comparable add user feature. This makes adding users a bit tedious,
but here's how you do it.

1. Create a new ASP.NET web application
2. Configure the new application for Forms authentication and point it at your newly-

created membership database

3. Copy the machine key element from your SharePoint site's Web.config into to your

new web application

4. Add users and roles using the ASP.NET Web Site Administration Tool (if you have

Visual Studio 2005 handy) or create users via the CreateUserWizard ASP.NET
control.

I'm assuming you know how to create a new web site, so I'm not delving into any of the
specifics of step 1. Once you have the website created, add a new Web.config to the
application root and add the following configuration setting to the file:

Listing 01 – Web.config for the User Creation Website

<?xml version="1.0"?>
<configuration xmlns="

http://schemas.microsoft.com/.NetConfiguration/v2.0

">

<connectionStrings>
<add name="MembershipDatabaseCNX" connectionString="SERVER=localhost;
DATABASE=MembershipDatabase; TRUSTED_CONNECTION=true;"/>
</connectionStrings>
<system.web>
<machineKey
validationKey="8E074B186056F889587355255B167DA297AD837E43FD9850"
decryptionKey="991D4DEB57A2263855C31AA1D3FF4F1AD508A53D2A94658F"
validation="SHA1"
/>
<authentication mode="Forms"/>
<membership defaultProvider="DemoMembershipProvider">
<providers>
<add
name="DemoMembershipProvider"
type="System.Web.Security.SqlMembershipProvider,
System.Web, Version=2.0.0.0, Culture=neutral,
PublicKeyToken=b03f5f7f11d50a3a"
connectionStringName="MembershipDatabaseCNX"
enablePasswordRetrieval="false"
enablePasswordReset="true"
requiresQuestionAndAnswer="true"
applicationName="/"
requiresUniqueEmail="false"
passwordFormat="Hashed"
maxInvalidPasswordAttempts="5"
minRequiredPasswordLength="7"
minRequiredNonalphanumericCharacters="1"
passwordAttemptWindow="10"
passwordStrengthRegularExpression=""

Strona 4 z 12

Configuring Forms Authentication in SharePoint 2007

2008-03-10

http://www.simple-talk.com/content/print.aspx?article=389

/>
</providers>
</membership>
<roleManager enabled="true" defaultProvider="DemoRoleProvider">
<providers>
<add
name="DemoRoleProvider"
connectionStringName="MembershipDatabaseCNX"
applicationName="/"
type="System.Web.Security.SqlRoleProvider, System.Web,
Version=2.0.0.0, Culture=neutral,
PublicKeyToken=b03f5f7f11d50a3a"
/>
</providers>
</roleManager>
</system.web>
</configuration>

I've bolded a few areas of Listing 01 because you will need to modify them to work on your
system:

1. Replace the machineKey element from the listing with the machine key element

in the Web.config from your SharePoint site. The machine key from the listing is
the machineKey from my SharePoint site (on a VPC local to my box, so calm down
you crazy Hax0rs) so it won't do you much good. The machineKey element changes
from site to site, so make sure you get it from the site you want to configure for Forms
authentication and not another site, or the SharePoint Central Administration site. You
need matching machineKeys in the web application and the SharePoint site because
user passwords are hashed (one way encrypted) and the hash routine uses the
machine key value as part of the hashing algorithm.

2. Make sure your connection string points at the appropriate server that houses the

membership database you just created. Also make sure the appropriate credentials
are supplied to the connection string.

3. You can name your connection string anything you want, just make sure you use the

same name later on in the connectionStrngName parameter for the membership
and roleManager provider configurations.

4. Make sure your applicationName parameters match in both the membership and

roleManager provider configurations. The SqlMembershipProvider allows multiple
applications to use the same membership database, so a mismatched name makes
the provider think there are two applications instead of one and your members and
roles won't associate correctly.

5. Feel free to configure the password settings of the membership provider as you see

fit.

Once you have the configuration settings in place for your web application, you need a way
to add users. If you are using Visual Studio 2005, you can use the built-in Web Site
Administration Tool:

1. Click the Website menu and choose the ASP.NET Configuration menu item. This

launches a new web browser window that displays the Web Site Administration Tool.

2. Click on the Security tab or link.
3. Click on the Create User link and create a new user. Remember the login information

because you'll be needing it later.

If you do not have Visual Studio 2005, then you can use the CreateUserWizard control to
add a new user to the membership database. It's not as nice as the Web Site
Administration Tool interface, but it does get the job done. Create a new page named

Strona 5 z 12

Configuring Forms Authentication in SharePoint 2007

2008-03-10

http://www.simple-talk.com/content/print.aspx?article=389

CreateUser.aspx and add the following markup to the file:

Listing 02 – CreateUser.aspx

<%@ Page Language="C#" %>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" >
<head runat="server">
<title>Create User Wizard</title>
</head>
<body>
<form id="form1" runat="server">
<asp:CreateUserWizard ID="CreateUserWizard1"
runat="server"></asp:CreateUserWizard>
</form>
</body>
</html>

Once you save the file, navigate to the CreateUser.aspx page using your browser and
create a new user. One way or another, you should have a user in the membership
database at this point.

Step 3: Configure SharePoint Central Administration Web.config

Now that you have a user in the membership database, you've got to let SharePoint know
that the user exists and grant the user access to your SharePoint site, which means
configuring your site to use Forms authentication. You configure authentication through the
SharePoint Central Administration web interface, but Central Administration needs to know
about your membership and roleManager providers before that configuration can take
place. That means you have to add the appropriate <connectionString>, <membership>,
and <roleManager> configuration elements to the Central Administration Web.config. The
configuration for Central Administration is almost identical to Listing 01, but this time
around you do NOT set the defaultProvider attribute on the <membership> and
<roleManager> elements, and do not set the enabled attribute on the <roleManager>
element. Also, the Web.config for Central Administration already contains a great deal of
configuration data, so make sure you do not accidentally remove or modify any existing
settings.

Open the Central Administration's Web.config. If you do not know where this is located, use
the IIS Manager to determine the home directory for Central Administration and open the
Web.config from that directory.

Add the following configuration elements to the Central Administration's Web.config. Please
note that some element, like <membership>, <connectionStrings>, and <roleManager>,
may already exist in the Web.config. If they do, add the child elements to the existing item.

Listing 03 – Additions to the Central Administration Web.config

<?xml version="1.0"?>
<configuration xmlns=
"http://schemas.microsoft.com/.NetConfiguration/v2.0">
...
<connectionStrings> <!-- element may already exist -->

Strona 6 z 12

Configuring Forms Authentication in SharePoint 2007

2008-03-10

http://www.simple-talk.com/content/print.aspx?article=389

<add name="MembershipDatabaseCNX"
connectionString="SERVER=localhost;
DATABASE=MembershipDatabase;
TRUSTED_CONNECTION=true;"/>
</connectionStrings>
...
<system.web>
...
<membership> <!-- element may already exist -->
<providers> <!-- element may already exist -->
<add
name="DemoMembershipProvider"
type="System.Web.Security.SqlMembershipProvider,
System.Web, Version=2.0.0.0, Culture=neutral,
PublicKeyToken=b03f5f7f11d50a3a"
connectionStringName="MembershipDatabaseCNX"
enablePasswordRetrieval="false"
enablePasswordReset="true"
requiresQuestionAndAnswer="true"
applicationName="/"
requiresUniqueEmail="false"
passwordFormat="Hashed"
maxInvalidPasswordAttempts="5"
minRequiredPasswordLength="7"
minRequiredNonalphanumericCharacters="1"
passwordAttemptWindow="10"
passwordStrengthRegularExpression=""
/>
</providers>
</membership>
<roleManager> <!-- element may already exist -->
<providers> <!-- element may already exist -->
<add
name="DemoRoleProvider"
connectionStringName="MembershipDatabaseCNX"
applicationName="/"
type="System.Web.Security.SqlRoleProvider,
System.Web, Version=2.0.0.0, Culture=neutral,
PublicKeyToken=b03f5f7f11d50a3a"
/>
</providers>
</roleManager>
...
</system.web>
...
</configuration>

Now the Central Administration knows about your provider configurations. You would think
that having the information in the "SharePoint Central Administration" would be enough, but
no. You've got to add it to the Web.config in your SharePoint site as well.

NOTE: Notice that Listing 03 never refers to the machineKey. Not even once. This is
because you should not mess with the machineKey in SharePoint Central Administration.
Leave it alone. Do not change it. Do not delete it. Your provider does not do any encrypting
or hashing from the Central Administration, so you don't have to synchronize the
machineKey between the two sites. If you change the machineKey in Central

Strona 7 z 12

Configuring Forms Authentication in SharePoint 2007

2008-03-10

http://www.simple-talk.com/content/print.aspx?article=389

Administration, bad things could happen.

Step 4: Configure SharePoint Site Web.config

At this point, you should be tired of messing with configuration settings, but the end is near.
Go ahead and open the Web.config in the root directory of your SharePoint site, and make
the same changes that you made to the SharePoint Central Administration's Web.config.
Use Listing 03 as your guide. When you are finished, you need to set the defaultProvider
attributes in the <membership> and <roleManager> elements, and the enabled attribute
in the <roleManager> element, as shown in Listing 04.

Listing 04 – Attributes that appear in the SharePoint site Web.config (but not in the
Central Administration Web.config)

<?xml version="1.0"?>
<configuration xmlns=
"http://schemas.microsoft.com/.NetConfiguration/v2.0">
...
<system.web>
...
<membership defaultProvider="DemoMembershipProvider">
...

 

</membership>
<roleManager enabled="true" defaultProvider="DemoRoleProvider">

 

...

 

</roleManager>
...
</system.web>
...
</configuration>

Once you've entered the configuration settings, SharePoint Central Administration and your
SharePoint site have the settings required to enable Forms authentication. Time to jump
back to the SharePoint Central Administration site.

Step 5: Enable Forms Authentication on the SharePoint site

You enable Forms Authentication for SharePoint sites using SharePoint Central
Administration. Navigate to the Central Admin site using your browser. You can normally
find a shortcut to the site in the Start menu:

Programs > Office Server 2007 > SharePoint 3.0 Central Administration

Once the Central Administration Home page is loaded, click on the Application
Management link on the left hand navigation bar. You are taken to the Application
Management page, which displays a variety of administration links. Click on the
Authentication Providers link under the Application Security section on the right hand
column of the page. The Authentication Providers page loads, as shown in Figure 3.

Strona 8 z 12

Configuring Forms Authentication in SharePoint 2007

2008-03-10

http://www.simple-talk.com/content/print.aspx?article=389

Figure 3 – Authentication Providers screen

When working in SharePoint Central Administration website, make sure the correct Web
Application is selected when you are about to change configuration settings; otherwise
you'll be applying changes to the wrong site. There's a small light-blue bar in the content
pane of the page that displays the current Web Application URL. Make sure it's the web
application on which you want to enable Forms authentication. If it's not, click the little
down-arrow next to the URL and choose "Change Web Application" from the drop down
list. SharePoint then displays a popup window with a list of web application from which you
may choose.

Once you have the right web application selected, the Authentication Providers page
displays a list of the zones in that application. Click on the name of the zone in which you
want to enable Forms authentication. The Edit Authentication page displays (Figure 4).

Strona 9 z 12

Configuring Forms Authentication in SharePoint 2007

2008-03-10

http://www.simple-talk.com/content/print.aspx?article=389

Figure 4 – Edit Authentication Page

In the Edit Authentication page, choose the "Forms" option for Authentication Type. The
page refreshes and displays the Membership provider and Role manager sections. Enter
DemoMembershipProvider in the Membership provider name textbox, and
DemoRoleProvider in the Role manager name textbox, then click the Save button. You
are taken back to the Authentication Providers screen, but your zone should now say
DemoMembershipProvider under the Membership Provider Name column. Forms
authentication is now enabled on the site.

Step 6: Authorize the Forms-based user to access the site

Now that Forms authentication is enabled on the site, you can hit the site and see the login
form (Figure 6). Microsoft spared no expense making this the blandest form you'll ever see.
You will probably want to customize it so it looks a lot nicer. Maybe include some text about
how the user should enter their username and password. Nobody will read it, but it
definitely makes a login form look like a login form. Anyway, if you enter your username and
password, you will be successfully authenticated and then promptly denied access because
you have no authorization to be in the site. So, how do you get authorization? You have to
use the Site Collection Administrator account.

You may remember setting up a Site Collection Administrator when you first created the
site a while back, and it was almost certainly a Windows user account. If you extended the
site and have both a Windows zone and a Forms authentication zone, then you can login to
the Windows zone and setup the Forms user in Site Settings as you would any other user.

If you have not extended the site, then you've only got one zone and its using Forms
authentication. As such, the Windows account associated with the site collection
administrator is effectively useless and you need to change the site collection administrator
over to a Forms based account. To do this, open SharePoint Central Administration and
click on the Application Management link in the left navigation menu. When the

Strona 10 z 12

Configuring Forms Authentication in SharePoint 2007

2008-03-10

http://www.simple-talk.com/content/print.aspx?article=389

Application Management page displays, click the Site Collection Administrators link
under the SharePoint Site Management section in the left-hand column of the page. The
Site Collection Administrators page displays (Figure 5).

Figure 5 – Site Collection Administrators Page

On the Site Collection Administrators page, make sure that correct site collection is
selected. Then, enter the username of the user you created back in Step 2 in the Primary
Site Collection Administrator textbox. Click on the Check Names icon (the little red guy
with a check mark) next to the textbox. It may take a few seconds, but the page should
underline the text in the textbox indicating that the username is valid. If the username is not
valid, the page puts a red squiggly line under the username and informs you that the user
was not found. If the user is not found, make sure you typed the name correctly. If the issue
persists, go back and check your configuration settings to ensure the connection string is
valid and there are no typos.

Click on the OK button to save the changes. Your Forms authentication account is now a
Site Collection Administrator who has authorization to visit the site. You can use that
account to get into the site and setup additional Forms authentication users in Site
Settings.

Step 7: Login

When you access the site, you are presented with the previously-mentioned default
SharePoint login page (Figure 6). Enter your username and password, and then click the
Sign In button. You should be authenticated and authorized, and the site should display as
you would expect.

Strona 11 z 12

Configuring Forms Authentication in SharePoint 2007

2008-03-10

http://www.simple-talk.com/content/print.aspx?article=389

Figure 6 – SharePoint Forms Authentication Login Page

Forms Authentication and the search crawler

If you are planning on using the searching capabilities of SharePoint, then you need to
know one major obstacle with Forms authentication. The search crawler can only access
zones configured for Windows authentication. If your crawler is pointed at the default zone,
and then you change the default zone to use Forms authentication, then your search is
going to break. To get around this issue, extend your web application and create a zone
that uses Windows authentication, then point the crawler at the new zone. Even though the
search is hitting a different zone, the search findings will be available in your Forms
authentication zone.

Conclusion

Once you know how to do it, getting Forms authentication up and running on a SharePoint
site is fairly easy. You still have a bit of work to do getting your security planned out and
adding users and roles to the site, but that's the case with almost any SharePoint project. I
would also highly recommend customizing the Forms login page since it's not much better
looking out of the box than the browser based password dialog you're trying to avoid in the
first place.

© Simple-Talk.com

Strona 12 z 12

Configuring Forms Authentication in SharePoint 2007

2008-03-10

http://www.simple-talk.com/content/print.aspx?article=389