Tokens TOTP para verificación electrónica de visitas y autenticación segura

Recomendamos utilizar tokens de hardware TOTP para la verificación electrónica de visitas (EVV). La solución Protectimus EVV, basada en TOTP, permite determinar la hora exacta de las visitas mediante contraseñas de un solo uso.

Los tokens TOTP son un método de EVV sencillo y eficaz tanto para el personal de atención domiciliaria como para las personas que reciben asistencia.

Los tokens TOTP de hardware para EVV tienen formato de llavero y no requieren instalación, conexión a Internet ni alimentación eléctrica. Se entrega el token a la persona que recibe la atención y el cuidador anota los códigos de un solo uso al inicio y al final de la visita. Los códigos se transfieren mediante API a Protectimus EVV, que devuelve la hora exacta en la que se generó cada OTP.

Esta guía explica cómo integrar Protectimus EVV con su sistema de verificación electrónica de visitas.

1. Cómo funcionan los tokens TOTP de Protectimus para EVV

El algoritmo TOTP permite calcular la hora de generación de cada código con una precisión de 30 o 60 segundos, según el token. Para EVV recomendamos tokens TOTP con intervalos de 60 segundos, debido al problema de coincidencia de OTP que puede producirse con intervalos de 30 segundos.

El algoritmo TOTP para EVV funciona así:

• La persona que recibe la atención recibe un token TOTP de hardware con reloj integrado y un secreto compartido único preprogramado.
• El mismo secreto compartido está registrado en Protectimus EVV, que verifica las contraseñas de un solo uso y calcula cuándo se generó cada OTP.

El uso de tokens TOTP de Protectimus para EVV sigue este proceso:

1. El cuidador visita a la persona que recibe la atención y anota dos contraseñas de un solo uso del token OTP: una antes y otra después de la visita.
2. Después introduce ambos códigos en el sistema EVV para confirmar la visita.
3. El sistema EVV consulta al servidor Protectimus EVV para calcular la hora de la visita.
4. Conociendo el secreto compartido, Protectimus EVV genera contraseñas de un solo uso durante el día, la semana o el mes anteriores y determina la hora de generación de los códigos indicados. De este modo se establece cuándo tuvo lugar la visita.

2. El problema de las contraseñas de un solo uso coincidentes en EVV

¡IMPORTANTE! Para EVV recomendamos tokens TOTP de 8 dígitos con intervalos de 60 segundos.

El número de combinaciones posibles con seis dígitos es limitado.

Durante períodos largos, los valores numéricos de las OTP se repiten inevitablemente. Dos contraseñas generadas en momentos distintos pueden coincidir y dificultar la identificación de la hora exacta.

Para reducir este problema, utilice tokens TOTP con más dígitos e intervalos mayores. Para EVV recomendamos ocho dígitos e intervalos de 60 segundos.

3. Cómo integrar Protectimus EVV con su sistema de verificación electrónica de visitas

3.1. Registrarse y añadir tokens en Protectimus Cloud u On-Premise

1. Regístrese en el servicio en la nube de Protectimus y active la API o instale la plataforma local Protectimus On-Premise.


2. Añada los tokens. Para ello, inicie sesión en el servicio SaaS de Protectimus o en la plataforma local Protectimus On-Premise y abra la página Tokens.

3. Haga clic en Add Token.

4. Seleccione el token Protectimus Two.

5. Cargue el archivo que recibirá después de solicitar los tokens TOTP para EVV.

3.2. Utilizar la API de Protectimus para integrar el sistema EVV

¡IMPORTANTE! Puede utilizar nuestra colección de Postman para acelerar la integración. Está disponible previa solicitud. Para obtenerla, póngase en contacto con nuestro equipo de soporte.

La API de Protectimus se basa en los principios REST. Los datos se transmiten en XML o JSON y los valores de los parámetros son idénticos en ambos formatos. De manera predeterminada, las respuestas se envían en XML.

Encontrará instrucciones completas en nuestra guía de integración con la API de Protectimus.

3.2.1. Autorización

Solo los usuarios autorizados pueden acceder a la API de Protectimus. Se utiliza autenticación Basic: el nombre de usuario es el login del administrador que envía la solicitud y la contraseña es un token de autenticación.

El token de autenticación es el hash de una cadena formada por los siguientes elementos:

<ApiKey>:<YYYYMMDD>:<HH>

Donde:

• ApiKey es una clave API única para cada administrador, disponible y modificable en la página de gestión del perfil https://service.protectimus.com/profile.
• YYYYMMDD es la fecha actual en el formato indicado.
• HH es la hora UTC en formato HH: solo horas en formato de 24 horas, sin minutos ni segundos.

Ejemplo:

The administrator’s profile contains the following information:
ApiKey – MySecureApiKey; Date - 30 January 2014; Time - 17:42 (UTC).

String for hash: MySecureApiKey:20140130:17

Hash SHA256 for this text: 62704fb3a9dcf7b5b3cf7bda6ac9d0b0aa37c6fce8d0fae6b466c91ba68894f5

3.2.2. Envío de solicitudes

Todas las solicitudes a la API de Protectimus se transmiten mediante HTTPS.

Formato de la solicitud:

<HTTP-method>
https://service.protectimus.com/multipass-web-api/v<API_version>/<API_section>/<API_method>.<response_format>

Los parámetros anteriores tienen los siguientes valores:

• HTTP-method es el método correspondiente a la solicitud actual.
• API_version es la versión de la API. Actualmente solo está disponible la primera versión, por lo que esta parte de la solicitud es «v1».
• API_section es la sección del método llamado. Están disponibles auth-service, resource-service, token-service y user-service. Las descripciones de los métodos de la API se organizan según las secciones a las que pertenecen.
• API_method es el método que se llama.
• response_format es el formato de respuesta: XML o JSON. El valor predeterminado es XML.

Si se produce un error, el procesamiento se interrumpe y se devuelve un mensaje de error.

La lista y descripción de los errores se encuentra en la sección Error Message de las instrucciones de integración con la API de Protectimus.

3.2.3. Método de la API de Protectimus EVV

Utilice este método de la API para obtener la hora de generación de la contraseña de un solo uso.

Opción 1. CURL

curl --request POST 'https://api.protectimus.com/api/v1/token-service/otp-time' \

--header 'Authorization: Basic ZGFueWxvLmRlaW5la29AZ21haWwuY29tOmNTI=' \

--header 'Content-Type: application/x-www-form-urlencoded' \



--data-urlencode 'tokenId=123' \

--data-urlencode 'otp=825043'

Opción 2. HTTP

POST /api/v1/token-service/otp-time HTTP/1.1
Host: api.protectimus.com
Authorization: Basic ZGFueWxvLmRlaW5la29AZ21haWwuY29tOmNTI=
Content-Type: application/x-www-form-urlencoded
Content-Length: 22


tokenId=123&otp=825043

Si tiene alguna pregunta, póngase en contacto con el servicio de atención al cliente de Protectimus.