INTEGRITY Dokumentace

← Řešení Cloudflare pro boty / bots / reference / bot-verification

Web Bot Auth

Web Bot Auth je metoda ověřování, která využívá kryptografické podpisy v HTTP zprávách k ověření, že požadavek pochází od automatizovaného robota. Web Bot Auth se používá jako metoda ověřování pro ověření boti a agenti.

Vychází z návrhů IETF: návrh directory ↗ který prohledávači umožňuje sdílet jeho veřejné klíče, a návrh protokolu ↗ definující, jak se tyto klíče mají použít k připojení identity prohledávače k požadavkům HTTP.

Tato dokumentace popisuje konkrétní integraci v rámci Cloudflare.

1. Vygenerujte platný podepisovací klíč

Musíte vygenerovat podepisovací klíč, který se použije k ověřování požadavků vašeho robota.

  1. Vygenerujte jedinečný Ed25519 ↗ soukromý klíč k podepisování požadavků. Tento příklad používá OpenSSL ↗ genpkey příkaz:

    openssl genpkey -algorithm ed25519 -out private-key.pem

  2. Extrahujte svůj veřejný klíč.

    openssl pkey -in private-key.pem -pubout -out public-key.pem

  3. Veřejný klíč převeďte do formátu JSON Web Key (JWK) pomocí libovolného nástroje. Tento příklad používá jwker ↗ aplikace pro příkazový řádek.

    go install github.com/jphastings/jwker/cmd/jwker@latest
jwker public-key.pem public-key.jwk

Po provedení těchto kroků máte vygenerovaný soukromý a veřejný klíč a veřejný klíč jste převedli do formátu JWK.

2. Hostujte adresář klíčů

Musíte hostovat adresář klíčů, který vašemu robotovi umožní ověřovat jeho požadavky vůči Cloudflare. Tento adresář by měl odpovídat definici z draft-meunier-http-message-signatures-directory-03 ↗.

  1. Umístěte adresář s klíčem na /.well-known/http-message-signatures-directory (mějte na paměti, že jde o povinný požadavek). Tento adresář klíčů by měl poskytovat sadu JSON Web Key Set (JWKS) obsahující veřejný klíč odvozený z vašeho podepisovacího klíče.

  2. Poskytujte webovou stránku přes HTTPS (nikoli HTTP).

  3. Vypočítejte otisk JWK kódovaný pomocí base64 URL ↗ spojený s vaším veřejným klíčem Ed25519.

  4. Podepište svou odpověď HTTP pomocí specifikace HTTP message signature tak, že ke každému klíči ve svém adresáři klíčů připojíte jeden podpis. Tím zajistíte, že nikdo jiný nemůže váš adresář zkopírovat a pokusit se registrovat vaším jménem. Vaše odpověď musí obsahovat následující hlavičky:

    • Content-Type: Tato hlavička musí mít hodnotu application/http-message-signatures-directory+json.
    • Signature: Vytvořte Signature hlavička ↗ nad vybranými komponentami.
    • Signature-Input: Vytvořte Signature-Input hlavička ↗ nad vybranými komponentami. Hlavička musí splňovat následující požadavky.
      Povinná komponenta / parametr Požadavek
      tag Mělo by se rovnat http-message-signatures-directory.
      keyid JWK Thumbprint odpovídajícího klíče ve vašem adresáři.
      created Mělo by se rovnat Unix časové razítko určující okamžik, kdy vaše aplikace zprávu odeslala.
      expires Mělo by se rovnat Unix časové razítko určující okamžik, od kterého se Cloudflare už nemá pokoušet zprávu ověřit.
      @authority Mělo by se rovnat hodnotě hlavičky Host odeslané v požadavku. Měli byste nastavit req parametr komponenty ↗.

    Následující příklad ukazuje anotovaný požadavek a odpověď s povinnými hlavičkami vůči https://example.com. Hodnota Signature zde slouží pouze pro ilustraci a nejedná se o skutečně vygenerovaný podpis.

    GET /.well-known/http-message-signatures-directory HTTP/1.1
Host: example.com
Accept: application/http-message-signatures-directory+json

HTTP/1.1 200 OK
Content-Type: application/http-message-signatures-directory+json
Signature: sig1=:TD5arhV1ved6xtx63cUIFCMONT248cpDeVUAljLgkdozbjMNpJGr/WAx4PzHj+WeG0xMHQF1BOdFLDsfjdjvBA==:
Signature-Input: sig1=("@authority";req);alg="ed25519";keyid="poqkLGiymh_W0uP6PZFw-dvez3QJT5SolqXBCW38r0U";nonce="ZO3/XMEZjrvSnLtAP9M7jK0WGQf3J+pbmQRUpKDhF9/jsNCWqUh2sq+TH4WTX3/GpNoSZUa8eNWMKqxWp2/c2g==";tag="http-message-signatures-directory";created=1750105829;expires=1750105839
Cache-Control: max-age=86400
{
  "keys": [{
    "kty": "OKP",
    "crv": "Ed25519",
    "x": "JrQLj5P_89iXES9-vFgrIy29clF9CC_oPPsw3c5D0bs", // Base64 URL-encoded public key, with no padding
  }]
}

Můžete použít společností Cloudflare vyvinutý http-signature-directory nástroj CLI ↗ k ověření vašeho adresáře.

3. Zaregistrujte svého bota a adresář klíčů

Abyste svého robota přidali na seznam ověřených robotů, musíte ho zaregistrovat spolu s jeho adresářem klíčů.

  1. Přihlaste se do Cloudflare dashboard ↗, a vyberte svůj účet a doménu.
  2. Přejděte na Manage Account > Konfigurace.
  3. Přejděte na Bot Submission Form kartě.
  4. Pro Metoda ověření: vyberte Signatura požadavku.
  5. Pro Pokyny k ověření: zadejte URL adresu vašeho adresáře klíčů. Volitelně můžete uvést hodnoty User Agents (a jejich vzory shody), které bude váš bot odesílat.
  6. Vyberte Odeslat.

Cloudflare přijímá všechny platné klíče Ed25519, které najde ve vašem adresáři klíčů. Pokud v registrované databázi Cloudflare daný klíč již existuje, Cloudflare s vámi zajistí dodání nového klíče, nebo rotaci toho stávajícího.

Po úspěšné verifikaci budete moci odesílat verifikované požadavky.

4. (Po ověření) Podepisujte své požadavky

Jakmile je váš bot úspěšně verifikován, je připraven podepisovat své požadavky. Protokol podpisu je definován v draft-meunier-web-bot-auth-architecture-02 ↗

4.1. Vyberte sadu komponent k podpisu

Vyberte sadu komponent k podepsání.

Komponentou je buď hlavička HTTP, nebo libovolný odvozené komponenty ↗ ve specifikaci HTTP Message Signatures. Cloudflare doporučuje následující:

4.2. Vypočítejte otisk JWK (thumbprint)

Vypočítejte otisk JWK kódovaný pomocí base64 URL ↗ z veřejného klíče, který jste zaregistrovali u Cloudflare.

4.3. Sestavte požadované hlavičky

Sestavte tři požadované hlavičky pro Web Bot Auth.

Signature-Input hlavička

Sestavte Signature-Input hlavička ↗ nad vybranými komponentami. Hlavička musí splňovat následující požadavky.

Povinný parametr komponenty Požadavek
tag Mělo by se rovnat web-bot-auth.
keyid Mělo by se rovnat thumbprintu vypočítanému v kroku 2.
created Mělo by se rovnat Unix časové razítko určující okamžik, kdy vaše aplikace zprávu odeslala.
expires Mělo by se rovnat Unix časové razítko určující okamžik, od kterého se Cloudflare už nemá pokoušet zprávu ověřit. Krátké expires snižuje pravděpodobnost útoků typu replay a Cloudflare doporučuje volit vhodné krátké intervaly platnosti.

Signature hlavička

Sestavte Signature hlavička ↗ nad vybranými komponentami.

Signature-Agent hlavička

Sestavte Signature-Agent hlavička ↗ která odkazuje na váš adresář klíčů. Cloudflare implementuje Signature-Agent formát z draft-meunier-http-message-signatures-directory-03, kde je hodnota hlavičky strukturovaný řetězec, například "https://signature-agent.test".

Cloudflare zprávu neověří, pokud:

4.4. Přidejte hlavičky do požadavků svého bota

Připojte k požadavkům svého bota tyto tři hlavičky.

Příklad požadavku může vypadat takto:

Signature-Agent: "https://signature-agent.test"
Signature-Input: sig2=("@authority" "signature-agent")
 ;created=1735689600
 ;keyid="poqkLGiymh_W0uP6PZFw-dvez3QJT5SolqXBCW38r0U"
 ;alg="ed25519"
 ;expires=1735693200
 ;nonce="e8N7S2MFd/qrd6T2R3tdfAuuANngKI7LFtKYI/vowzk4lAZYadIX6wW25MwG7DCT9RUKAJ0qVkU0mEeLElW1qg=="
 ;tag="web-bot-auth"
Signature: sig2=:jdq0SqOwHdyHr9+r5jw3iYZH6aNGKijYp/EstF4RQTQdi5N5YYKrD+mCT1HA1nZDsi6nJKuHxUi/5Syp3rLWBA==:

Tranzitivní důvěra a Forwarded hlavička

Agent, který se dostane na váš web, často neprovozuje společnost, jež ho vytvořila. Platforma může spouštět automatizace jménem mnoha různých koncových uživatelů, takže provozovatel a koncový uživatel nejsou stejná strana. Cloudflare tento řetězec (vlastník webu → provozovatel bota → koncový uživatel) označuje jako tranzitivní důvěra.

Aby bylo možné identitu operátora přenášet napříč tímto řetězcem, Cloudflare experimentuje s Forwarded hlavičku definovanou v RFC 7239 ↗. Funguje to podobně jako X-Forwarded-For dělá pro IP adresy: preference povolit platí pro provozovatele bez ohledu na to, zda k vám přistupuje přímo, nebo přes zprostředkovatele, kterým Cloudflare důvěřuje.

Operátor se identifikuje pomocí for parametr:

Forwarded: for="openai"

Hlavička může nést také content-use hodnotu, ke které se operátor zavazuje u obsahu, k němuž přistupuje:

Forwarded: for="openai";use="reference"

Omezení

Implementace Web Bot Auth od Cloudflare nepodporuje všechny komponenty a parametry definované v IETF RFC 9421. Pokud do hlavičky Signature-Input vaší žádosti zahrnete některou z následujících položek, ověření selže.

Následující parametry komponent definované v IETF RFC 9421 nejsou podporované, a pokud budou ve zprávě obsaženy, Cloudflare se ji nepodaří ověřit:

Řešení potíží

Neúspěšné ověření zprávy

Pokud vaše zpráva neprochází ověřením, může to mít následující příčiny:

Použijte HTTP message signatures / Web Bot Auth v zóně bez ověřování Cloudflare

Pokud chcete používat HTTP Message Signatures (Web Bot Auth) pro vlastní zpracování na origin serveru a nechcete, aby do procesu zasahovalo nebo pole doplňovalo ověřování Cloudflare cf.bot_management.verified_bot pole můžete požádat o deaktivaci funkce ověřování Cloudflare pro vaši zónu.

Chcete-li deaktivovat ověřování Web Bot Auth, kontaktujte Cloudflare Support.

Vypnutím této funkce Cloudflare přestane ověřovat příchozí podpisy. Verified bots se poté při určování legitimity provozu spolehnou na jiné metody, například na reverzní ověření DNS.

Další zdroje

Můžete využít následující zdroje.