diff --git a/content/docs/introduction/installing-captcha/copy-sitekey.png b/content/docs/introduction/installing-captcha/copy-sitekey.png new file mode 100644 index 0000000..4008dc9 Binary files /dev/null and b/content/docs/introduction/installing-captcha/copy-sitekey.png differ diff --git a/content/docs/introduction/installing-captcha/index.md b/content/docs/introduction/installing-captcha/index.md new file mode 100644 index 0000000..1fb58a7 --- /dev/null +++ b/content/docs/introduction/installing-captcha/index.md @@ -0,0 +1,136 @@ +--- +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 +
+ + +``` + +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! diff --git a/content/docs/introduction/installing-captcha/mcaptcha-widget-installation-result.png b/content/docs/introduction/installing-captcha/mcaptcha-widget-installation-result.png new file mode 100644 index 0000000..18d60d5 Binary files /dev/null and b/content/docs/introduction/installing-captcha/mcaptcha-widget-installation-result.png differ diff --git a/content/docs/introduction/installing-captcha/new-sitekey-adv-mode.png b/content/docs/introduction/installing-captcha/new-sitekey-adv-mode.png new file mode 100644 index 0000000..279e066 Binary files /dev/null and b/content/docs/introduction/installing-captcha/new-sitekey-adv-mode.png differ diff --git a/content/docs/introduction/installing-captcha/new-sitekey-btn.png b/content/docs/introduction/installing-captcha/new-sitekey-btn.png new file mode 100644 index 0000000..956e1cb Binary files /dev/null and b/content/docs/introduction/installing-captcha/new-sitekey-btn.png differ diff --git a/content/docs/introduction/installing-captcha/new-sitekey-easy-mode-filled.png b/content/docs/introduction/installing-captcha/new-sitekey-easy-mode-filled.png new file mode 100644 index 0000000..4a27364 Binary files /dev/null and b/content/docs/introduction/installing-captcha/new-sitekey-easy-mode-filled.png differ diff --git a/content/docs/introduction/installing-captcha/new-sitekey-easy-mode.png b/content/docs/introduction/installing-captcha/new-sitekey-easy-mode.png new file mode 100644 index 0000000..5b3fc8e Binary files /dev/null and b/content/docs/introduction/installing-captcha/new-sitekey-easy-mode.png differ diff --git a/content/docs/introduction/installing-captcha/sitekey-in-dashboard-sidepanel.png b/content/docs/introduction/installing-captcha/sitekey-in-dashboard-sidepanel.png new file mode 100644 index 0000000..4745c79 Binary files /dev/null and b/content/docs/introduction/installing-captcha/sitekey-in-dashboard-sidepanel.png differ diff --git a/content/docs/prologue/_index.md b/content/docs/prologue/_index.md deleted file mode 100644 index 59d9e61..0000000 --- a/content/docs/prologue/_index.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -title : "Prologue" -description: "Prologue mCaptcha." -lead: "" -date: 2020-10-06T08:48:45+00:00 -lastmod: 2020-10-06T08:48:45+00:00 -draft: false -images: [] ---- diff --git a/content/docs/prologue/introduction.md b/content/docs/prologue/introduction.md deleted file mode 100644 index 22d72d2..0000000 --- a/content/docs/prologue/introduction.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: "Introduction" -description: "mCaptcha is a privacy focused, libre CAPTCHA system with a kickass UX." -lead: "mCaptcha is a privacy focused, libre CAPTCHA system with a kickass UX." -date: 2021-07-21 14:49 -lastmod: 2021-07-21 14:49 -draft: false -images: [] -menu: - docs: - parent: "prologue" -weight: 100 -toc: true ---- - -## Get started - -There are two main ways to get started with mCaptcha: - -1. Managed solution: We run mCaptcha, experience is similar to other - CAPTCHA solutions. -2. Self-hosted: You can host mCaptcha on your server - -## Manged solution: - -{{< alert icon="⚠️" text="Coming soon" >}} - -### Self-hosted - -One page summary of how to start a new Doks project. [Quick Start →](../self-hosted/getting-started)