Ayuda

¿Cómo puedo utilizar Tractis Verifications?

Tractis Identity te ofrece la posibilidad de verificar la identidad de tus usuarios mediante DNI electrónico y otros certificados electrónicos. Estas verificaciones pueden utilizarse como pasarelas de autenticación fuerte para ofrecer login con certificados a tus usuarios o creando verificaciones de identidad públicas para mostrar perfiles de usuarios certificados en tu web.

Para poder usar este servicio previamente debes obtener una API Key de una Verificación de Identidad.

Una vez dispongamos de la API Key la integración consta de dos partes:

  1. Crear un formulario HTML para acceder a la pasarela
  2. Verificación de los datos recogidos por la pasarela

Creación del formulario HTML

El formulario HTML es muy sencillo. Se compone de la siguiente forma:


<form method="post" action="https://www.tractis.com/verifications">
<input type="hidden" value="IDENTIFICADOR_DE_TU_API_KEY" name="api_key"/>
<input type="hidden" value="URL_DONDE_DEBE_VOLVER_EL_USUARIO" name="notification_callback"/>
<input type="submit" value="Hacer login" name="commit"/>
<!-- OPCIONAL: el campo public_verification es opcional -->
<input type="hidden" value="true" name="public_verification"/>
</form>

El formulario consta de los siguientes parámetros:

  • api_key: Identificador de la API Key de la pasarela de verificación de identidad.
  • notification_callback: URL a la que se dirigirá al usuario una vez completada la verificación de su identidad. En esta URL se recibirán como parámetros GET el resultado del proceso.
  • public_verification (opcional): Si añadimos el parámetro public_verification=true indicaremos que la verificación de identidad es pública y el proceso nos devolverá una URL con la prueba de la verificación para que podamos enlazarla en nuestro sitio web.

Recepción de los datos

Una vez completado el proceso identificación en la pasarela de verificaciones de identidad el usuario será dirigido al notification_callback. Si el notification_callback fuera http://www.mysite.com/login la url con la que nos llamaran será algo parecido a la siguiente :

http://www.mysite.com/login?
    token=cc9b9fe0965f471e50b2d9e5c31bfa4a9d42af5d
   &tractis%3Aattribute%3Adni=44183781E
   &tractis%3Aattribute%3Aname=DAVID+GARCIA+GARCIA
   &verification_code=e8b54d1bc09da6ab056cb8450487e49279b2ab83
   &tractis%3Aattribute%3Aissuer=DIRECCION+GENERAL+DE+LA+POLICIA

Aquí podemos ver que Tractis nos devuelve una serie de parámetros que identifican la transacción de la pasarela y los atributos sobre el usuario que han sido verificados:

  • tractis:attribute:dni=44183781E: El número de dni del usuario que se ha logado
  • tractis:attribute:name=DAVID GARCIA GARCIA: El nombre del usuario que se ha logado
  • tractis:attribute:issuer=DIRECCION GENERAL DE LA POLICIA: El emisor del certificado que ha sido usado, en este caso corresponde al emisor del dnie

Si se tratara de una verificación pública (con el argumento public_verification=true en el formulario) recibiríamos además el siguiente parámetro:

  • verification_url=https://www.tractis.com/verifications/cc9b9fe0965f471e50b2d9e5c31bfa4a9d42af5d: En esta URL se certifica cuáles han sido los atributos extraidos en la verificación. La URL solo será accesible mediante un enlace desde tu sitio web.

Tractis solamente llamará a la URL de notification_callback si el certificado el válido.

Nuevo: Por defecto el método HTTP de retorno cuando se ha producido la verificación de identidad con éxito es GET. Es posible configurar la API Key para que la vuelta se produzca usando el método HTTP POST, para ello tendrás que cambiar la opción en la configuración de la API Key y adaptar la recepción de atributos.

Verificación de los datos recogidos por la pasarela

Una vez recibidos los datos del usuario hemos de verificar el resultado recibido para evitar que alguien haya llamado a nuestra URL de notification_callback haciéndose pasar por Tractis e intentando engañar a nuestro sistema.

Para verificar la autenticidad del resultado debemos llamar a https://www.tractis.com/data_verification‘ usando el método POST y pasándole nuestra API Key y todos los datos recibidos en el callback.

Tractis nos responderá con un código de status HTTP. Si el código es 200 los datos son fiables y podemos proceder, si el código es otro simplemente debemos ignorar el resultado y mostrar un error.

IMPORTANTE: Tractis no permite utilizar una misma verificación varias veces así que la verificación solo funcionará una vez para cada verificación. Si intentamos verificar los datos una segunda vez Tractis no dará por válida la verificación.

Un ejemplo en código

A continuación damos un ejemplo en php para ver lo simple que sería el integrarse con una pasarela.

El formulario de login lo pondremos dentro de una página welcome.html. Éste será el formulario que debe enviar el usuario a Tractis para poder empezar el proceso:


<html>
<body>
Form test<br/>
<form method="post" action="https://www.tractis.com/verifications">
<input type="hidden" value="AQUI_TU_API_KEY" name="api_key" id="api_key"/>
<input type="hidden" value="AQUI_LA_URL_DE_TU_CALLBACK" name="notification_callback" id="notification_callback"/>
<input type="submit" value="Hacer login" name="commit"/>
</form>
</body>
</html>

Como puede verse en el código anterior debemos configurar el parámetro notification_callback de manera que apunte a la url que procesará el resultado de la verificación de identidad en nuestro site.

Suponiendo que hemos puesto como valor http://www.example.com/auth-result.php (siendo www.example.com nuestro servidor web) deberemos disponer de una página llamada auth-result.php con un contenido como el siguiente:


<html>
<body>
<?php

$s = curl_init();

curl_setopt($s,CURLOPT_URL,"https://www.tractis.com/data_verification");
curl_setopt($s,CURLOPT_POST,true);

// Tenemos que pasarle a /data_verifications todos los parámetros que nos ha enviado Tractis
// junto con nuestra API Key
$_GET['api_key'] = "AQUI_TU_API_KEY";
curl_setopt($s,CURLOPT_POSTFIELDS,$_GET);

curl_exec($s);
$status = curl_getinfo($s,CURLINFO_HTTP_CODE);

echo  "HTTP status " . $status . "<br/>";

if ($status == 200){
echo "Auth ok dni is " . $_GET["tractis:attribute:dni"];
}else{
echo "Auth failed";
}

?>
</body>
</html>

NOTA: Usamos la librería curl de php para hacer las llamadas de verificación. Para saber como instalarla o utilizarla mas allá de los usos expuestos consulta la documentación relativa a la misma dentro de la documentación de PHP.

Esta página llamará a Tractis, le pedirá que verifique que los datos son correctos, y si estos lo son, Tractis le devolverá un código HTTP 200 indicando que la información es fiable. Otro código distinto implicará que la información no es fiable y por lo tanto debe ser descartada.

Para acceder a la información sobre los atributos del usuario solamente debemos preguntar a la variable $_GET que contendrá todos los atributos verificados.

Por ejemplo el dni del usuario se encuentra en $_GET["tractis:attribute:dni"], el nombre en $_GET["tractis:attribute:name"] .