website/content/docs/introduction/installing-captcha/index.md

---
title: "Installing mCaptcha on your website"
description: "Interested in deploying mCpatcha? From deploying a self-hosted instance to installing the CAPTCHA on your website, this guide will have you covered!"
lead: ""
date: 2022-06-22
lastmod: 2022-08-01 20:17
draft: false
images: []
menu:
  docs:
    parent: "Introduction"
weight: 511
toc: true
---

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:

{{% img src="mcaptcha-widget-installation-result.png" alt="A registration form with mCaptcha widget installed" %}}

For the purpose of this demo, we will be using
[demo.mcaptcha.org](https://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](https://demo.mcaptcha.org/join) and
create an account. When ready, sign in.

## 2. Create new site key

A [site key](/docs/terminology/sitekey/) is how a new CAPTCHA is configured within mCaptcha. To create
a new site key, click on "New Site" button in the dashboard.

{{% img src="new-sitekey-btn.png" alt="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](/docs/introduction/configuring-difficulty-factor/#advance-option).

> ### [Easy Mode](/docs/introduction/configuring-difficulty-factor/#easy-option)
>
> Easy mode asks a few basic statistics about your website and generates a
> configuration that should work for your website. Currently, easy mode is
> guided by assumptions on suitable difficulty factors to protect a
> website but it will be fine-tuned as mCaptcha sees more deployment.
>
> Configuration generated by easy mode can be tweaked later using the
> advance mode, as you become more familiar with how mCaptcha works.

Fill the form and submit it.

{{% img src="new-sitekey-easy-mode-filled.png" alt="mCaptcha dashboard with the 'new site key' form in easy mode, with details filled in" %}}

## 3. Copy widget link

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](https://github.com/mCaptcha/glue#framework-support).

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.

```html
<div id="mcaptcha__widget-container"></div>
<script src="https://unpkg.com/@mcaptcha/vanilla-glue@0.1.0-alpha-2/dist/index.js"></script>
<script charset="utf-8">
  let config = {
    widgetLink: new URL(
      {{paste yout widget link}}
    ),
  };
  new mcaptchaGlue.default(config);
</script>
```

A full example is available
[here](https://github.com/mCaptcha/glue/blob/ea576d875457de54d82bed3edfc4ee68302fa4d8/packages/vanilla/static/embeded.html).

## 5. Configure backend to authenticate CAPTCHA tokens

1. Get [access token](/docs/terminology/access-token) from the user's
   form submission payload. The access token will be associated with a
   parameter called `mcaptcha__token`.

   ```python
    mcaptcha_token = request.form["mcaptcha__token"]
   ```

2. Validate access token with mCaptcha instance

```python
payload = {
    "token": mcaptcha_token,
    "key": mcaptcha_sitekey, # captcha site key
    # mCaptcha account secret; available in settings
    "secret": mcaptcha_account_secret,
}
resp = requests.post(
    "https://demo.mcaptha.org/api/v1/pow/siteverify", json=payload
)
resp = resp.json()
```

3. If access token is valid, allow access to protected resource or deny
   access.

```python
 if resp["valid"] == False:
     return "invalid captcha", 400
 else:
     return allow_access_to_protected_resource(request.form)
```

Please see here for a complete [Flask example](https://github.com/mCaptcha/dos/tree/8f2b53ab46d64fa78a8300dc8ce9d78578ffce12/server) and here for an [Actix
Web example](https://github.com/mCaptcha/dos/tree/8f2b53ab46d64fa78a8300dc8ce9d78578ffce12/rust-server/demo-server).

Congratulations, mCaptcha is now integrated with your website!