How To Use BotDetect CAPTCHA With SharePoint 2010 Server / Foundation

documentation > asp.net captcha > sharepoint

BotDetect ASP.NET Captcha protection can be added to your SharePoint (MOSS) pages using the BotDetect:Captcha custom Web Control. For demonstration purposes, this How To guide shows the steps required to create a simple SharePoint Web Part displaying the Captcha test and checking that user input matches the displayed Captcha code.

Prerequisites

Microsoft SharePoint Server 2010 (SP2010) or SharePoint 2007 (SP2007)
Microsoft Visual Studio 2010
BotDetect ASP.NET CAPTCHA v3.0.5 or newer. If you don't have it already, you can download the free version

You can also download the example SharePoint Web Part produced by following the instructions from this How To guide: BotDetectCaptchaWebPart.zip.

Create a SharePoint Web Part using BotDetect Captcha protection
Configure your SharePoint Server to enable BotDetect Captcha
- Register the BotDetect Captcha HttpHandler in SharePoint configuration
- Enable ASP.NET Session State in SharePoint configuration
Add the Web Part using BotDetect Captcha protection to a SharePoint page
(Optional) Configure BotDetect SharePoint Captcha settings
- BotDetect SharePoint Captcha localization
- Other BotDetect SharePoint Captcha options

1. Create a SharePoint Web Part Using BotDetect CAPTCHA Protection

These are the steps required to create a simple SharePoint WebPart which displays a Captcha test and checks that user input matches the displayed Captcha code. We will use C#, but please keep in mind that equivalent VB.NET code is very similar.

Set up a SharePoint Web Part Project

Start Visual Studio 2010
Select File -> New -> Project
From the Project Template Gallery select Visual C# -> SharePoint -> 2010 -> Empty SharePoint Project
At the SharePoint Customization Wizard screen, select Deploy as a farm solution
Right click your project from the Visual Studio Solution Explorer and select Add -> New Item -> WebPart
Name the new WebPart BotDetectCaptchaWebPart
Right click your project from the Visual Studio Solution Explorer and select References -> Add reference, then Browse to the BotDetect Captcha installation folder.

If you haven’t modified the installation path during setup, the BotDetect assembly will be located at C:\Program Files\Lanapsoft\BotDetect 3 CAPTCHA Component\Asp.Net\v2.0
Expand the Package folder in the Visual Studio Solution Explorer, then double-click on Package.package and open its Properties
Click on the Advanced tab and select Add -> Add Existing Assembly
Browse to the BotDetect reference
Select GlobalAssemblyCache as the Deployment Target
Click OK to save the changes

[back to top]

Modify SharePoint Web Part Code to Display and Validate the CAPTCHA

To add Captcha protection to the WebPart, we will use four controls:

a BotDetect.Web.UI.Captcha control
a TextBox for the Captcha code user input
a Button invoking Captcha validation
a Label displaying the Captcha validation result

When the Validate button is clicked and the form is submitted, user input is compared to the code displayed in the Captcha image.

In this simplified example, we just display the Captcha validation result. In a real-world scenario, the protected action (user registration, comment posting, email sending...) would only be performed if the Captcha test was passed.

The above can be achieved by adding the following C# code in the BotDetectCaptchaWebPart.cs file:

using System;
using System.ComponentModel;
using System.Web;
using System.Web.UI;
using System.Web.UI.WebControls;
using System.Web.UI.WebControls.WebParts;
using Microsoft.SharePoint;
using Microsoft.SharePoint.WebControls;

using BotDetect;
using BotDetect.Web;
using BotDetect.Web.UI;

namespace BotDetectCaptchaWebPart.BotDetectCaptchaWebPart
{
    [ToolboxItemAttribute(false)]
    public class BotDetectCaptchaWebPart : WebPart
    {
        protected override void CreateChildControls()
        {
            base.CreateChildControls();

            // create the Captcha control instance
            Captcha captchaControl = new Captcha();
            captchaControl.ID = "BotDetectCaptcha";
            // set Captcha locale; if you don't specify a locale,
            //  "en-US" will be used by default
            //captchaControl.Locale = "fr-CA"
            
            // create the user input textbox
            TextBox captchaCodeTextBox = new TextBox();
            captchaCodeTextBox.ID = "CaptchaCodeTextBox";

            // create the button
            Button validateButton = new Button();
            validateButton.ID = "ValidateButton";
            validateButton.Text = "Validate";
            validateButton.Click +=
              new EventHandler(validateButton_Click);

            // create the Captcha validation result label
            Label messageLabel = new Label();
            messageLabel.ID = "MessageLabel";

            // add all controls to the WebPart
            this.Controls.Add(captchaControl);
            this.Controls.Add(captchaCodeTextBox);
            this.Controls.Add(validateButton);
            this.Controls.Add(messageLabel);
        }

        protected void validateButton_Click(object sender, EventArgs e)
        {
            // get control references
            Captcha captchaControl = 
              (Captcha)this.FindControl("BotDetectCaptcha");
              
            TextBox captchaCodeTextBox = 
              (TextBox)this.FindControl("CaptchaCodeTextBox");
              
            Label messageLabel = 
              (Label)this.FindControl("MessageLabel");

            // get user input
            string captchaText = 
              captchaCodeTextBox.Text.Trim().ToUpper();
              
            // clear user input, since each Captcha code 
            // can only be validated once
            captchaCodeTextBox.Text = null;
            
            // validate the user input
            if (captchaControl.Validate(captchaText))
            {
                messageLabel.Text = "Success!";
            }
            else
            {
                messageLabel.Text = "Error!";
            }
        }
    }
}

[back to top]

Build & Deploy the CAPTCHA-protected Web Part to SharePoint

Build the WebPart project
Right-click your project in Solution Explorer and choose Deploy
The built WebPart will be deployed to the Sharepoint 2010 server instance

[back to top]

2. Configure Your SharePoint Server to Enable BotDetect CAPTCHA

Using BotDetect in your SharePoint sites requires a few changes in the SharePoint Web.config file. While reading the following instructions, you can also see the required changes by comparing the web.BEFORE.config and web.AFTER.config files from the BotDetect Sharepoint Web.Config example.

Register the BotDetect CAPTCHA HttpHandler in SharePoint Configuration

BotDetect uses a special HttpHandler for Captcha requests (Captcha images, sounds, resources...), which needs to be registered in your SharePoint Web.config file.

Locate the <system.web> -> <httpHandlers> section of the SharePoint site Web.config file. Add the following BotDetect handler registration to this section:

<httpHandlers>
<!-- Register the HttpHandler used for BotDetect Captcha requests-->
  <add verb="GET" path="BotDetectCaptcha.ashx" 
    type="BotDetect.Web.CaptchaHandler, BotDetect, Version=3.0.14.0, 
      Culture=neutral, PublicKeyToken=74616036388b765f" />

Locate the <system.webServer> -> <handlers> section of the SharePoint site Web.config file. Add the following BotDetect handler registration to this section:

<handlers>
<!-- Register the HttpHandler used for BotDetect Captcha requests-->
  <remove name="BotDetectCaptchaHandler"/>
  <add name="BotDetectCaptchaHandler" preCondition="integratedMode" 
    verb="GET" path="BotDetectCaptcha.ashx" 
    type="BotDetect.Web.CaptchaHandler, BotDetect, Version=3.0.14.0, 
      Culture=neutral, PublicKeyToken=74616036388b765f" />

[back to top]

Enable ASP.NET Session State in SharePoint Configuration

BotDetect requires ASP.NET Session state to function properly, which should be enabled for your SharePoint site. Also, to ensure Captcha sounds work properly in all browsers, a custom SessionIDManager (implementing an optional but recommended improvement, as explained in the BotDetect FAQ) should be registered.

In the <system.web> section of the Web.config file, locate the <sessionState> element if it exists, or add it if it doesn't. Add the following attribute to the declaration:
```
<sessionState mode="InProc" cookieless="AutoDetect" timeout="20" 
  sessionIDManagerType=" BotDetect.Web.CustomSessionIdManager,
    BotDetect, Version=3.0.14.0, Culture=neutral, 
    PublicKeyToken=74616036388b765f" />
```
If you want to use a different Session State mode or options, you can change any settings except the sessionIDManagerType – which should point to the BotDetect class as specified above, if you want Captcha sounds to work reliably.
Make sure the ASP.NET Session State HttpModule is allowed in the <system.web> -> <httpModules> section of the SharePoint Web.config file - if the following element is missing or commented-out, please add it:
```
<httpModules> 
  <add name="Session" 
    type="System.Web.SessionState.SessionStateModule" />
```

The same HttpModule should also be added the <system.webServer> -> <modules> section:

<modules runAllManagedModulesForAllRequests="true">
  <remove name="Session" />
  <add name="Session" 
    type="System.Web.SessionState.SessionStateModule" />

Make sure ASP.NET Session State is allowed in the <pages> section of the SharePoint Web.config file - the enableSessionState attribute value should be set to true:

<pages enableSessionState="true" enableViewState="true" 
  enableViewStateMac="true" validateRequest="false" 
  pageParserFilterType="Microsoft.SharePoint.ApplicationRuntime.
    SPPageParserFilter, Microsoft.SharePoint, Version=14.0.0.0, 
    Culture=neutral, PublicKeyToken=71e9bce111e9429c" 
  asyncTimeout="7">

[back to top]

3. Add the Web Part Using BotDetect CAPTCHA Protection to a SharePoint Page

Once the Web Part is deployed and the SharePoint site is configured to use BotDetect, you can add the Web Part to SharePoint pages and test BotDetect Captcha functionality.

Navigate to your SharePoint site and open a page in which you want to import the Web Part
Select Edit -> Insert -> Web Part -> Custom, choose the BotDetectCaptchaWebPart and add it to the page
After the Web Part is successfully added to the page, BotDetect Captcha should be rendered in the page, and you should be able to change the Captcha code, play Captcha sounds, and test that Captcha validation only returns true when the user input matches the displayed code.

[back to top]

4. (Optional) Configure BotDetect SharePoint CAPTCHA Settings

To keep things simple, we used the default BotDetect Captcha settings in the above instructions. Now we will show how to customize BotDetect to suit your requirements.

BotDetect SharePoint CAPTCHA Localization

You can skip this step if you plan to use only the default US English Captcha locale. It is needed to load BotDetect pronunciation sound packages required for localized Captcha sounds from a central location. We'll use the fr-CA as an example - you can find the details about other supported Captcha locales on the BotDetect Captcha localization page.

Register the global BotDetect configuration section, just below the root configuration element:

<configuration>
  <configSections>
    <!-- Register the BotDetect configuration section -->
    <section name="botDetect" requirePermission="false" 
      type="BotDetect.Configuration.BotDetectConfigurationSection, 
        BotDetect, Version=3.0.14.0, Culture=neutral, 
        PublicKeyToken=74616036388b765f" />

Create the <botDetect> section element just below the closing </configSections> element, and specify the global BotDetect sound package location:

</configSections>
<botDetect>
  <captchaSound enabled="true">
    <soundPackages folderPath="C:\Program Files\Lanapsoft\
      BotDetect 3 CAPTCHA Component\Asp.Net\BotDetectSounds" />
  </captchaSound>
</botDetect>

Make sure the Pronunciation_French_CA.bdsp is located in the specified folder, and that the IIS worker process running the SharePoint site has Read permissions to it (this is done by default for sound packages installed with the BotDetect setup).

In Web Part source code, uncomment the line setting the Captcha Locale:

// set Captcha locale; if you don't specify a locale,
//  "en-US" will be used by default
captchaControl.Locale = "fr-CA";

Rebuild and redeploy BotDetectCaptchaWebPart to the Sharepoint Server.
Reload the page containing the Web Part, and you should hear the Captcha code pronounced in Canadian French when you click the Captcha sound button

[back to top]

Other BotDetect SharePoint CAPTCHA Options

BotDetect ASP.NET Captcha allows detailed customization of many Captcha properties, and you can read more about them in the BotDetect Captcha configuration How To.

[back to top]