BotDetect CAPTCHA ASP.NET Integration & Deployment FAQ (BotDetect v3.0; deprecated)

We do not save generated image and sound files to the hard drive or reuse them in any way, but create them on-the-fly for security reasons.

An ASP.NET HttpHandler allows us to generate Captcha images and sounds which are unique and re-generated each time they are requested.

Also, dynamically generating binary files according to incoming Http requests is usually done with HttpHandlers.

BotDetectCaptcha.ashx is not a physical file, but an ASP.NET HttpHandler.

If you followed the ASP.NET Captcha integration procedure and are having trouble displaying Captcha images, please refer to the Captcha HttpHandler troubleshooting steps.

Here is a short BotDetect Captcha troubleshooting checklist that can help you:

• Is the BotDetect HttpHandler registered in your web.config file?
• If you're using IIS 7, is the BotDetect Integrated Mode Handler also registered?
• If you're using Forms Authentication, are BotDetect paths accessible to unauthenticated visitors?
• Are you using any form of Url routing or rewriting? If so, you can either disable the Url translation for BotDetect Captcha paths, or modify the paths BotDetect uses so they are not processed by the Url Rewriter anymore.
• Make sure you're running the latest available BotDetect release, since we regularly fix bugs as they are found.

If this doesn't help, you're going to need to debug the issue a bit to determine why exactly is the image missing.

• You will need the exact Captcha image Url, which you can get by right-clicking the missing image element in IE and selecting Properties -> Address (URL). Alternatively, you can view the page source and search for LBD_CaptchaImage, then copy the src value of the <img> element. Image Url example:

  BotDetectCaptcha.ashx?get=image&c=default_samplecaptcha
    &t=7b1f4d579c064a4da5fadd3c1ab95b2d
    &s=FMM934m6JOY2%2f9lIeND22rE2dXjVvVPidyFNE%2fQ%2fDSM%3d

• Open a new browser tab, and paste the exact Captcha image Url into the address bar. When you try to access the image directly this way, you should get a more detailed error, and the details should point to the underlying cause.
• If you get a 404 Not Found error, this means something is preventing correct handling of BotDetectCaptcha.ashx requests. For example, Url Routing could be modifying the request, in which case you should exclude BotDetectCaptcha.ashx paths from routing.
• If you get a 500 Internal Server Error, you will need the full stack trace. If you only get a generic ASP.NET error page, you might have to temporarily set the <customErrors mode="Off" in web.config to see the stack trace.
• If the stack trace is not helpful, contact our Support Department and we'll take a look at it for you.

Yes, BotDetect ASP.NET CAPTCHA works with IIS 7. If you are running ASP.NET in integrated mode, you need to add the following declaration to your project's web.config file:

<system.webServer>
  <validation validateIntegratedModeConfiguration="false" />
  <handlers>
    <remove name="BotDetectCaptchaHandler"/>
    <add name="BotDetectCaptchaHandler" 
      preCondition="integratedMode" 
      verb="GET" path="BotDetectCaptcha.ashx"
      type="BotDetect.Web.CaptchaHandler, BotDetect"/>
  </handlers>
</system.webServer>

You need to disable authorization checks for BotDetect Captcha requests. Adding the following declaration to the <configuration> section of your web.config will solve the problem:

<location path="BotDetectCaptcha.ashx">
  <system.web>
    <authorization>
      <allow users="*"/>
    </authorization>
  </system.web>
</location>

The simplest workaround for the issue is to avoid rewriting BotDetect paths (BotDetectCaptcha.ashx) altogether. I'm assuming you are rewriting paths so pages have more user-friendly names – but Captcha images and sounds won't have user-friendly paths anyway.

Depending on the rewriting module you use, there should be a way to specify a list of exceptions (paths that will not be rewritten).

For example, if you're using IIS 7 Url Rewriting, you will just have to exclude BotDetectCaptcha.ashx paths from the URL Rewriting rules, as described under "Prevent Rewriting of Requests for ASP.NET Web Resources" at URL Rewriting for ASP.NET Web Forms:

<!--  The following condition prevents rule from rewriting 
  requests to BotDetectCaptcha.ashx -->
<add input="{URL}" negate="true" pattern="BotDetectCaptcha\.ashx$" />

Yes, the BotDetect HttpHandler path can be customized in the <botDetect> configuration section. if you don't have that section already registered, you'll have to add it first:

<configSections>
  <!-- Register the BotDetect configuration section -->
  <section name="botDetect" requirePermission="false" 
    type="BotDetect.Configuration.BotDetectConfigurationSection, BotDetect"/>

  <!-- ... other config sections ... -->

<configSections>

Then you can then use the captchaUrls element to specify your custom path:

<botDetect>
  <captchaUrls requestPath="TodoCaptchaCustomPath.ashx"/>

  <!-- ... other BotDetect settings ... -->

</botDetect>

Of course, you will then have to change the paths used for HttpHandler registration to match this setting.

You can customize both the filename and extension used for Captcha requests. Please keep in mind that if you use an extension which is not processed by the ASP.NET runtime by default, you will also have to update your IIS configuration, mapping the custom extension to the ASP.NET runtime in your application.

Yes, BotDetect Captcha is compatible with ASP.NET MVC, and includes required classes in the BotDetect.Web.UI.Mvc.dll assembly. Both "regular" .aspx Views and Razor Views are supported. Please check the BotDetect ASP.NET MVC integration how to guide for instructions, and the BotDetect Captcha ASP.NET MVC integration code samples for sample code.

The BotDetect ASP.NET MVC compatibility code contained in the BotDetect.Web.UI.Mvc.dll assembly is identical for all versions of ASP.NET MVC. Referencing the older version of ASP.NET MVC assemblies allows the BotDetect assembly to work in the broadest set of applications without requiring recompilation of identical code for different ASP.NET MVC version numbers.

In case you need to deploy it to an environment which only has a newer version of ASP.NET MVC installed, you can simply resolve this error by adding a binding redirect to your application's main web.config file:

  <runtime>
    <assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1">
      <dependentAssembly>
        <assemblyIdentity name="System.Web.Mvc" 
          publicKeyToken="31bf3856ad364e35" />
        <bindingRedirect oldVersion="1.0.0.0-2.0.0.0" 
          newVersion="3.0.0.0" />
      </dependentAssembly>
    </assemblyBinding>
  </runtime>
</configuration>

Yes, BotDetect Captcha protection can easily be added to ASP.NET MVC projects even without adding Model fields. A Model field is added in the integration instructions and code samples for the sake of simplicity, but is by no means necessary.

To add BotDetect Captcha to a Controller action without a Model field, make the following adjustments to the sample code:

View

Instead of adding Captcha protection referencing the Model field:

<div class="editor-label">
    @Html.LabelFor(m => m.CaptchaCode)
    @Html.Captcha(registrationCaptcha)
</div>
<div class="editor-field">
    @Html.TextBoxFor(m => m.CaptchaCode)
    @Html.ValidationMessageFor(m => m.CaptchaCode)
</div>

create the required elements explicitly instead:

<div class="editor-label">
    @Html.Label("Retype the code from the picture")
    @Html.Captcha(registrationCaptcha)
</div>
<div class="editor-field">
    @Html.TextBox("CaptchaCode") 
    @Html.ValidationMessage("CaptchaCode")  
</div>

Controller

Instead of relying on Model validation to automatically set the Model state based on the Captcha validation result:

[HttpPost]
[CaptchaValidation("CaptchaCode", "RegistrationCaptcha", "Incorrect code!")]
public ActionResult Register(RegisterModel model)
{
    if (ModelState.IsValid)
    {

use an additional action parameter and make the validation logic explicit:

[HttpPost]
[CaptchaValidation("CaptchaCode", "RegistrationCaptcha", "Incorrect code!")]
public ActionResult Register(RegisterModel model, bool captchaValid)
{
    if (ModelState.IsValid && captchaValid)
    {

A possible workaround would be to create a sub-class of the CaptchaValidationAttribute in your application, which sets the error message to the localized value. For example:

[AttributeUsage(AttributeTargets.Method, AllowMultiple = false,Inherited = false)]
  public class LocalizedCaptchaValidationAttribute :
    BotDetect.Web.UI.Mvc.CaptchaValidationAttribute
  {
      public LocalizedCaptchaValidationAttribute(string inputfield, string captchaId)
          : base(inputfield, captchaId, Resources.Error.CaptchaMismatch)
      {
      }
  }

and then, instead of:

[CaptchaValidation("Captcha", "RegistrationCaptcha", Resources.Error.CaptchaMismatch)]

use:

[LocalizedCaptchaValidation("CaptchaCode", "RegistrationCaptcha")]

Please check is IIS scripting enabled on the machine where you ran the setup package. You can do this in Control Panel, looking at the Programs and Features -> Turn Windows features on or off -> Internet Information Services -> Web Management Tools -> IIS Management Scripts and Tools option. It must be enabled before the BotDetect installation can deploy packaged samples to local IIS.

• If you are using BotDetect Captcha in an ASP.NET Web Application project or an ASP.NET MVC Web Application project (as opposed to an ASP.NET Web Site), you will have to recompile your project with the new version of the BotDetect.dll assembly, and deploy the updated build.
• If you are using the BotDetect Captcha logging utility to track BotDetect errors or Captcha validation attempts, you will also have to update the BotDetect.Troubleshooting.dll assembly to the newest version.
• If you reference the BotDetect.dll assembly with the full version number and PublicKeyToken (in your web.config file or an @Register directive for example), you will have to update these values to match the new release.

Yes, BotDetect runs in both ASP.NET Medium Trust and ASP.NET Minimal Trust.

The only possible complication is if you want to load BotDetect pronunciation sound packages from a central location, to avoid copying .bdsp files to every ASP.NET application on the server. Since lower trust levels restrict application FileIOPermissions, trying to read sound packages from another location could produce security exceptions.

To resolve this in Medium Trust, you can modify the Medium Trust configuration to also be able to access the shared BotDetect sounds folder. You can see an example of such a modification in the web_mediumtrust.config file located in the Config folder included in the BotDetect installation.

In Minimal Trust (or if you don't have permission to edit the Medium Trust configuration), you can just reference BotDetect assemblies from the GAC. Assemblies loaded from GAC can have Full Trust permissions even when the ASP.NET application is running a lower trust level.