Deep Dive zur reCAPTCHA Enterprise Assessment API

Wenn Ihre Automatisierung plötzlich auf recaptcha/enterprise.js statt api.js trifft, lautet die Frage meist: Muss ich meine Integration umbauen? Die kurze Antwort ist nein. Aus Solver-Sicht wird reCAPTCHA Enterprise nahezu genauso gelöst wie reCAPTCHA v3 – der Unterschied liegt auf der Serverseite, wo Google zusätzlich zum Score konkrete Risikogründe, Betrugssignale und den Account Defender liefert. Dieser Deep Dive zeigt, wie die Assessment API aufgebaut ist und worauf Sie beim Automatisieren Enterprise-geschützter Seiten achten.

So läuft eine Enterprise-Bewertung ab

Der Ablauf hat zwei Hälften: Der Browser erzeugt ein Token, der Server macht daraus eine bewertete Antwort.

Client-side:

  1. Load reCAPTCHA Enterprise script
  2. Call grecaptcha.enterprise.execute(SITE_KEY, {action: 'LOGIN'})
  3. Receive token
  4. Send token to your backend

Server-side:

  1. Create assessment via Enterprise API
  2. Receive detailed risk analysis
  3. Make access decision based on score + reasons
  4. Optionally annotate the assessment (report fraud/legitimate)

Clientseitige Integration von reCAPTCHA Enterprise

Das JavaScript-SDK einbinden

Das SDK folgt dem Muster von reCAPTCHA v3: Skript laden, im ready-Callback eine action ausführen, Token ans Backend senden.

<script src="https://www.google.com/recaptcha/enterprise.js?render=SITE_KEY"></script>
<script>
    grecaptcha.enterprise.ready(function() {
        grecaptcha.enterprise.execute('SITE_KEY', { action: 'LOGIN' })
            .then(function(token) {
                // Send token to backend
                fetch('/api/verify', {
                    method: 'POST',
                    headers: { 'Content-Type': 'application/json' },
                    body: JSON.stringify({ token: token })
                });
            });
    });
</script>

• Die Skript-URL endet auf .../recaptcha/enterprise.js statt auf .../recaptcha/api.js.
• Das API-Objekt heißt grecaptcha.enterprise statt grecaptcha.
• execute() liefert dasselbe Tokenformat zurück.

reCAPTCHA Enterprise im Seitenquelltext erkennen

Klären Sie zuerst die Variante – der zuverlässigste Marker steht in der Skript-URL.

import requests
import re

def detect_recaptcha_enterprise(url):
    """Detect if a page uses reCAPTCHA Enterprise."""
    html = requests.get(url, timeout=10).text

    indicators = {
        "is_enterprise": False,
        "is_standard": False,
        "site_key": None,
        "actions": [],
    }

    # Enterprise detection
    if "recaptcha/enterprise.js" in html:
        indicators["is_enterprise"] = True
        match = re.search(r"render=([A-Za-z0-9_-]+)", html)
        if match:
            indicators["site_key"] = match.group(1)

    # Standard v3 detection
    elif "recaptcha/api.js?render=" in html:
        indicators["is_standard"] = True
        match = re.search(r"render=([A-Za-z0-9_-]+)", html)
        if match:
            indicators["site_key"] = match.group(1)

    # Extract action names
    actions = re.findall(r"action:\s*['\"](\w+)['\"]", html)
    indicators["actions"] = list(set(actions))

    return indicators

print(detect_recaptcha_enterprise("https://example.com/login"))

Die serverseitige Assessment API

Eine Bewertung erstellen

Diesen Schritt führt der Seitenbetreiber aus, nicht der Solver – er zeigt, welche Felder Google bewertet.

from google.cloud import recaptchaenterprise_v1
from google.cloud.recaptchaenterprise_v1 import Assessment

def create_assessment(project_id, site_key, token, action):
    """Create a reCAPTCHA Enterprise assessment."""
    client = recaptchaenterprise_v1.RecaptchaEnterpriseServiceClient()

    event = recaptchaenterprise_v1.Event()
    event.site_key = site_key
    event.token = token
    event.expected_action = action

    assessment = recaptchaenterprise_v1.Assessment()
    assessment.event = event

    request = recaptchaenterprise_v1.CreateAssessmentRequest()
    request.assessment = assessment
    request.parent = f"projects/{project_id}"

    response = client.create_assessment(request)
    return response

Aufbau der Assessment-Antwort

Die Antwort ist der Mehrwert von Enterprise. Wichtig sind vier Bereiche:

• riskAnalysis mit score und reasons,
• tokenProperties mit Gültigkeit, Hostname und Aktion,
• accountDefenderAssessment mit den Konto-labels,
• event mit siteKey, expectedAction und optional hashedAccountId.

{
    "name": "projects/123456/assessments/abcdef123",
    "event": {
        "token": "...",
        "siteKey": "6Le...",
        "expectedAction": "LOGIN",
        "hashedAccountId": "abc123..."
    },
    "riskAnalysis": {
        "score": 0.9,
        "reasons": [
            "AUTOMATION",
            "TOO_MUCH_TRAFFIC"
        ],
        "extendedVerdictReasons": [
            "BROWSER_ERROR"
        ]
    },
    "tokenProperties": {
        "valid": true,
        "hostname": "example.com",
        "action": "LOGIN",
        "createTime": "2025-01-15T10:30:00Z",
        "invalidReason": ""
    },
    "accountDefenderAssessment": {
        "labels": ["PROFILE_MATCH"]
    }
}

Account Defender: Konten über den Lebenszyklus verfolgen

Der Account Defender bewertet nicht die Anfrage, sondern das Konto dahinter – über Registrierung, Login und Nutzung hinweg. Die Signale kommen als labels.

{
    "accountDefenderAssessment": {
        "labels": [
            "PROFILE_MATCH",
            "SUSPICIOUS_LOGIN_ACTIVITY",
            "SUSPICIOUS_ACCOUNT_CREATION",
            "RELATED_ACCOUNTS_NUMBER_HIGH"
        ]
    }
}

WAF-Integration am Netzwerkrand

reCAPTCHA Enterprise lässt sich mit WAF-Anbietern koppeln und ergänzt CAPTCHA-Abfragen am Netzwerkrand.

Cloudflare WAF

Request arrives at Cloudflare edge
    ↓
Cloudflare WAF rule evaluates request
    ↓
Rule triggers reCAPTCHA Enterprise challenge
    ↓
Client solves CAPTCHA → token returned
    ↓
Cloudflare validates token via Enterprise API
    ↓
If valid + score above threshold → request forwarded to origin

F5 BIG-IP

F5 iRule or policy evaluates request
    ↓
Triggers reCAPTCHA Enterprise challenge page
    ↓
Client solves → token validated server-side
    ↓
F5 forwards or blocks based on assessment score

reCAPTCHA Enterprise in der Automatisierung lösen

Python: Enterprise-Token über CaptchaAI lösen

Enterprise-Token verhalten sich für den Solver identisch zu Standard-Token. Ein Beispiel: Ein Berliner SaaS-Team testet seine Login-Strecke auf einer Hetzner-Staging-Umgebung mit reCAPTCHA Enterprise. Nötig ist nur ein zusätzliches Flag – Übermittlung und Status-Abfrage bleiben gleich.

import requests
import time

API_KEY = "YOUR_API_KEY"

# Enterprise is solved with the same method
# The solver handles the Enterprise variant automatically
submit = requests.post("https://ocr.captchaai.com/in.php", data={
    "key": API_KEY,
    "method": "userrecaptcha",
    "googlekey": "6LcR_RsTAAAAAN_r0GEkGBfq3L7KmU5JbPHJtwNp",
    "pageurl": "https://enterprise-site.com/login",
    "enterprise": 1,  # Flag for Enterprise variant
    "json": 1,
})

task_id = submit.json()["request"]

for _ in range(60):
    time.sleep(5)
    result = requests.get("https://ocr.captchaai.com/res.php", params={
        "key": API_KEY,
        "action": "get",
        "id": task_id,
        "json": 1,
    }).json()

    if result.get("status") == 1:
        token = result["request"]
        print(f"Enterprise token: {token[:50]}...")
        break

Node.js

Dasselbe Muster mit axios; eine Schleife fragt das Ergebnis ab, bis der Status 1 ist.

const axios = require("axios");

async function solveEnterprise(sitekey, pageurl) {
    const API_KEY = "YOUR_API_KEY";

    const { data: submit } = await axios.post(
        "https://ocr.captchaai.com/in.php",
        new URLSearchParams({
            key: API_KEY,
            method: "userrecaptcha",
            googlekey: sitekey,
            pageurl: pageurl,
            enterprise: 1,
            json: 1,
        })
    );

    const taskId = submit.request;

    for (let i = 0; i < 60; i++) {
        await new Promise(r => setTimeout(r, 5000));
        const { data: result } = await axios.get(
            "https://ocr.captchaai.com/res.php",
            { params: { key: API_KEY, action: "get", id: taskId, json: 1 } }
        );

        if (result.status === 1) return result.request;
    }

    throw new Error("Timeout");
}

Enterprise vs. Standard auf einer Zielseite erkennen

Für viele Seiten lohnt eine kompakte Routine, die die Variante direkt aus dem HTML ableitet.

def identify_recaptcha_version(html):
    """Determine which reCAPTCHA version a page uses."""
    if "recaptcha/enterprise.js" in html:
        return "enterprise"
    elif "recaptcha/api.js?render=" in html:
        return "v3"
    elif "g-recaptcha" in html and 'data-size="invisible"' in html:
        return "v2_invisible"
    elif "g-recaptcha" in html:
        return "v2"
    else:
        return "none"

Enterprise und Standard-v3 im Vergleich

Beide liefern einen Score von 0,0 bis 1,0; Enterprise begründet ihn und ergänzt die Betrugs- und Kontoabwehr.

Score-Gründe richtig deuten

Der wichtigste Zugewinn gegenüber v3: Enterprise nennt konkrete Gründe für einen niedrigen Score, im Feld reasons.

Erweiterte Urteilsgründe (extendedVerdictReasons)

Hinweis: Die genaue Score-Auswirkung je Grund veröffentlicht Google nicht; die Werte oben sind Erfahrungswerte und variieren je nach IP-Reputation und Traffic-Muster.

Typische Probleme und Lösungen

Häufige Fragen

Kostet mich das Lösen von reCAPTCHA Enterprise mehr als Standard-reCAPTCHA?

Nein. CaptchaAI rechnet Thread-basiert ab – pro gleichzeitigem Thread, nicht pro Lösung, ohne Aufschlag nach CAPTCHA-Typ. Ein Enterprise-Token kostet damit genauso viel wie ein reCAPTCHA-v3-Token; der Einstieg beginnt bei BASIC (15 $/Monat, 5 Threads).

Welchen action-Wert muss ich übergeben – und warum ist er wichtig?

Den Wert, den die Zielseite in grecaptcha.enterprise.execute(...) verwendet, etwa LOGIN. Passt Ihr action-Parameter nicht zum Wert der Seite, bewertet Google das Token häufig mit einem niedrigen Score – selbst wenn es technisch gültig ist.

Warum bleibt der Score niedrig, obwohl mein Token gültig ist?

Ein gültiges Token und ein hoher Score sind zwei verschiedene Dinge. Der Score speist sich aus Signalen wie IP-Reputation, Anfragevolumen und Verhaltensmustern – sichtbar in den reasons-Feldern, die aber nur der Seitenbetreiber sieht, nicht der Solver.

Unterstützt CaptchaAI sowohl reCAPTCHA v2 Enterprise als auch v3 Enterprise?

Ja. Beide Enterprise-Varianten laufen über dieselbe userrecaptcha-Methode wie ihre Standard-Pendants; Sie ergänzen die Anfrage lediglich um enterprise=1. Ein eigenes Google-Cloud-Konto brauchen Sie dafür nicht – das benötigt nur der Seitenbetreiber.

Fazit

reCAPTCHA Enterprise erweitert das Standard-reCAPTCHA um Risikoanalyse, Score-Gründe, Account Defender und WAF-Integration. Für die Automatisierung ändert sich kaum etwas: Enterprise-Token lösen Sie wie Standard-reCAPTCHA – Sie ergänzen Ihre CaptchaAI-Anfrage um enterprise=1. Ob eine Seite Enterprise nutzt, erkennen Sie an recaptcha/enterprise.js im Quelltext. Entscheidend sind nur das richtige enterprise-Flag und ein passender action-Parameter.

Verwandte Leitfäden

• reCAPTCHA v2 Callback per API lösen
• reCAPTCHA v2 und Turnstile auf derselben Seite
• reCAPTCHA v3 Enterprise per API lösen