When a CAPTCHA stage belongs in your authentik flows
A CAPTCHA stage belongs in an authentik flow when automated sign-up or login attempts reach your self-hosted instance and you need a human-verification step before the flow continues. In authentik, the captcha stage is a flow stage you place inside a login or enrollment flow, so it runs as one step in the sequence a user passes through. It is one control among several. Reputation policies that score failing clients, MFA that proves possession of a second factor, and rate limits at your reverse proxy each address a different part of the abuse, and a CAPTCHA works best when it is placed where the other controls cannot stop a bot on their own.
authentik 2026.8 added two things to the captcha stage: JSON verification requests and the self-hostable Cap CAPTCHA provider. Before you choose a provider, confirm in your own environment whether it must run inside your network, whether your users can reach its endpoints, and how it fits your data handling rules. Vendor selection is outside this page. The rest of this page covers how to configure the stage, bind it to the right flow, and protect its settings from tampering, using the release notes for authentik 2026.8 as the starting point for version-specific behavior.
Plan the placement before you build. Attach the stage to the flow step where abuse actually occurs, such as the enrollment step for sign-up abuse or the identification step for credential stuffing, and test the flow with a normal account and a deliberately failing client. Note which policies decide whether the stage runs at all, because a CAPTCHA that appears for every user adds friction without adding protection. Record who is allowed to edit flows and stages, since a weakened captcha configuration is a silent failure.
Choosing a CAPTCHA provider for authentik
Hosted CAPTCHA services run their challenge and verification on infrastructure the vendor operates. When a user meets the challenge, the browser loads the provider's client code and sends signals to the provider, and your authentik server then asks the provider to verify the response. That means login traffic touches a third party, and your login path depends on that provider being reachable. For many organizations the operating burden is low, since there is nothing to host, but the data handling and availability questions move to your vendor review.
- Data flows: Confirm which browser signals, IP addresses and page identifiers the provider collects during the challenge, and whether they are used for the provider's own purposes.
- Data residency: Ask where verification data is processed and stored, and whether the provider offers regional processing options that match your requirements.
- External dependency: If the provider is slow or unreachable, enrollment and login through the affected flow may fail, so plan a fallback decision for that case.
- Privacy notices: Update your privacy documentation and cookie or consent records to cover the third party, since users see its code on your login page.
- Vendor terms: Review the provider's contract, data processing terms and subprocessors through your procurement process.
Before you choose a hosted provider, confirm in the CAPTCHA stage settings and the release notes for your authentik version which providers that version supports.
authentik 2026.8 added the self-hostable Cap CAPTCHA provider to the captcha stage. Running Cap inside your own infrastructure keeps challenge verification within networks you control, which matters where data residency or an external dependency is a blocker. The trade-off is that you own its availability, patching and capacity, so the service becomes part of your authentik operating scope and needs monitoring like any other internal dependency.
- Data residency: Verification requests stay inside the environment you deploy, which simplifies residency discussions with your privacy and legal teams.
- Operating ownership: Your team or your partner must deploy, patch, back up and monitor the Cap service, and define who responds when it fails.
- Network placement: Confirm that browsers can reach the Cap service and that authentik can reach it for verification, including through any reverse proxy and network segmentation you apply.
- Failure behavior: Decide how login and enrollment behave if Cap is down, and test that path before go-live.
- Version alignment: Track Cap release changes alongside authentik upgrades, and confirm the supported Cap configuration in the 2026.8 release notes.
Before you commit to Cap, check the provider list in your authentik version's stage settings and the 2026.8 release notes, then confirm the Cap deployment requirements with the project.
The right family depends on your data rules, your operating capacity and how much availability risk your login flows can carry. Hosted services usually demand more vendor and privacy review, while Cap demands more platform operations. Many teams decide by asking which risk they prefer to own: a third party's processing and availability, or their own service's uptime and patching. Document the decision with the flow it protects, because a CAPTCHA on enrollment has different consequences from one on password login.
- Risk owner: Name who owns the provider relationship or the service, and who signs off on data processing.
- Flow scope: Decide whether the challenge applies to login, enrollment, recovery or only to clients flagged by reputation policies.
- Availability target: Ask your team how long a CAPTCHA outage can be tolerated before users are blocked, and set that expectation with stakeholders.
- Audit evidence: Keep the provider choice, configuration and approval records so auditors can trace how the control was set up.
- Change control: Treat provider changes as configuration changes that go through review, since they alter user-facing behavior.
Before you decide, ask a partner to map these questions to your environment so the choice reflects your actual data and availability constraints.
Captcha stage options and when each fits
This table compares the main configuration choices on an authentik CAPTCHA stage and where each one sits in a login or enrollment flow. Read each row for when the option fits, what it trades off, and which values to confirm in the admin interface for your installed version.
| Choice | When it fits | Trade-off | Confirm in the admin interface |
|---|---|---|---|
| CAPTCHA provider (hosted service) | Your users can reach an external CAPTCHA service and your policy allows that third-party call from the login path | Adds a dependency on the provider's availability and an outbound call that some air-gapped or restricted networks cannot make | Provider list, site key and secret key fields, and whether the stage requires the outbound network path to be open |
| CAPTCHA provider (Cap, self-hostable) | You want the challenge verified by a service you run, and your networks keep login traffic inside your own infrastructure | You must host and patch the provider and keep its verification endpoint reachable from authentik, which adds an operational component to plan for | Whether Cap appears in the provider list on your installed version, since it arrived in 2026.8, and the endpoint and key values you enter |
| JSON verification requests | Your provider or self-hosted service expects a JSON body rather than the default form submission | Mismatched request format causes every challenge to fail, so testing against the provider is required before rollout | Whether the JSON verification option is enabled on the stage and the request format your provider documents |
| Form-style verification (default request) | An existing provider integration already works and you do not need a change in request format | Requires no change, but if a provider moves to JSON-only requests the stage will stop validating users | The default request setting on the stage after any upgrade, since defaults can differ between versions |
| Flow stage binding (login flow) | You want to challenge only sign-ins that reach the login step, for example after a reputation or GeoIP check | Attackers who fail earlier steps may never see the CAPTCHA, and the order of bindings decides what users experience | Binding order, the policy attached to the binding, and whether the stage runs on every attempt or only on conditions you set |
| Flow stage binding (enrollment flow) | You open self-service signup or invitation-free enrollment and need to stop automated account creation | Adds friction for legitimate new users, so the challenge should be tested on mobile and with assistive technologies | Binding order within the enrollment flow and whether it sits before or after the user prompt stage |
| Position in the flow relative to identification and password stages | You want the CAPTCHA to protect the password check from automated guessing | Placed before identification, it challenges every visitor including those who only land on the page; placed later, bots may submit credentials first | Stage order in the flow diagram and the rule that enforces the challenge for that binding |
| Stage configuration protection | You have delegated administration or a shared admin team and want CAPTCHA keys and settings to stay under control | Blocking API paths at the reverse proxy can also block legitimate administrator tooling, so test automation first | The reverse proxy rules covering the CAPTCHA and blueprint API paths named in the hardening guide |
How to add a CAPTCHA stage to an authentik flow
This sequence takes a CAPTCHA stage from creation to a tested login or enrollment flow, so that bots and scripted attempts must pass a challenge before authentik continues. Each step ends with a check you can run before users see the change.
Confirm the provider and its keys
Before creating anything in authentik, decide which CAPTCHA provider your organization will use and confirm that you hold its site key and secret key. Check the provider's own documentation for the verification endpoint it expects, and confirm whether your network can reach it from the authentik server and worker containers. Confirm the provider list against the authentik 2026.8 release notes, since the Cap provider and JSON verification requests were added in that release and your version must include them. The step is done when you have a written record of the provider, the keys and the endpoint, and you have confirmed your authentik version is 2026.8 or later if you need those options.
Create the CAPTCHA stage
In the authentik Admin interface, open the stages section and create a new CAPTCHA stage. Enter the provider settings you confirmed in the previous step, including the site key, secret key and verification endpoint, and choose whether to send verification requests as JSON if your provider requires it. Save the stage and give it a name that makes its role clear to administrators, such as the flow it protects. The step is done when the stage appears in the stage list with the settings you entered, and no error appears on save.
Bind the stage into the target flow
Open the login or enrollment flow you want to protect and add a stage binding for the CAPTCHA stage. Place it where the user has submitted the information the challenge should guard, typically before the stage that verifies credentials or creates the account, and not after a point where the account is already created or the session already authenticated. Review the order of all bindings in the flow, because a CAPTCHA placed after the password or identifier step does not stop a client from testing those fields. The step is done when the flow's binding list shows the CAPTCHA stage in the position you intended.
Check the flow in a fresh session
Open a private browser window or a different browser profile so that you have no existing authentik session, then start the flow you changed. Confirm that the CAPTCHA challenge is presented at the expected point and that the flow does not skip it. If the challenge does not appear, review the stage binding order and any policies bound to the flow or stage, since a policy can change which stages run. The step is done when a fresh session reaches the challenge in the correct position and you can see it in the rendered page.
Test with a valid challenge
Complete the CAPTCHA challenge correctly in the fresh session and continue through the flow. Confirm that the next stage in the flow runs and that the user reaches the expected outcome, such as the password prompt, the enrollment form or the signed-in state. Check the authentik event log for the flow execution so that you can see the CAPTCHA stage recorded as passed. The step is done when a legitimate attempt completes the flow without extra prompts and the event log reflects the successful verification.
Test with an invalid challenge
Start a new fresh session and submit an incorrect or expired CAPTCHA response, or deliberately skip the challenge if the interface allows it in a test context. Confirm that the flow does not advance past the CAPTCHA stage and that the user sees a failure message rather than the next step. Then review the event log to confirm that the failed verification was recorded. Repeat this test for the enrollment flow if you protect it separately. The step is done when every invalid attempt stops at the CAPTCHA stage and the failure appears in the logs.
Protect the CAPTCHA configuration from tampering
Review your reverse proxy rules so that the CAPTCHA stage configuration and the blueprint endpoints cannot be changed through the public internet. The authentik hardening guide suggests blocking the paths beginning with the captcha stage API and the managed blueprints API at the proxy, and you should confirm the exact path patterns against the current guide before you apply them. Test that administrative access still works from the networks you intend to allow, and that public requests to the blocked paths are refused. The step is done when the blocked paths return a refusal from outside your admin network and the CAPTCHA settings remain editable from inside it.
What JSON verification requests change for your flow
authentik 2026.8 added JSON verification requests to the captcha stage, so the stage can send its verification call to your CAPTCHA provider in JSON rather than the default request format. For most administrators nothing changes on day one, because the default remains in place until you choose otherwise. The option matters when your chosen provider, or a proxy or verification service in front of it, expects a JSON body, or when your integration team wants one consistent request format across the stages they maintain. Confirm the exact behavior, including which fields are sent and how the response is read, in the authentik 2026.8 release notes before you change the setting on a production flow.
Treat the JSON option as a change to the contract between authentik and your provider, not a cosmetic setting. Send a test challenge through a non-production flow, capture the request your provider receives, and confirm that the verification response is accepted and that a failed token is rejected. Check the provider's own documentation for the request body it expects, since the provider, not authentik, decides whether a given request is valid. If your provider is the self-hostable Cap provider, confirm its supported request format for the version you run, and do not assume that the format used for a hosted provider carries over.
Plan for the cases where the request format breaks a working login path. A mismatch usually shows up as every CAPTCHA attempt failing, which can lock out legitimate users during enrollment or sign-in. Before the change, record which flows reference the stage, agree who signs off on the switch, and keep a rollback step ready. Also note that any reverse proxy rules or monitoring that inspect these requests should be reviewed when the format changes, because they may have been written against the default body.
Protecting CAPTCHA settings from tampering
A CAPTCHA stage only helps if it stays enabled and configured as intended. The cards below cover the threats to the stage itself, the reverse proxy rule the hardening guide suggests, the admin and audit controls that sit around it, and the cost of blocking paths that automation may depend on.
Threats to the stage itself
A CAPTCHA stage can be weakened in two ways: someone with administrative rights disables it or changes its provider settings, or an attacker finds a route to the configuration API and edits it without logging in through the normal console. Either change can quietly remove the challenge from login or enrollment flows. Treat the stage as a security control, and check that a disabled or reconfigured stage is noticed quickly.
Blocking the stage API at the proxy
The authentik hardening guide suggests blocking /api/v3/stages/captcha* at the reverse proxy so that the CAPTCHA configuration endpoints are not reachable from outside the admin network. Test the rule against your own admin paths before rollout, and confirm that the exact path patterns match your installed version.
Blocking blueprint paths
The same guide suggests blocking /api/v3/managed/blueprints* at the proxy. Blueprints can create or change flows and stages, so an endpoint that accepts blueprint changes is a path to altering a CAPTCHA stage indirectly. Restrict this path to the operators who legitimately apply blueprints, and confirm which hosts and networks need access.
Restricting administrator roles
Limit who can edit flows, stages and bindings to a small group of named administrators, and separate read access from write access where your role model allows it. Review membership of the admin groups on a fixed schedule. A CAPTCHA stage is only as protected as the most privileged account able to edit it.
Auditing and reviewing changes
Record who changed a CAPTCHA stage, when, and what the previous value was. Forward authentik logs to your central log platform and alert on changes to stages and flow bindings, including a stage being unbound from a login flow. Ask your team which events are logged and retained in your version before you rely on them.
Trade-off with automation
Blocking these paths also blocks pipelines that manage the stage through the API or through blueprints, including configuration as code. Decide which tool owns the CAPTCHA configuration, allow only that tool's network path, and move manual changes through the same review process. If you skip this step, the first deployment pipeline run may fail in a way that looks like an outage.
Running CAPTCHA stages after go-live
After go-live, the most useful signal for a CAPTCHA stage is how often real users fail the challenge or abandon the flow at that step. Set up a dashboard or log query that tracks the CAPTCHA stage's failure and completion counts alongside the login or enrollment flow's overall completion rate, so a sudden drop after a configuration change or a provider-side change shows up quickly. Confirm which events authentik writes for stage failures in your version and whether they reach your central log platform, since a challenge that silently blocks users is hard to notice without this baseline. Review the numbers with the service desk, because users who abandon a flow rarely file a ticket about the CAPTCHA itself.
Provider credentials need the same routine as any other secret. Keep the site and secret keys for your chosen provider in the store your team already uses for secrets, record who holds them, and plan a rotation with the provider's own procedure. Rotate in a maintenance window, update the stage configuration, then confirm a test login succeeds in each enrolled flow. If you use the self-hostable Cap provider added in 2026.8, treat its service as part of your own infrastructure, with its own patching, certificate renewal and availability checks, because a failed verification endpoint will block every user at that step.
Upgrades are where CAPTCHA behavior most often changes unexpectedly. Check the authentik security policy before choosing a target version, and stay on a release line that still receives security fixes, currently listed as 2026.5.x and 2026.8.x. Read the release notes for each step, since JSON verification requests and the Cap provider were introduced in 2026.8 and your stage settings may need review after the move. After every upgrade, run a scripted set of test logins and enrollments through each flow that contains a CAPTCHA stage, including a failed challenge, and record the results so you can compare them with the next upgrade. Confirm the exact upgrade path with the authentik documentation for your current version.
Questions teams ask before adding a CAPTCHA to authentik
Can our own team configure a CAPTCHA stage in authentik without outside help?
Yes, a team that already runs authentik and understands its flows can add a CAPTCHA stage to a login or enrollment flow alone. The work is a provider choice, a stage configuration with the site and secret keys, and a binding into the right flow. The harder part is the surrounding work: testing every path a user can take through the flow and protecting the CAPTCHA settings from changes by non-administrators. If your team has not yet built flows and policies in authentik, the learning curve is the larger cost, not the CAPTCHA itself. Confirm the stage fields against the release notes for your version before you copy any configuration.
What makes a CAPTCHA setup take more effort?
Effort rises with four factors. Flow complexity matters most: a single login flow with one stage is small, while enrollment, recovery and invitation flows that share stages need separate testing. Provider choice matters next, since a hosted provider brings its own account, keys and data handling review, while a self-hosted provider such as Cap, added in 2026.8, brings its own service to run. Reverse proxy hardening adds work because the CAPTCHA configuration endpoints must be blocked from outside administrative access. Testing across login and enrollment closes the list, because a CAPTCHA that blocks a legitimate user at enrollment is a support issue.
Does adding a CAPTCHA to authentik require an Enterprise license?
Not by default, but you should confirm it for the code you run. authentik's repository places most of its code under the MIT license, while code in the enterprise directory is covered by a separate enterprise license defined in that directory. Before you rely on the stage, check the license file and the directory that contains the stage code in the release you deploy. Enterprise pricing on the authentik pricing page applies to the Enterprise features listed there, so a license question about one stage should be answered from the license text and your edition, not from the pricing page alone.
What does our team need to provide for a CAPTCHA project?
Plan to provide the following before work starts:
- Access to the authentik administrator interface and the flows that will carry the CAPTCHA, including login and enrollment
- A decision on the CAPTCHA provider and an account with that provider if it is hosted, or hosting capacity if it is self-hosted
- Access to the reverse proxy or ingress configuration so administrative API paths can be restricted
- A test group of users who can exercise login, enrollment and recovery before production use
- A named owner for the CAPTCHA keys so rotation and access reviews have a clear responsible party
How long does a CAPTCHA setup take in authentik?
The duration depends on scope, and no fixed figure applies to every environment. A single login flow in a test instance is a short task for an experienced administrator. Adding the CAPTCHA to several flows, adding a reverse proxy rule, running user testing across enrollment and recovery, and documenting the change for auditors extends the work considerably. Ask any provider for a schedule tied to a written scope that lists the flows, the provider, the proxy platform and the test cases. Do not accept a duration that does not name those items.
When does outside help make sense for CAPTCHA in authentik?
Outside help makes sense when the flows are shared across several applications, when the reverse proxy is managed by another team with change controls, or when your environment must be hardened to an audit standard. It also helps if you plan to self-host a provider and need the service sized and monitored alongside authentik. DeployOpen plans, implements, hardens and documents self-hosted platforms in infrastructure you control, and most engagements are fixed-scope with the scope agreed in writing before work starts. DeployOpen does not issue audit reports or certifications, so independent auditors would still assess the controls.
What cost components should we compare in a CAPTCHA quote?
A quote for this work should separate the one-time build from any recurring costs. One-time items include the design of the flow changes, the stage configuration, the proxy hardening, testing and documentation. Recurring items include provider fees if you use a hosted provider, and the operation of a self-hosted provider, including updates. Ask the provider to state which items are included, which are optional, and what changes after an authentik version upgrade. Confirm current provider pricing with the provider directly, since it is not a figure this page supplies.
How DeployOpen scopes CAPTCHA work
DeployOpen fixes the scope of CAPTCHA work in writing before any configuration changes. The agreed scope names each flow that receives a CAPTCHA stage, typically the login flow, the enrollment flow or both, and states which policy bindings decide when the challenge appears. It also records the provider choice and the reason for it, including whether a self-hostable provider such as Cap, added in authentik 2026.8, fits your data-residency and network rules better than a hosted service. Where the provider calls an external verification endpoint, the scope states which outbound addresses must be reachable from the authentik server and worker containers, so network teams can approve them before the build starts. Your team should confirm the exact provider list against the authentik 2026.8 release notes for your target version.
The reverse proxy in front of authentik is the second scope item. The authentik hardening guide suggests blocking /api/v3/stages/captcha* and /api/v3/managed/blueprints* at the proxy, so that a user or attacker with network access cannot read or replace CAPTCHA settings through the API. DeployOpen plans these rules with your platform team, applies them in your environment, and tests that administrators still reach the settings through the path your team actually uses. The scope also covers JSON verification requests if your chosen provider needs them, including which fields the stage sends and how failures are handled, so that a provider outage does not silently lock out legitimate users.
Testing and handover close the scope. DeployOpen tests the flow with clean sessions, failed challenges, expired challenges and low-reputation clients, and confirms that the blocked API paths return denials from the proxy rather than from authentik. The handover includes the flow and binding configuration exported as blueprints, a short runbook for rotating provider keys, and notes on which settings to review at each authentik upgrade. Everything runs in your cloud accounts, data centers or air-gapped network. Ask any partner for the written scope, the list of flows and proxy paths it covers, and the test cases it will run before you accept a quote.
How DeployOpen delivers and supports authentik flows
DeployOpen approaches CAPTCHA stages in authentik as a scoped, written piece of work inside your own infrastructure. We agree which flows get a challenge, which provider is used, and how the configuration is protected before any build starts, then document and hand over the result.
How we scope
- Confirm which login, enrollment or recovery flows should carry a CAPTCHA stage and which should not.
- Record the CAPTCHA provider choice, including whether a self-hostable option fits your authentik version.
- Agree who may change CAPTCHA settings and how that access is controlled before work starts.
- Engagements are fixed-scope, with deliverables and timelines agreed in writing before work begins.
How we build
- Configure the CAPTCHA stage and bind it to the agreed flows and policies in a test environment first.
- Test the verification request path, including JSON verification requests, and how failures are handled.
- Restrict access to CAPTCHA configuration endpoints at the reverse proxy and confirm the rules work.
- Review the change set with your team before it is promoted to production.
How we hand over
- Document each flow with its CAPTCHA stage, provider, bindings and the reasons for those choices.
- Provide the proxy rules and the steps for reviewing CAPTCHA configuration changes over time.
- Walk your administrators through testing a login and an enrollment after any future change.
- Deliver the written configuration record so your team can operate the stage without us.
How we support
- Retest CAPTCHA flows after authentik upgrades, since release notes can change stage behavior.
- Review security release notices and plan updates ahead of supported version timelines.
- Available as a retainer for ongoing support, upgrades and continuous testing of your flows.
- Confirm support terms and response expectations with DeployOpen in the written scope.
