hCaptcha

Please use caution when referencing concepts or code contained in the private https://docs.hcaptcha.com/enterprise documentation.

Wikimedia uses hCaptcha Enterprise's First-Party feature, which routes all client traffic through a Wikimedia controlled proxy.

Design

https://docs.hcaptcha.com/#quick-start

Client Side

We load hCaptcha JS through a reverse proxy on first form interaction with Special:CreateAccount.

Hcaptcha wmf design

Server side

CDN → Load Balancer→ reverse proxy → hcaptcha upstream ("the internet")

• proxoid.discovery.wmnet (active/active service)
• The reverse proxy is a basic nginx installation Currently (Sept 2025) the proxy is installed on the url_downloader hosts.

Key features

• Forwards requests to hCaptcha
• Strips any identifying information by unsetting various headers
• Hashes client IP address, <%= @nginx_ipblinding_conf %> blocks in NginX-'s (see below)

Configuration

On https://dashboard.hcaptcha.com, we have a sitekey defined for production wikis.

This sitekey is defined in:

• PrivateSettings.php in operations/mediawiki-config
• Puppet private configuration for the hCaptcha reverse proxy.

mediawiki-config

To enable/disable this functionality, toggle wmgEnableHCaptcha in wmf-config/InitialiseSettings.php. Here is an example patch to do this: I80886c

Puppet

• modules/profile/manifests/hcaptcha/proxy.pp
• modules/profile/templates/hcaptcha/nginx.conf.erb
• modules/profile/templates/hcaptcha/proxy.nginx.conf.erb
• modules/profile/templates/hcaptcha/subdomain.nginx.conf.erb
• modules/role/manifests/url_downloader.pp
• hieradata/common/profile/hcaptcha/proxy.yaml
• Puppet privare IP blinding configuration
• Puppet private configuration for the hCaptcha reverse proxy

Cookies

The proxy removes all cookies except hmt_id, per Idb012f and I87190f.

Monitoring

• Grafana
• Superset

Runbook

In case of emergency, please disable this functionality, by toggling wmgEnableHCaptcha in wmf-config/InitialiseSettings.php. Here is an example patch to do this: I80886c

Contact information

The hCaptcha integration with on-wiki workflows is managed by the Product Safety and Integrity team as part of the WE4.2 anti-abuse signals hCaptcha project.

The proxy infrastructure is managed by Traffic SRE and ServiceOps SRE.