From 3efcca8ee6f8e5f4e6d02db20b1b3dca56289347 Mon Sep 17 00:00:00 2001 From: unatasha8 Date: Tue, 17 Mar 2026 16:03:59 -0700 Subject: [PATCH] docs: moved and updated CAPTCHA challenge doc --- docs/kratos/concepts/security.mdx | 61 -------------------- docs/kratos/self-service/flows/captcha.mdx | 67 ++++++++++++++++++++++ src/sidebar.ts | 1 + 3 files changed, 68 insertions(+), 61 deletions(-) create mode 100644 docs/kratos/self-service/flows/captcha.mdx diff --git a/docs/kratos/concepts/security.mdx b/docs/kratos/concepts/security.mdx index a43206af7..efea95320 100644 --- a/docs/kratos/concepts/security.mdx +++ b/docs/kratos/concepts/security.mdx @@ -70,64 +70,3 @@ password policy, refer to the [password policy page](../../concepts/password-pol Ory OAuth2 and OpenID Connect is a certified OAuth2 and OpenID Connect provider. You can read more in the [OAuth 2.0 security overview](../../hydra/security-architecture) documentation. - -## CAPTCHAs - -Ory Identities supports protecting self-service flows with CAPTCHA challenges. This is useful to prevent credential stuffing, -brute force and other automated attacks. - -### Prerequisites - -Before proceeding, ensure you are on a plan that supports this feature. If you need CAPTCHA support, -[contact us](https://www.ory.com/contact). - -Supported CAPTCHA providers are: - -- [Cloudflare Turnstile](https://developers.cloudflare.com/turnstile) - -```mdx-code-block - - -``` - -1. Go to . -2. Toggle **CAPTCHA protection**. -3. Choose your preferred configuration mode: - - **Managed**: Our standard, zero-setup integrated Cloudflare Turnstile widget. - - Add or remove domains from the **Allowed domains** list. - - You must define at least one valid domain. - - You can list up to 10 domains in total. - - **Bring Your Own Keys**: Connect your existing Cloudflare Turnstile account to view detailed security analytics directly - within your own Cloudflare dashboard. - - Enter your Turnstile **Site Key** and **Secret Key**. -4. Click **Save**. -5. Navigate to any protected self-service screen, for example the registration or login page, to test the CAPTCHA protection. - -```mdx-code-block - - -``` - -Configure Managed Mode: - -```shell -ory patch identity-config --project --workspace \ - --replace '/selfservice/methods/captcha/enabled=true' \ - --replace '/selfservice/methods/captcha/config/byo=false' \ - --replace '/selfservice/methods/captcha/config/allowed_domains=["example.org", "foo.bar.dev"]' -``` - -Configure BYO Mode: - -```shell -ory patch identity-config --project --workspace \ - --replace '/selfservice/methods/captcha/enabled=true' \ - --replace '/selfservice/methods/captcha/config/byo=true' \ - --replace '/selfservice/methods/captcha/config/cf_turnstile/sitekey=your-site-key' \ - --replace '/selfservice/methods/captcha/config/cf_turnstile/secret=your-secret-key' -``` - -```mdx-code-block - - -``` diff --git a/docs/kratos/self-service/flows/captcha.mdx b/docs/kratos/self-service/flows/captcha.mdx new file mode 100644 index 000000000..927100bf0 --- /dev/null +++ b/docs/kratos/self-service/flows/captcha.mdx @@ -0,0 +1,67 @@ +--- +id: CAPTCHA +title: CAPTCHA challenge +sidebar: CAPTCHA challenge in flows +--- + +import Tabs from "@theme/Tabs" +import TabItem from "@theme/TabItem" + +Ory Identities supports protecting self-service flows with CAPTCHA challenges. This is useful to prevent credential stuffing, +brute force and other automated attacks. + +### Prerequisites + +Before proceeding, ensure you are on a plan that supports this feature. If you need CAPTCHA support, +[contact us](https://www.ory.com/contact). + +Supported CAPTCHA providers are: + +- [Cloudflare Turnstile](https://developers.cloudflare.com/turnstile) + +```mdx-code-block + + +``` + +1. Go to . +2. Toggle **CAPTCHA protection**. +3. Choose your preferred configuration mode: + - **Managed**: Our standard, zero-setup integrated Cloudflare Turnstile widget. + - Add or remove domains from the **Allowed domains** list. + - You must define at least one valid domain. + - You can list up to 10 domains in total. + - **Bring Your Own Keys**: Connect your existing Cloudflare Turnstile account to view detailed security analytics directly + within your own Cloudflare dashboard. + - Enter your Turnstile **Site Key** and **Secret Key**. +4. Click **Save**. +5. Navigate to any protected self-service screen, for example the registration or login page, to test the CAPTCHA protection. + +```mdx-code-block + + +``` + +Configure Managed Mode: + +```shell +ory patch identity-config --project --workspace \ + --replace '/selfservice/methods/captcha/enabled=true' \ + --replace '/selfservice/methods/captcha/config/byo=false' \ + --replace '/selfservice/methods/captcha/config/allowed_domains=["example.org", "foo.bar.dev"]' +``` + +Configure BYO Mode: + +```shell +ory patch identity-config --project --workspace \ + --replace '/selfservice/methods/captcha/enabled=true' \ + --replace '/selfservice/methods/captcha/config/byo=true' \ + --replace '/selfservice/methods/captcha/config/cf_turnstile/sitekey=your-site-key' \ + --replace '/selfservice/methods/captcha/config/cf_turnstile/secret=your-secret-key' +``` + +```mdx-code-block + + +``` diff --git a/src/sidebar.ts b/src/sidebar.ts index 1560bb6df..73aec49ab 100644 --- a/src/sidebar.ts +++ b/src/sidebar.ts @@ -382,6 +382,7 @@ const kratos: SidebarItemsConfig = [ "kratos/self-service/flows/user-logout", "kratos/self-service/flows/user-settings", "kratos/self-service/flows/verify-email-account-activation", + "kratos/self-service/flows/CAPTCHA", "kratos/self-service/flows/account-recovery-password-reset", "kratos/self-service/flows/user-facing-errors", ],