Validar Token (Con Clave Privada)
Validar Token de Éxito de MTCaptcha
Un Verified-Token se creará una vez que un usuario sea verificado mediante captcha. Este token debe verificarse en el servidor utilizando la PrivateKey correspondiente para asegurar su validez. El método estándar es usar la CheckToken API, pero para casos más personalizados y sensibles a la red, el token también puede descifrarse directamente en el lado del servidor.
Obtener el Token
Este Verified-Token se puede encontrar comúnmente a través de:
- Campo oculto en el formulario HTML con el nombre
mtcaptcha-verifiedtoken:
<input type='hidden' name='mtcaptcha-verifiedtoken' … />
También se puede obtener mediante:
- Método de JavaScript
mtcaptcha.getVerifiedToken()
- Parte del argumento de devolución de llamada de estado a través de verified-callback (consulta Callbacks de JS para más detalles)
function mtcaptchaVerifiedCallback( status ) {
console.log( status.verifiedToken );
}
console.log( status.verifiedToken ); }
Restricciones del Token
Cada verifiedToken normalmente es válido por unos pocos minutos y solo puede verificarse una vez mediante la API CheckToken para evitar ataques de repetición.
Después de obtener el verifiedToken, debes verificarlo dentro del límite de tiempo para asegurarte de que el token siga siendo válido. El widget de JavaScript de MTCaptcha garantizará que haya al menos 50 segundos disponibles para que el servidor lo verifique.
API CHECKTOKEN
Método HTTP: GET
Parámetros:
- privatekey : La clave privada compartida entre tu servidor y MTCaptcha. (Obligatorio)
- token : La cadena del VerifiedToken. (Obligatorio)
Ejemplo : https://service.mtcaptcha.com/mtcv1/api/checktoken?privatekey=&token=
Nota : Para garantizar que la clave privada se mantenga en secreto, esta API solo debe ser llamada desde el lado del servidor.
Para entornos del lado del servidor que requieren ACLs de firewall explícitas para tráfico saliente, usa: service2.mtcaptcha.com — URL de la API de dominio que permite direcciones IP explícitas.
URL: https://service2.mtcaptcha.com/mtcv1/api/checktoken
Las IP que en la lista blanca son:
- 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
Respuesta de la API CHECKTOKEN
La respuesta de la API es un objeto JSON, ejemplos de respuestas a continuación
{
"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"
}
}
Ejemplo de respuesta fallida
{
"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"
}
}
Campos de respuesta de la API CHECKTOKEN
| Campo | Descripción |
|---|---|
| success | true si el token es válido. false en caso contrario. |
| fail_codes | El código (razón) del fallo de validación. Este campo solo existirá si success: false. |
| tokeninfo | Objeto JSON con los metadatos del token desencriptados. Este campo puede no existir en ciertos fallos. |
| tokeninfo.v | La versión del formato del token, debe ser "1.0". |
| tokeninfo.code | El código del token que describe el método de verificación. Para una lista completa de posibles códigos, ver más abajo. |
| tokeninfo.codeDesc | La descripción del código del token. Para una lista completa de códigos y descripciones posibles, ver más abajo. |
| tokeninfo.tokID | El GUID único del token, codificado en Hex/Base16 de 128 bits. |
| tokeninfo.timestampSec | La marca de tiempo cuando se creó el token, en tiempo Unix epoch (en segundos). |
| tokeninfo.timestampISO | La marca de tiempo cuando se creó el token, en formato ISO 8601 UTC. |
| tokeninfo.hostname | El nombre de host de la página web donde se sirvió el captcha. |
| tokeninfo.isDevHost | true si el nombre de host coincide con los "dominios de desarrollo" configurados para el sitio. |
| tokeninfo.action | La cadena de acción usada en la inicialización del captcha. Si no está definida, por defecto es una cadena vacía. |
| tokeninfo.ip | La IP del cliente del usuario. En formato de cadena. |
Códigos y descripciones de la información del token de respuesta
Los códigos para tokeninfo.code y tokeninfo.codeDesc se enumeran a continuación:
| Códigos de Token | Descripción del Código | Descripción |
|---|---|---|
| 201 | valid:captcha-solved | Verificado porque el desafío del captcha fue resuelto. |
| 211 | valid:ip-whitelisted | Verificado porque el cliente proviene de una IP incluida en la lista blanca del sitio. |
| 212 | valid:low-friction | Verificado porque el cliente fue considerado de bajo riesgo y el sitio tiene captcha invisible de baja fricción habilitado. |
| 301 | valid-test:captcha-solved-via-testkey | Verificado mediante TestKey (para pruebas automatizadas). |
Códigos de fallo de la respuesta
Posibles fail_codes de respuesta
| Códigos de Falla | Descripción |
|---|---|
| token-expired | El token ha expirado. Comúnmente 120 segundos, puede ser más según el tipo de captcha. |
| token-duplicate-cal | El token ya fue verificado y por lo tanto no debe usarse nuevamente. |
| bad-request | Error general por solicitudes inesperadas o malformadas. |
| missing-input-privatekey | Falta el parámetro privatekey. |
| missing-input-token | Falta el parámetro token. |
| invalid-privatekey | El privatekey proporcionado no es válido. |
| invalid-token | El token no es válido. |
| invalid-token-faildecrypt | El token no es válido y falló durante la desencriptación. |
| privatekey-mismatch-token | El token y el privatekey no coinciden, es decir, el token fue creado desde otro sitekey. |
| expired-sitekey-or-account | El sitekey/privatekey ya no es válido por vencimiento o cierre de cuenta. |
Parámetros opcionales de la API CHECKTOKEN
Para casos de uso personalizados, la API CheckToken admite estos parámetros opcionales.
| Parámetro | Descripción del Parámetro |
|---|---|
| tokenExpireMiniSec | Establece el tiempo mínimo de expiración (TTL) en segundos para el token verificado, lo que permite que el token sea válido por más tiempo que el valor predeterminado de 60–120 segundos. Esta duración personalizada solo se aplicará si es mayor que el tiempo de expiración predeterminado de MTCaptcha. El valor debe ser un número entero y el máximo permitido es 1200 (20 minutos). Ejemplo: tokenExpireMiniSec=300. |
| tokenDuplicateCallMaxCount | Establece el umbral de llamadas duplicadas desde el valor predeterminado de una (1) llamada CheckToken por token a múltiples. El valor debe ser un número entero y el máximo permitido es 20. Ejemplo: tokenDuplicateCallMaxCount=5. |
El uso de estos parámetros opcionales agregará los campos token_callcount y token_agesec a la respuesta de la API CheckToken.
{
"success": ...,
"token_callcount": 3,
"token_agesec": 9,
"tokeninfo": {
...
}
}
CHECKTOKEN mediante Desencriptado en el Servidor (Sin Llamada a API Externa)
El método estándar y más sencillo para validar el verifiedToken de MTCaptcha es mediante la API de checktoken, pero también puedes desencriptar y decodificar el token directamente en el servidor sin hacer llamadas externas a mtcaptcha.com.
Necesitarás la PrivateKey del sitio y la capacidad de calcular el hash MD5 y desencriptar con el cifrado AES. En el servidor deberán aplicarse verificaciones adicionales de tiempo de expiración y uso único para garantizar la seguridad adecuada.
Código de Ejemplo de Desencriptado
El código de ejemplo en Java para desencriptar y decodificar el token se puede encontrar en el proyecto de GitHub aquí:
https://github.com/mtcaptcha-public/MTCaptcha-Direct-Token-Decryption/
Estructura de la Cadena Verified-Token
"v1([Checksum de MTCaptcha], [Checksum del Cliente], [Sitekey], [Semilla Aleatoria], [TokenInfo Encriptado])"
Ejemplo:
v1(2f03cc7d,1058dfde,MTPublic-hal9000uJ,34715559cd42d3955114303c925c3582,kSdkIYA.....qOCQ**)
PARTES DEL TOKEN
| PARTE DEL TOKEN | VALOR DE EJEMPLO |
|---|---|
| [MTCaptcha CheckSum] | 2f03cc7d |
| [Customer Checksum] | 1058dfde |
| [Sitekey] | MTPublic-hal9000uJ |
| [Random Seed] | 34715559cd42d3955114303c925c3582 |
| [Encrypted TokenInfo] | kSdkIYA.....qOCQ** |
LÓGICA DE DESENCRIPTADO DEL TOKEN VERIFICADO
| PASO | LÓGICA |
|---|---|
| [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