forked from mCaptcha/website
136 lines
4.8 KiB
Markdown
136 lines
4.8 KiB
Markdown
---
|
|
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](../configuring-difficulty-factor/) 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](../configuring-difficulty-factor#advance-option).
|
|
|
|
> ### [Easy Mode](../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](../../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!
|