How to setup and Configure Forms Based User Administration Feature Release 1.0 Beta
Chandima Kulathilake, Zachary Smith
IMPORTANT UPDATE (14th July 2007)
Please note that this is now part of the SharePoint Community Kit Project (CKS). All future releases and enhancements will be released via CKS.
With WSS V3 and MOSS 2007 you can leverage ASP.Net pluggable authentication modules. This enables a WSS site to leverage user authentication other than Active Directory or Windows based logins.
This project provides WSS site’s with a Feature set that will enable administrators to manage users within an ASPNET SQL data store.
This guide assumes that you have are familiar with WSS concepts and have installed WSS V3.0. This guide presents the concept in a WSS site collection this can also be implemented for MOSS.
**Extra Reading on Forms Authentication **
Andrew Connell has written a very detailed article on how to enable forms authentication for a Web Publishing Site. [http://andrewconnell.com/blog/archive/2006/10/21/4953.aspx] This guide takes the same concept and applies this to a WSS v3.0 based site collection.
Nick Swan also has a similar article which the reader or this guide should be familiar with. [http://weblog.vb-tech.com/nick/archive/2006/06/14/1617.aspx]
The following is a very concise version of what the two above articles discuss in detail on how to configure Forms authentication for WSS V3.0.
Setup and Configuration
Prerequisites:
It is important to note that this should be thoroughly tested in your development environment before a full deployment. This Software is provided as is with no warranties.
The user who is deploying the feature is a Site Collection administrator and has knowledge in deploying and installing SharePoint solutions.
============================================================================
To enable a custom forms based WSS site collection you will first need to do some configuration within Central Administration as well as to the new web application hosting the site collection.
You will also need to create an authentication data store using the “aspnet_regsql” command line.
First create a web application from Central Administration.
In this guide we are creating a web application with a host header named “pixelfactory-dev”. Then we extend this application to the “Internet” zone as “pixelfactory.net”. This will have anonymous access turned on. (Please refer to AC’s article on why we are doing this).
Go to Central Administrations and Select Create or extend web application
Figure 1: Central Administration > Create or Extend Web Application
Select “Create a new web application”
Figure 2: Create a new Web application
In the following screen enter details for your web application
Under “Security Configuration” choose NTLM and choose Anonymous as “Yes” Select or create a new application pool account Leave the Zone to be “Default” (This is the only option)
Figure 3: Web application settings
Once the web application is created you will then create a site collection.
Choose “Team Site” template from the Site Template screen. (You can choose other templates if you wish to) For this guide we are using a WSS V3.0 Team site.
Fill in the information for your site collection.
Add the windows username of the site collection administrator. We will need this to login to the site and grant user access later on.
Once the site is created we will extend the site collection to an internet facing URL. Go back to Central administration and Choose “Create or Extend Web Application” (Figure 1)
In the next screen select “Extend an existing web application” (Figure 2)
Make sure you select the Web application you want to extend from the drop down menu. In this guide we select http://pixelfactory-dev which we created earlier for our WSS site collection.
Use the Web Application selector at the top of the page to pick the correct web application.
Create a new IIS web site to serve the same web content but this time the URL for this site will be configured to the “Internet” zone as http://pixelfactory.net
Figure 4: Extending the web application to Internet Zone
We’ll enable anonymous access later and configure the authentication provider.
Next few steps involve work outside of SharePoint.
This is where you will create a data store to contain the user credentials for forms authentication. Then we will create a web application and test the connection to our data store. (Note again AC and Nick has very detailed information on how to do this)
**Creating the Database **
The user store is an SQL Server database that is created using the aspnet_regsql.exe utility. This utility is typically located in: [ C:\WINDOWS\Microsoft.NET\Framework{VERSION} ]
From a Visual Studio 2005 command prompt, run the following command: (Assuming that Visual Studio 2005 installed on the server this solution is being tested on.)
aspnet_regsql -S
The following is a description of what the parameters mean.
-S The sql server instance to use -E Indicates that windows authentication will be used to connect to SQL Server -A m Specifies that we want to use the membership features (we will not be using roles and profiles) -d The database name to create (can be an existing database)
In this guide I am creating a database named “PixelFactoryDS” on the server “WSSDEV”
So my command looks like this “aspnet_regsql -S WSSDEV -E -A m -d PixelFactoryDS”
(For more options run aspnet_regsql /?)
Figure 5: Create SQL data store
Now we’ll create a web application to add our first user to the database.
Using Visual Studio 2005 create a web application. Choose the file system. The only use of this web application is to add the initial user to the membership provider database.
Open the web.config file of this application and add the following entries to web.config. This is the connection string to connect to the database that was created using aspnet_regsql command line.
In this example we are using integrated security which means the application pool user will need to be granted access to our membership database. To do this open up the database in SQL Server Management Studio and under the security folder right click and select ‘New User’. Enter the user that the application pool is running under and under roles check ‘aspnet_Membership_FullAccess’. Alternately we could create a user in SQL 2005 with explicit permissions to the membership database. The connection string would need to be modified accordingly with that approach as follows.
Then we’ll need to add the following entry to the web.config to setup the membership provider information.
NOTE: We are not using a role provider or profiles for this application and feature.
Many of the provider settings are configurable. However it is important to not edit the following settings to ensure all components of the authentication feature work correctly.
The provider name can be set to something more meaningful as long as the name is used consistently throughout the configuration process. Certain pages in SharePoint will display the provider name so this is important.
NOTE: It is important that in the web.config file the “passwordFormat” attribute is set to ‘Clear’ initially when we create the first user, otherwise the asp.net configuration will give you an error.
Also change the authentication mode to forms as shown below.
Now you will need to click on the Settings Icon of the web application.
This will present you with the web application admin screen to add your initial forms authentication user to the data store. To add the user to the data store select the “Security” tab. Ensure that the “Active User” checkbox is checked.
Figure 6: Add initial user
Create the initial user. You will need to have access the username and password details of this user to access the WSS site collection via forms login.
Go to the “Provider” tab and note the provider name.
In this guide it is “CustomAspNetSqlMembershipProvider” Now we’ll need to configure the WSS web application to use the above provider model for authentication.
You will also need to add the config sections to the web.config of the web application(s).
In this guide the web.config files are located in the following location(s):
C:\Inetpub\wwwroot\wss\VirtualDirectories\pixelfactory-dev80
C:\Inetpub\wwwroot\wss\VirtualDirectories\Pixelfactory.net80\
Open the web.config file and add the Membership provider information as outlined above just after the opening <system.web> tag and save your changes. Make sure you set passwordFormat to ‘Encrypted’ at this point. It is also a good idea to change the initial users password when the feature has been setup so that it is not stored in clear text.
The User Administration feature has been developed to run under a minimal trust configuration (WSS_Minimal). To ensure the security of your application your web.config files should have trust levels set to WSS_Minimum prior to feature deployment.
This is the default setting for a WSS web application. When the feature is deployed the web.config will automatically be updated to WSS_Custom to incorporate the trust policies for the User Administration feature. The WSS site will still be running under WSS_Minimal with additional permissions granted to the administration feature.
Once you have done this go to Central Administration and select the site collection URL
Figure 7: Change Membership Provider
On the Edit Authentication page change the Membership provider for Internet zone of [http://pixelfactory-dev] web application to the following settings:
Figure 8: Membership provider settings
Now you will need to give permission for anonymous users to access your site. You can do this by selecting “Site Settings” > Under “Users and Permissions”, and select “Advanced Permissions”
Then from the Tool bar “Settings” menu select “Anonymous Access”
Figure 9: Anonymous Access settings
Figure 10: Select Access Level
Do an IISREST via the command line.
Once this has been done you will be able to access http://[external] URL
NOTE: if you have deployed the “Alpha” release you will need to retract the solution via Central Administration then remove it before installing the new release.
Please follow the below steps in detail to retract the Alpha release.
http://[server]/_layouts/ManageFeatures.aspx?Scope=Site
http://[server]/_catalogs/wp/Forms/AllItems.aspx
STSADM.EXE -o addsolution -filename C:\PublicData\CustomAuthenticationSolution.wsp
Download the solution feature file “CustomAuthenticationSolution.wsp” to a local directory. Ex: C:\PublicData
To deploy the feature you will need to use the STSADM command line tool. Open a command prompt and change the directory setting to:
C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\BIN\
Now run the following command
stsadm.exe -o addsolution -filename C:\PublicData\CustomAuthenticationSolution.wsp
Figure 11: Add the solution via STSADM
Now you will need to go to Central administration operations and deploy the solution as outlined below to the web application which we have configured for forms based access.
Figure 12: Solution Management
Click on “customauthenticationsolution.wsp” to deploy the solution.
Figure 13: Deploy Solution
Note in this first release the web.config file trust levels for WSS will be modified.
Now go to Site settings and activate the Custom User Administration Feature.
Figure 14: Activate Custom User Administration Feature
By activating the feature the following files are deployed to the Layouts directory.
A new folder “UserAdmin” is created in
C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\LAYOUTS\
This contains the “Register User” form for users to self register on your site. The standard login.aspx is copied and modified as log-in.aspx and will have a links to the self registration and password retrieval pages. This is served from “_layouts/log-in.aspx”.
To configure password retrieval we must modify the web.config located at C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\LAYOUTS\UserAdmin\Web.Config. Locate the section shown below and edit it to reflect to the correct network host and desired email address.
<system.net>
For an administrator to be able to add/edit and remove users to the site you will need to create a sub-site within the site that you have deployed Forms authentication feature to.
When creating this sub-site make sure that “Do not inherit permissions” is checked. This is because we only want site administrators to have access to this site.
Once this site is created you can specify who has access to this “Administration” web site.
Typically you will grant a Windows account to have full permissions. You can also add users from the database using the people picker.
Figure 15: Add User from Data store
Once the site is created we will add the User administration web part to our “Admin” site’s homepage.
NOTE: If you get an error when adding the web part you will have to grant database, you will need to add the user to have access to the data store. (This is typically the Web application pool account)
Navigate to the site and choose edit site from the site actions menu. Click “Add Web Part”. In the web part gallery choose from “Provoke Web parts” > “user administration” web part.
Figure 16: Add Web Part
Once you add this web part you will be able to add/edit users to your site and grant user rights. The web part also allows the administrator to delete users from the system.
Figure 17: User Administration List
Figure 18: Add New User
When an anonymous user visits your site and wants to register they can do so by going to the following URL by choosing sign in on the top corner of the site.
User Sign In screen has been changed to add links to the Register Page and Forgot password pages.
http://[host]/_layouts/useradmin/register.aspx
Figure 20: User Registration Screen (New Screen with CAPTCHA)
Figure 21: Registration Confirmed
Clicking “Continue” will log the user to the site automatically. Now the user is a contributor on the site.
If a user forgets their password they have the option of having the password emailed to them through the ‘Retrieve Password’ form. Please see how to configure email for the site collection and the web.config settings.
Figure 22: Retrieve Password Screen
By self registration users are granted “Contributor” or “Member” access to the site. This means users can participate in discussion groups and blogs by self registering on your site.
Validation will take place to check the username doesn’t already exist and whether the password is valid according to the provider settings. Other general validation takes place to ensure the user has entered a value for each field. By default a user will be registered as “Active”.
The Beta Release includes CAPTCHA validation.
If a user has been locked out after too many password attempts (configurable in the membership provider settings) users can be unlocked by selecting activate.
All other standard SharePoint functionality contained in the “People & Groups” operates as per existing functionality for forms authenticated users. This includes adding and removing users from SharePoint defined groups and roles or changing user details such as the name.
This is a “Beta” release. We hope to share the source code with SharePoint MVP’s and SharePoint community groups in return for any feedback or new modules.
**Scheduled Enhancements for the Next Release(s) **
All configuration and setup related issues should be addressed to the CodePlex site.