Token validieren (mit privatem Schlüssel)
MTCaptcha-Erfolgstoken validieren
Sobald ein Benutzer per Captcha verifiziert wurde, wird ein Verified-Token erstellt. Dieses Token muss serverseitig mit dem entsprechenden PrivateKey auf seine Gültigkeit überprüft werden. Standardmäßig wird die CheckToken-API verwendet. Für individuellere und netzwerksensitivere Anwendungsfälle kann das Token jedoch auch direkt serverseitig entschlüsselt werden.
Den Token erhalten
Dieses Verified-Token findet man üblicherweise über:
- HTML hidden input form with name
mtcaptcha-verifiedtoken:
<input type='hidden' name='mtcaptcha-verifiedtoken' … />
und ist auch zu finden über
- Javascript method
mtcaptcha.getVerifiedToken()
- Teil des status callback arguments über verified-callback (see JS Callbacks for more details)
function mtcaptchaVerifiedCallback( status ) {
console.log( status.verifiedToken );
}
console.log( status.verifiedToken ); }
Token-Einschränkungen
Jeder verifizierte Token ist in der Regel einige Minuten gültig und kann nur einmal über die CheckToken-API verifiziert werden, um Replay-Angriffe zu verhindern.
Nach Erhalt des verifizierten Tokens müssen Sie ihn innerhalb der Frist überprüfen, um sicherzustellen, dass er noch gültig ist. Das MTCaptcha-JavaScript-Widget stellt sicher, dass dem Server mindestens 50 Sekunden für die Verifizierung zur Verfügung stehen.
CHECKTOKEN API
HTTP METHOD: GET
Parameters:
- privatekey : Das gemeinsame PrivateKey-Geheimnis zwischen Ihrem Server und MTCaptcha. (Erforderlich)
- token : Die VerifiedToken string. (Erforderlich)
eg : https://service.mtcaptcha.com/mtcv1/api/checktoken?privatekey=&token=
NOTE : Um sicherzustellen, dass der private Schlüssel geheim bleibt, sollte diese API nur von der Serverseite aufgerufen werden.
Informationen zu serverseitigen Umgebungen, die explizite Firewall-ACLs für ausgehenden Datenverkehr erfordern, finden Sie unter: Verwenden Sie die unten stehende Domänen-API-URL service2.mtcaptcha.com, die explizite IP-Adressen ermöglicht. URL: https://service2.mtcaptcha.com/mtcv1/api/checktoken
The IPs to white list are:
- 52.214.217.96
- 35.165.137.56
- 13.228.176.242
- 13.234.26.164
- 18.228.103.117
- 18.162.183.0
- 47.52.173.54
- 8.210.253.57
CHECKTOKEN API-Antwort
Die API response ist ein JSON objekt, Beispielantworten unten
{
"success": true,
"tokeninfo": {
"v": "1.0",
"code": 201,
"codeDesc": "valid:captcha-solved",
"tokID": "ae1e60a1e249c217cb7b05c4dba8dd0d",
"timestampSec": 1552185983,
"timestampISO": "2019-03-10T02:46:23Z",
"hostname": "some.example.com",
"isDevHost": false,
"action": "",
"ip": "10.10.10.10"
}
}
Beispiel für eine Fehlerreaktion
{
"success": false,
"fail_codes": [
"token-expired"
],
"tokeninfo": {
"v": "1.0",
"code": 201,
"codeDesc": "valid:captcha-solved",
"tokID": "25eff0c56a227781408a95a053c36b65",
"timestampSec": 1552185729,
"timestampISO": "2019-03-10T02:42:09Z",
"hostname": "some.example.com",
"isDevHost": false,
"action": "",
"ip": "10.10.10.10"
}
}
CHECKTOKEN-API-Antwortfelder
| Field | Description |
|---|---|
| success | true, wenn das Token gültig ist. Andernfalls false. |
| fail_codes | Der Code (Grund) für den Validierungsfehler. Dieses Feld ist nur vorhanden, wenn success: false angegeben ist. |
| tokeninfo | JSON objekt mit den entschlüsselten Token-Metadaten. Dieses Feld ist bei bestimmten Fehlern möglicherweise nicht vorhanden. |
| tokeninfo.v | Die Version des Token-Formats sollte "1.0" sein. |
| tokeninfo.code | Der Tokencode beschreibt die Verifizierungsmethode. Eine vollständige Liste der möglichen Tokencodes finden Sie unten. |
| tokeninfo.codeDesc | Die Tokencode-Beschreibung. Eine vollständige Liste der möglichen Codes und Beschreibungen finden Sie weiter unten. |
| tokeninfo.tokID | Die eindeutige GUID für das Token, 128 Bit Hex/Base16-codiert. |
| tokeninfo.timestampSec | Der Zeitstempel der Token-Erstellung in Unix-Epochenzeit (in Sekunden). |
| tokeninfo.timestampISO | Der Zeitstempel der Token-Erstellung im UTC-Format ISO 8601. |
| tokeninfo.hostname | Der Hostname der Webseite, unter der das Captcha bereitgestellt wurde. |
| tokeninfo.isDevHost | true, wenn der Hostname mit den für die Site konfigurierten Entwicklungsdomänen übereinstimmt. |
| Tokeninfo.action | Tokeninfo.action Die Aktionszeichenfolge, die bei der Initialisierung des Captchas verwendet wird. Wenn nicht definiert, wird standardmäßig eine leere Zeichenfolge verwendet. |
| tokeninfo.ip | Die Client-IP des Benutzers. Im String-Format. |
Antwort-Token-Infocodes und -Beschreibungen
The codes for tokeninfo.code and tokeninfo.codeDesc are listed below:
| Token Codes | Code Description | Description |
|---|---|---|
| 201 | valid:captcha-solved | Überprüft, ob die Captcha Herausforderung gelöst wurde. |
| 211 | valid:ip-whitelisted | Überprüft über den Client, der von einer IP kommt, die mit der IP-Whitelist für die Site übereinstimmt. |
| 212 | valid:low-friction | Verifiziert durch den Client, der als risikoarm eingestuft wird, und die Site hat ein reibungsarmes unsichtbares Captcha aktiviert. |
| 301 | valid-test:captcha-solved-via-testkey | Verifiziert über den TestKey (für automatisierte Tests). |
Antwortfehlercodes
Possible response fail_codes
| Fail Codes | Description |
|---|---|
| token-expired | Das Token ist abgelaufen. Normalerweise 120 Sekunden. Kann je nach Captcha Typ länger sein. |
| token-duplicate-cal | Das Token wurde bereits überprüft und sollte daher nicht verwendet werden. |
| bad-request | Allgemeiner Fehler bei unerwarteten fehlerhaften/fehlerhaften Anfragen. |
| missing-input-privatekey | Der Parameter privatekey fehlt |
| missing-input-token | Der Parameter token fehlt |
| invalid-privatekey | Der angegebene private Schlüssel ist ungültig |
| invalid-token | Das Token ist ungültig |
| invalid-token-faildecrypt | Das Token ist ungültig und die Entschlüsselung ist fehlgeschlagen |
| privatekey-mismatch-token | TDas Token und der private Schlüssel stimmen nicht überein. Das heißt, das Token wurde aus einem anderen Sitekey erstellt. |
| expired-sitekey-or-account | Der Sitekey/Privatekey ist aufgrund eines Ablaufs oder einer Kontoschließung nicht mehr gültig. |
Optionale Parameter der CHECKTOKEN-API
For custom use cases, the CheckToken API supports these optional parameters.
| Parameter | Parameter Description |
|---|---|
| tokenExpireMiniSec | Legt die minimale Ablaufzeit (TTL) in Sekunden für das verifizierte Token fest. Dadurch ist das Token effektiv länger als die standardmäßigen 60–120 Sekunden gültig. Diese benutzerdefinierte Ablaufzeit wird nur angewendet, wenn sie länger als die standardmäßige MTCaptcha-Ablaufzeit ist. Der Wert muss eine Ganzzahl sein und darf maximal 1200 (20 Minuten) betragen. Beispiel: tokenExpireMiniSec=300. |
| tokenDuplicateCallMaxCount | Setzt den Schwellenwert für doppelte Aufrufe von einem (einen) CheckToken-Aufruf pro Token auf mehrere. Der Wert muss eine Ganzzahl sein und darf maximal 20 betragen. Beispiel: tokenDuplicateCallMaxCount=5. |
Die Verwendung dieser optionalen Parameter fügt der CheckToken-API-Antwort die Felder token_callcount und token_agesec hinzu.
{
"success": ...,
"token_callcount": 3,
"token_agesec": 9,
"tokeninfo": {
...
}
}
CHECKTOKEN via Server Side Decryption (Without External API Call)
Die standardmäßige und einfachste Methode zur Validierung des MTCaptcha verifiedToken erfolgt über die Checktoken-API. Sie können das Token jedoch auch direkt serverseitig entschlüsseln und dekodieren, ohne externe API-Aufrufe an mtcaptcha.com zu senden. Sie benötigen den PrivateKey der Site und die Fähigkeit, den MD5-Hash zu berechnen und mit AES-Verschlüsselung zu entschlüsseln. Zusätzliche Prüfungen auf Timeout und einmalige Verwendung sind serverseitig erforderlich, um die Sicherheit zu gewährleisten.
Beispielcode entschlüsseln
Den Beispiel Java Code zum Entschlüsseln und Dekodieren des Tokens finden Sie hier im GitHub-Projekt.:
https://github.com/mtcaptcha-public/MTCaptcha-Direct-Token-Decryption/
Verified-Token-String-Struktur
"v1([MTCaptcha CheckSum], [Customer Checksum], [Sitekey], [Random Seed], [Encrypted TokenInfo])"
Example: v1(2f03cc7d,1058dfde,MTPublic-hal9000uJ,34715559cd42d3955114303c925c3582,kSdkIYA.....qOCQ**)
Token-Teile
| Token Part | Example Value |
|---|---|
| [MTCaptcha CheckSum] | 2f03cc7d |
| [Customer Checksum] | 1058dfde |
| [Sitekey] | MTPublic-hal9000uJ |
| [Random Seed] | 34715559cd42d3955114303c925c3582 |
| [Encrypted TokenInfo] | kSdkIYA.....qOCQ** |
Verifizierte Token-Entschlüsselungslogik
| Step | Logic |
|---|---|
| [CalculatedCustomerCheckSum] | = MD5([Privatekey] + [SiteKey] + [Random Seed] + [Encrypted TokenInfo]).toHexLowercase().substring(0, 8) |
| [EncryptedTokenInfoBinary] | = URLSafeBase64.decode([Encrypted TokenInfo].replace("*", "=")); |
| [SingleUseDecryptionKey128bit] | = MD5([Privatekey] + [Random Seed]); |
| [AesIV] | = [SingleUseDecryptionKey128bit] |
| [DecryptedTokenInfoJson] | = AES.decrypt("CBC/PKCS5Padding", [SingleUseDecryptionKey128bit], [AesIV], [EncryptedTokenInfoBinary]); |
Textual Encoding / Decoding Format: UTF-8