mCaptcha

Installing mCaptcha on your website

mCaptcha can protect your website from DDoS attacks. In this guide we’ll explore how to install mCaptcha on your website. The end result will be something like this, on your website:

A registration form with mCaptcha widget installed

For the purpose of this demo, we will be using demo.mcaptcha.org, a demo instance running in @realaravinth’s bedroom(for this same reason, it shouldn’t be used for anything serious)

1. Create an account and sign into the mCaptcha dashboard

Head over to demo.mcaptcha.org and create an account. When ready, sign in.

2. Create new site key

A site key is how a new CAPTCHA is configured within mCaptcha. To create a new site key, click on “New Site” button in the dashboard.

mCaptcha dashboard with the 'new site key' button highlighted

There are two options to create a new site key, easy and advanced. We are going to use the easy mode in this tutorial. If you are interested in learning more about the advance mode, please see here.

Fill the form and submit it.

mCaptcha dashboard with the 'new site key' form in easy mode, with details filled in

Submitting the form will take you to a page where site key configuration can be viewed. “View deployment” link will display CAPTCHA widget with the supplied configuration. Click on it and grab the widget link.

4. Install mCaptcha on your website

Integration support is available for some frontend JavaScript frameworks. To see full list of supported frameworks, please see here.

There are two options to use the integration library to integrate mCaptcha on your website:

  1. Serve the integration library yourself
  2. Use a CDN like unpkg.com

In this tutorial, we’ll be using the CDN.

Pasting the following snippet on the page, within the form that requires to be protected will load the mCaptcha widget with the configuration supplied. Be sure to replace Your {{paste your widget link}} with the link obtained from the previous step.

 1<label
 2  data-mcaptcha_url="{{paste your widget link here}}"
 3  for="mcaptcha__token"
 4  id="mcaptcha__token-label"
 5>
 6  mCaptcha authorization token.
 7  <a
 8    href="https://mcaptcha.org/docs/user-manual/how-to-mcaptcha-without-js/"
 9    >Instructions</a
10  >.
11  <input type="text" name="mcaptcha__token" id="mcaptcha__token" />
12</label>
13<div id="mcaptcha__widget-container"></div>
14<script src="https://unpkg.com/@mcaptcha/vanilla-glue@0.1.0-rc2/dist/index.js"></script>

A full example is available here.

5. Configure backend to authenticate CAPTCHA tokens

  1. Get authorization token from the user’s form submission payload. The access token will be associated with a parameter called mcaptcha__token.

    1 mcaptcha_token = request.form["mcaptcha__token"]

  2. Validate access token with mCaptcha instance

 1payload = {
 2    "token": mcaptcha_token,
 3    "key": mcaptcha_sitekey, # captcha site key
 4    # mCaptcha account secret; available in settings
 5    "secret": mcaptcha_account_secret,
 6}
 7resp = requests.post(
 8    "https://demo.mcaptha.org/api/v1/pow/siteverify", json=payload
 9)
10resp = resp.json()

Note: secret (mcaptcha_account_secret from above) is available in Dashboard > Settings > Secret

  1. If access token is valid, allow access to protected resource or deny access.
1 if resp["valid"] == False:
2     return "invalid captcha", 400
3 else:
4     return allow_access_to_protected_resource(request.form)

Please see here for a complete Flask example and here for an Actix Web example.

Congratulations, mCaptcha is now integrated with your website!

Edit this page on git.batsense.net

Configuring Difficulty Factor →