Configuring Forms Authentication in SharePoint 2007

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).

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).

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.

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=""
            />
         </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 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 -->
      <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 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.

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).

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 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.

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.

Customizing the Login Page in SharePoint 2007

Microsoft SharePoint 2007 gives you the option of using forms authentication, but the out-of-the-box forms-based login experience is fairly bland. It’s not bad if you’re doing something for internal use, but if you’re doing something for internal use then you’re probably using Windows authentication. Forms authentication is normally found on external or customer facing sites where corporate branding is a big deal, and master pages play a major role in presenting a consistent look and feel throughout a SharePoint site. But when you apply a master page to a publishing site, or edit the default.master in a team site, you’ll quickly find out that it doesn’t alter the look and feel of the login page. In this article, we’ll take a look at why that is and what you need to do to get your login page in line with your corporate brand.

If you’re wanting to know how to enable forms authentication in SharePoint 2007, check out this article: Configuring Forms Authentication in SharePoint 2007.

Where does the login.aspx page reside?

When you try to view a protected page in a forms authenticated site, SharePoint redirects you to the login page (Figure 01). At the login screen, take a good look at the URL in your browser notice that the login.aspx page is in the _layouts folder. If you browse to the directory that houses your SharePoint application, you’ll quickly notice that there’s no _layouts folder in the directory itself. This isn’t a shocking revelation to most because a lot of the pages you see in SharePoint don’t actually exist on the file system. But if you open the Internet Information Services (IIS) manager snap-in and navigate to your SharePoint site, you’ll find that the _layouts folder is actually a virtual directory that points to the following real-life directory on your server (assuming you installed to the default location):

C:\Program Files\Common Files\Microsoft Shared\Web Server Extension\12\template\layouts

The layouts folder contains application and system pages used by all the SharePoint sites on your server. Upload a new document to a site you’ll end up on the upload.aspx page from the layouts folder. View the people who have access to the site you’ll be on the people.aspx page. And if you’re trying to login, you’ll be hitting the login.aspx page. There are 400 pages in the directory, each of which has its own specific point and purpose, so it’s impossible to go into detail on each page. But they are all in there.

Figure 1 – the login.aspx page

Global consequences of changing files in the _layouts folder

Armed with the location of the application system pages in SharePoint, you may be tempted fire up an editor and start hacking away at them, but you should probably know what you’re getting yourself into before going down that path. Remember how the _layouts folder in your SharePoint site is a virtual directory that points to C:\Program Files\Common Files\Microsoft Shared\Web Server Extension\12\template\layouts? Well, all of the SharePoint sites on your server are setup in exactly the same way. That means when you change something in the _layouts folder for one site, you’re changing it for every single SharePoint site on your server. It also means that you’re editing the only version of the file on your system, so you’d better make a backup of the folder content. Otherwise you’ll have to reinstall SharePoint to get those files back into working order if you have a nasty mishap.

Creating a site-specific _layouts virtual directory

Depending on your situation, applying changes to all of the sites on your server may or may not be a bad thing. If all of the sites on your server need the exact same branding, layout, and functionality, then go ahead and make the change directly in the standard layout folder (after backing it up). But you may just as well find yourself in a situation where each site needs to be different, so applying a sweeping change to all the sites won’t work. What do you do when you find yourself in that situation? You make a copy of the shared layouts folder specifically for your site, and make the changes in that site-specific copy. To do this, take the following actions

1.) Navigate to the C:\Program Files\Common Files\Microsoft Shared\Web Server Extension\12\template\ folder

2.) Select the layouts folder and copy it

3.) Navigate to the root directory of your SharePoint site

4.) Paste a copy of the layouts folder in your SharePoint directory

5.) Rename the layouts folder _layouts

6.) Open the IIS manager snap-in

7.) Expand your SharePoint site’s website entry

8.) Right click on the _layouts virtual directory (you may also see a non-virtual _layouts folder) and select Properties from the context menu

9.) On the virtual directory tab, click the Browse button next to the Local Path textbox to display the directory selection dialog

10.) Navigate to the _layouts folder you just created in your SharePoint site, select it, then click OK

11.) Click OK to apply the change to the _layouts virtual directory

Now you can make changes in the _layouts folder for your SharePoint site without it affecting other sites on your server.

Warning: some operations in SharePoint Central Administrator, like extending a site or changing the authentication type for a zone, can “reset” the _layouts virtual directory in your SharePoint sites so they point back to C:\Program Files\Common Files\Microsoft Shared\Web Server Extension\12\template\layouts. When this occurs, just go back into the IIS manager snap-in and point the virtual directory back over at the _layouts folder copy for your site.

Login.aspx and its Master Page

When you open the login.aspx page you’ll quickly discover it’s a content page containing markup for a title, layout table, username textbox, password textbox, a login button, a “remember me” checkbox, and a few content controls to helpful text labels next to some of the fields. Just enough markup for a non-descript login form, but certainly not enough to make the unsightly bluish surroundings on the Standard SharePoint login page (see Figure 1 again). The login page relies on the simple.master page in the _layouts folder to define most of the look and feel you see around the page (see Figure 2). Following is the Page directive found at the top of the login.aspx page which shows the association of the simple.master with the page:

<%@ P

age Language=”C#”
Inherits=”Microsoft.SharePoint.ApplicationPages.LoginPage”
MasterPageFile=”~/_layouts/simple.master”%>

When you’re considering changing the look and feel of the login form, you need to determine exactly what you’re trying to accomplish. If you want to change the branding surrounding the form itself, then you need to edit the simple.master page. If you want to change the login form itself, by rearranging controls, adding additional help text, graphics, etc, then you need to edit the login.aspx page.

Figure 2 – simple.master from the layouts folder

Editing the simple.master page

Like most master pages, the simple.master controls the look and feel or more than just a single page. In fact, it controls the look and feel of seven pages in the _layouts folder:

Page Name	Description
AccessDenied.aspx	Displays a notice that you have been denied access to the requested resource. Shows the name of the currently logged-in user and a link to sign-in as a different user.
Confirmation.aspx	Displays a message indicating that the requested operation succeeded.
Error.aspx	Displays a message indicating that an error has occurred. May also display additional stack trace information if the site has been configured to do so.
Login.aspx	Display a login page allowing users to enter forms authentication credentials.
ReqAcc.aspx	Displays a notice that you have been denied access to the requested resource.
Signout.aspx	Responsible for logging a user out of the site.
Webdeleted.aspx	Displays a message indicating the web site has been deleted.

People visiting your forms authenticated SharePoint site will run into a couple of these pages on a regular basis, so you’ll definitely want to include the simple.master in any branding efforts you undertake for your SharePoint site. But with seven different pages relying on the simple.master page, the question is what can you change on the simple.master page and what do you have to leave? Master pages contain ContentPlaceHolders controls that identify sections of the page into which content may be injected by a content page. Content pages contain Content controls that refer to the ContentPlaceHolder controls in the master. If a content page refers to a ContentPlaceHolder in the master, but you’ve removed that ContentPlaceHolder, an error occurs. So, the key to modifying a master page is to NOT remove any required ContentPlaceHolder controls.

Determinging exactly which ContentPlaceHolder controls are required in a master page can be fairly arduous because some of ContentPlaceHolders may be required by one page but not another. For example, the simple.master page contains a ContentPlaceHolder controls named PlaceHolderPageImage. If you remove it from the simple.master, the login.aspx page loads without a problem because the login.aspx page doesn’t reference the control. But you do get an error when you hit the AccessDenied.aspx page because it uses the PlaceHolderPageImage to insert a little icon on the page. Since the simple.master only controls the look and feel of seven pages, it doesn’t take too much time to check each page to see if you removed a required control. With other master pages you’re not so lucky. The application.master, for example, controls the look and feel of more than 200 pages. And that’s just too much to test.

One way to avoid the headache of accidentally removing required controls is to leave them on the page, but hide them. The process looks something like this:

1. Open your master page file

2. At the bottom of the page, add a hidden panel using the following code:

<

asp:Panel runat=”server” visible=”false”>
</asp:Panel>

3. Look through the markup of your content page and locate any ContentPlaceHolder controls (or any other server controls for that matter) on the master page

4. When you find a ContentPlaceHolder control (or a server control) cut and paste it into that hidden panel

When you finish, you’ll have a master page whose server controls are entirely contained in a hidden panel. View any page that references that master, and you’ll see that the page renders without any errors because all of controls that were originally there are still there, they’re just hidden. Of course, it also renders without any content because the hidden panel is hiding everything, but you’ll take care of that next. Now you can begin altering the look and feel of the master page by adding in the branding elements for your corporate image. As you do so, you can begin adding back in any ContentPlaceHolders and server controls that you want in the final master page.

If you’re curious, the following ContentPlaceHolders are required in the simple.master:

· PlaceHolderAdditionalPageHead
· PlaceHolderPageTitle
· PlaceHolderSiteName
· PlaceHolderTopNavBar
· PlaceHolderTitleBreadcrumb
· PlaceHolderPageImage
· PlaceHolderPageTitleInTitleArea
· PlaceHolderMain
· PlaceHolderPageDescription

You’ll also probably want to keep the ScriptLinkControl named ScriptLink1 as well, because it contains important JavaScript includes.

Editing the login page

Editing a content page is a much less perilous task than changing a master page because any bugs you introduce are localized to the page itself. You can keep a copy of the page up in your browser and refresh the screen when you make a change to see if it breaks. Like the master page, the biggest thing to remember on a content page is that the class which controls the page is looking for specific page elements. If it tries to find a page element and it’s not there, the page throws an error and won’t render. If you do not want an element to display on the screen, you can place that control in a hidden Panel control to hide it from view without breaking the code that controls the page.

Most of the changes you’ll be making in content pages are going to be cosmetic, and will likely revolve around adding some additional content here and there and changing the layout of elements inside the page. Understand, however, that all of these SharePoint pages are built using ASP.NET technology. As such, these pages can be altered any way that you could normally alter an ASP.NET page, allowing you to do some really heavy renovations if you so choose. For example, take the login.aspx page. Here’s the Page directive found in login.aspx:

<%

@ Page Language=”C#”
Inherits=”Microsoft.SharePoint.ApplicationPages.LoginPage”
MasterPageFile=”~/_layouts/simple.master” %>

Notice that the page references the simple.master as its master page and inherits its functionality from Microsoft.SharePoint.ApplicationPages.LoginPage class. If you don’t want the login.aspx page to use a master page, you can remove the MasterPageFile element in the Page directive and place all of the branding markup directly in the login.aspx page itself. I don’t recommend the approach, but you can do it. Or what if you don’t like the way the Microsoft.SharePoint.ApplicationPages.LoginPage class handles the page? You can remove the element to remove the page logic entirely, or point it at a different class. If you do remove the Inherits element, you can still write your own custom code for the page by adding server-side script directly in the login.aspx page. I put the following code in my login.aspx page and it works just fine (and it actually logs you into the site too!)

<%

@ Page Language=”C#” %>
<script runat=”server”>
protected override void OnLoad(EventArgs e)
{
Response.Write(“This is from the onload event”);
base.OnLoad(e);
}
</script>
<html>
<body>
<form runat=”server”>
<asp:login id=”login” runat=”server” />
</form>
</body>
</html>

Is it a good idea to get rid of the master page and the controlling class for a SharePoint page? Absolutely not! But it does show you the flexibility you have in editing pages.

Conclusion

You’ve seen where you can find the SharePoint login page and the master page that controls its look and feel. You’ve learned the global consequences of editing pages in the _layouts folder, and how to avoid those consequences if you need changes to apply to a single site on your server. You’ve got some good guidelines for editing master pages. And you know that you can do just about anything you want to a content page. So you should have a sporting chance at changing just about anything you want on the login page or any other SharePoint application page.