Ruby

Das Gem eu_captcha prüft das Token auf dem Server. Es kommt ohne weitere Abhängigkeiten aus und verwendet net/http aus der Standardbibliothek von Ruby.

Voraussetzungen

Die folgenden Voraussetzungen sind erfüllt:

Voraussetzung	Wert
Ruby	ab Version 2.7
Zugangsdaten	Öffentlicher Sitekey und Secret aus der Ansicht Details

Gem installieren

Installieren Sie das Gem:

gem install eu_captcha

Alternativ ergänzen Sie die Datei Gemfile:

gem 'eu_captcha'

Widget einbinden

Ergänzen Sie jede Seite mit einem zu schützenden Formular um den Skript-Verweis:

<script src="https://cdn.eu-captcha.eu/verify.js" async defer></script>

Fügen Sie das Widget in das Formular ein:

<div class="eu-captcha" data-sitekey="EUCAPTCHA_SITE_KEY"></div>

Hinweis

Bei einer Single-Page-Anwendung mit React, Vue oder Angular binden Sie das Widget über das jeweilige npm-Paket ein. Das Gem übernimmt dann allein die serverseitige Prüfung.

Token prüfen

Prüfen Sie das übermittelte Token auf dem Server:

require 'eu_captcha'

captcha = EuCaptcha::Client.new(
  sitekey: ENV['EUCAPTCHA_SITE_KEY'],
  secret:  ENV['EUCAPTCHA_SECRET_KEY']
)

result = captcha.validate(
  token:       params['eu-captcha-response'],
  remote_addr: request.ip
)

render_error unless result.success?

Optionen

Die folgenden Optionen übergeben Sie als Schlüsselwortargumente an den Konstruktor:

Option	Typ	Vorgabe	Wirkung
sitekey	String	—	Öffentlicher Sitekey. Der Wert ist erforderlich.
secret	String	—	Geheimer Schlüssel. Der Wert ist erforderlich und darf nicht im Browser erscheinen.
fail_default	Boolean	true	Rückgabewert für den Netzwerk- und den Token-Zustand, wenn die API nicht erreichbar ist. true lässt die Absendung zu, false weist sie ab.
check_cdn_headers	Boolean	true	Ermittelt die IP-Adresse des Besuchers aus den Kopfzeilen HTTP_CLIENT_IP, HTTP_X_FORWARDED_FOR und HTTP_X_REAL_IP der Rack-Umgebung, bevor REMOTE_ADDR verwendet wird.
verify_url	String	Adresse der Produktivumgebung	Überschreibt die Adresse des Endpunkts /verify. Verwenden Sie die Option für Tests.
credentials_url	String	Adresse der Produktivumgebung	Überschreibt die Adresse des Endpunkts /verify-credentials.

Das Ergebnisobjekt

validate gibt ein Objekt EuCaptcha::Result mit den folgenden Methoden zurück:

Methode	Rückgabe
success?	true, wenn die API erreichbar war und das Token gültig ist.
success_network?	true, wenn der Aufruf der API ohne Netzwerk- oder Übertragungsfehler abgeschlossen wurde.
success_token?	true, wenn die API das übermittelte Token als gültig gemeldet hat.
train	true, false oder nil.

Die getrennte Abfrage unterscheidet eine nicht bestandene Challenge von einer Störung der API:

result = captcha.validate(token: params['eu-captcha-response'], remote_addr: request.ip)

unless result.success_network?
  # Could not reach the API — consider logging or alerting
end

unless result.success_token?
  # Token was rejected — the submission is likely automated
end

Achtung

train gibt true zurück, wenn die API die eigentliche Prüfung übersprungen und ein positives Ergebnis erzwungen hat. Das geschieht nur, wenn der Schutz des Sitekeys abgeschaltet ist. Bei einem unbekannten Sitekey oder einem falschen Secret meldet die API success: false. success? wertet dieses Kennzeichen bereits aus und gibt in diesem Fall false zurück. Bei einem Netzwerkfehler gibt train den Wert nil zurück.

Zugangsdaten prüfen

Mit verify_credentials prüfen Sie Sitekey und Secret ohne ein Token des Browsers, zum Beispiel beim Start der Anwendung:

captcha = EuCaptcha::Client.new(
  sitekey: ENV['EUCAPTCHA_SITE_KEY'],
  secret:  ENV['EUCAPTCHA_SECRET_KEY']
)

unless captcha.verify_credentials
  # Credentials are invalid or the API is unreachable — log and alert
end

Bei einem Netzwerk- oder API-Fehler gibt die Methode false zurück und löst keine Ausnahme aus.

Siehe Endpunkt /verify-credentials.

Ruby on Rails

Legen Sie die Zugangsdaten in config/credentials.yml.enc ab und erzeugen Sie den Client in einer Initialisierungsdatei.

Datei config/initializers/eu_captcha.rb:

EU_CAPTCHA = EuCaptcha::Client.new(
  sitekey: Rails.application.credentials.dig(:eucaptcha, :sitekey),
  secret:  Rails.application.credentials.dig(:eucaptcha, :secret)
)

Prüfen Sie das Token im Controller:

class ContactController < ApplicationController
  def create
    result = EU_CAPTCHA.validate(
      token:       params['eu-captcha-response'],
      remote_addr: request.ip,
      user_agent:  request.user_agent
    )

    unless result.success?
      render json: { error: 'CAPTCHA verification failed' }, status: :unprocessable_entity
      return
    end

    # process the form...
  end
end

request.ip beachtet die Einstellung der vertrauenswürdigen vorgelagerten Systeme von Rails.

Sinatra und Rack

Übergeben Sie die Rack-Umgebung, damit das Gem die IP-Adresse und die Kennung des Browsers selbst ermittelt:

require 'sinatra'
require 'eu_captcha'

CAPTCHA = EuCaptcha::Client.new(
  sitekey: ENV['EUCAPTCHA_SITE_KEY'],
  secret:  ENV['EUCAPTCHA_SECRET_KEY']
)

post '/contact' do
  result = CAPTCHA.validate(
    token:    params['eu-captcha-response'],
    rack_env: env
  )

  halt 422, 'CAPTCHA verification failed' unless result.success?

  # process the form...
end

Bei einer übergebenen Rack-Umgebung beachtet validate die Einstellung check_cdn_headers.

Vollständiges Beispiel

Siehe Svelte und Ruby.