🔐Secure Link - Implementación

Guía del desarrollador para implementación de Access Token y Generación de Enlace Seguro de IDG

Inicio

Esta guía explica cómo obtener un JWT de Identidad Digital Global (IDG) para comunicarse con el servicio de biometría, lectura y extracción de datos de de documentos de identificación, las reglas de uso y el vencimiento del token.

IDG es un producto desarrollado por Global Bridge Connections, con marca registrada en Paraguay, Perú, Panamá y los Estados Unidos de América.

Audiencia

Esta guía está orientada para personas con conocimientos en JavaScript, conceptos de programación y programación orientada a objetos, que desean utilizar la API de IDG.

Ambientes

El cliente dispondrá de dos ambientes totalmente independientes para utilizar el Secure LInk y estas son:

Staging

Ambiente proveída al cliente para realizar sus pruebas y familiarizarse con el producto.

El Portal KYC se accede con la siguiente url: https://dash-kyc-staging.globalbridgeconnections.com.py/

Host Api: https://stagingservices.globalbridgeconnections.com.py/

Production

Ambiente proveída al cliente con el cual operará una vez culminada sus pruebas con el producto.

El Portal KYC se accede con la siguiente url: https://dash-kyc.globalbridgeconnections.com.py/

Host Api: https://services.globalbridgeconnections.com.py/

Autorización

El servicio de Secure Link requiere de un JWT como autorización, el cual debe ser generado por el cliente con dos datos provistos por Global Bridge Connections de manera confidencial a cada empresa cliente.

Los datos a ser proveídos para la generación del JWT son los listados a continuación:

• Una clave privada RS256, la cual deberá ser almacenada de forma segura de lado del cliente que utilizará los servicios de IDG.

• Un identificador único o ID de cliente (client_id).

Ambos datos también son accesibles desde el Portal KYC -> Mi Perfil

Obs: Las credenciales podrián ser distintas según el ambiente en la que opere.

A continuación hablaremos de los pasos a seguir para la creación de Link Seguro.

Paso 1 - Generación de un JWT

El JWT deberá contar con la siguiente estructura:

Parte	Key	Ejemplo de Firma	Observación
Header	alg	RS256	Algoritmo de firma JWT, debe ser un valor RS256 constante: "RS256"
Header	typ	JWT	Tipo de token. Valor constante: “JWT”
Header	kid	test2 (opcional)	Clave que utiliza para identificar a la firma
Payload	sub	Colocar el Client ID	Su identificación de cliente proporcionada (client_id)
Payload	iss	Colocar el Client ID	Su identificación de cliente proporcionada (client_id)
Payload	aud	https://idg.globalbridgeconnections.com.py	Host Cliente
Payload	exp	1694536577	Fecha y Hora de caducidad del JWT en Epoch Unix Timestamp Formato Seconds
Payload	iat	1694532977	Fecha y Hora de creación del JWT en Epoch Unix Timestamp Formato Seconds

async execute({ id_client }: IRequest): Promise<{ token: string } | AppError> {
  const IDENTIDAD_GLOBAL_AUD = 'https://stagingservices.globalbridgeconnections.com.py';
  const IDENTIDAD_GLOBAL_KEYID = id_client;
  const IDENTIDAD_GLOBAL_CLIENT_ID = id_client;
  const IDENTIDAD_GLOBAL_SECRET_KEY='./unit/keys/secret.production.pem'
  const privateKey = fs.readFileSync(IDENTIDAD_GLOBAL_SECRET_KEY, 'utf8');
  const currentTimestamp = Math.floor(Date.now() / 1000);
  const expiration = currentTimestamp + 3600;


  const token = jwt.sign(
    {
      sub: IDENTIDAD_GLOBAL_CLIENT_ID,
      iss: IDENTIDAD_GLOBAL_CLIENT_ID,
      aud: IDENTIDAD_GLOBAL_AUD,
      exp: expiration,
      iat: currentTimestamp
    },
   privateKey,
   { algorithm: 'RS256', keyid: IDENTIDAD_GLOBAL_KEYID }
 );


return { token };
}

Generación de un token JWT en Node.js

Paso 2: Validación y Registro de JWT

Es un servicio a través del cual IDG recibe el JWT generado por el cliente para autenticar y autorizar el uso de los servicios de Secure Link.

Para ello se realiza una solicitud a un Endpoind cuyas características son la siguiente:

Validación y Registo de JWT

POST {host_api}/api/v1/kyc-kit/oauth/token

Endpoint para verificar y registrar JWT

Headers

Name	Type	Description
Authorization*	String	Bearer {JWT generado en el paso 1}

200: OK JWT Generado en el paso 1

400: Bad Request Token ya registrado

401: Unauthorized Invalid Token

500: Internal Server Error Error Interno

Paso 3: Generación de link seguro

Una vez que se registre el JWT en el Paso 2, procedemos a enviar datos que nos servirá cuando al momento de generar el link seguro.

Actualmente tenemos 2 versiones de link seguro, para gestionar el cambio entre versiones debe hacerlo a través del canal de soporte ([e-mail])

Versión 1

Se caracteriza por el esquema original de Secure Link. (OCR, Blacklist, LivenessCheck, Facematch)

Para ello se realiza una solicitud a un Endpoind cuyas características son la siguiente:

Generar Link Seguro

POST {{host_api}}/api/v1/kyc-kit/processing_link

Endpoint que se encarga de generar el link seguro

Headers

Name	Type	Description
Authorization*	String	Bearer {JWT registrado y retornado en el Paso2}

Request Body

Name	Type	Description
external_id *	String	ID con el que el cliente podrá identificar el proceso.
callback*	String	Una URI válida, al cual haremos post y enviaremos una estructura json con los datos recolectados durante el proceso
authorization	String | Undefined	ApiKey que se utilizará como header Authorization al hacer el envio de datos al callback del cliente
document_reader_dual_mode	Boolean	Por defecto se tomará el valor configurado en el dashboard, si en un proceso de onboarding en particular se necesita apagar, puede enviar este atributo en False

200: OK Link Seguro creado

{
    "id": {id de link seguro},
    "external_id": {external id ingresado por el cliente},
    "callback": {endpoint del cliente al cual se hara el envio de los datos},
    "url": {link seguro},
    "token": {token de link seguro},
    "expire_at": {fecha de expiración de link seguro, programable en el Dashboard}
}

401: Unauthorized Invalid Token

500: Internal Server Error Internal Error

Versión 2

A diferencia de la Versión 1 se caracteriza por porder customizar el workflow a nivel de módulos, eso quiere decir que el cliente podrá escoger que módulos de KYC serán utilizados en el proceso de onboarding.

Para ello se realiza una solicitud a un Endpoind cuyas características son la siguiente:

Generar Link Seguro

POST {{host_api}}/api/v1/kyc-kit/processing_link

Endpoint que se encarga de generar el link seguro

Headers

Name	Type	Description
Authorization*	String	Bearer {JWT registrado y retornado en el Paso2}

Request Body

Name	Type	Description
callback*	String	Una URI válida, al cual haremos post y enviaremos una estructura json con los datos recolectados durante el proceso
external_id *	String	ID con el que el cliente podrá identificar el proceso.
authorization	String | Undefined	ApiKey que se utilizará como header Authorization al hacer el envio de datos al callback del cliente
modules*	String	aqui va las id de los modulos (ej ”1099,1095,1096,1098”) que el cliente desee activar en el link seguro. Se especificará mejor en Módulos Validos.
data.first_name*	String | Null | Undefined	Requerido solo si module 1095 existe y 1099 no existe, primer nombre a utilizarse en módulo 1095.
data.second_name	String | Null | Undefined	Segundo nombre a utilizarse en módulo 1095.
data.first_last_name*	String | Null | Undefined	Requerido solo si module 1095 existe y 1099 no existe, primer apellido a utilizarse en módulo 1095.
data.second_last_name	String | Null | Undefined	country_code a utilizarse en módulo 1095.
data.doc*	String | Null | Undefined	Requerido solo si module 1098 existe y 1099 no existe, reference image del documento a utilizarse en módulo 1098.
data.selfie*	String | Null | Undefined	Requerido solo si module 1098 existe y 1096 no existe, selfie del documento a utilizarse en módulo 1095.
document_reader_dual_mode	Boolean	Por defecto se tomará el valor configurado en el dashboard, si en un proceso de onboarding en particular se necesita apagar, puede enviar este atributo en False

200: OK Link Seguro creado

{
    "id": {id de link seguro},
    "external_id": {external id ingresado por el cliente},
    "callback": {endpoint del cliente al cual se hara el envio de los datos},
    "url": {link seguro},
    "token": {token de link seguro},
    "expire_at": {fecha de expiración de link seguro, programable en el Dashboard}
}

400: Bad Request Faltan Parametros en la data del body

{

"message": "Favor ingresar {parametro requerido en el body según modulos}",

"data": [],

"code": "A5000"

}

400: Bad Request Falta ingresar modulos

{

"message": "Módulos no han sido ingresados",

"data": [],

"code": "A5000"

}

400: Bad Request Módulos ingresados no son válidos

{

"message": "El modulo 10 no existe",

"data": [],

"code": "A5000"

}

401: Unauthorized JWT invalido

{

"message": "Invalid Token",

"data": [],

"code": "A5000"

}

500: Internal Server Error Internal Error

Módulos Válidos

Aquí definimos un diccionario de los parámetros usados en el body al momento de generar el Secure Link.

Actualmente Secure Link puede utilizar los módulos (Carga de Documento, Lista de Sanciones, Prueba de Vida, Comparación de Rostro) que el cliente desee al momento de generar el link seguro, mencionando los id de cada uno de los módulos en un string separados por coma y sin espacio (por ejemplo "1099,1095,1096,1098" o "1099" o "1099,1095").

El flujo del Secure Link es único, es por ello que no importa el orden en que ingrese los módulos en el string, siempre será el mismo.

Tabla de id y su respectivo módulo

ID	Módulo
1099	Carga de Documento
1095	Lista de Sanciones
1096	Prueba de Vida
1098	Comparación de Rostro

Máximo intento de peticiones

A fin de asegurar un uso efectivo de los componentes, se ha implementado un control de peticiones, el cual permitirá hasta un máximo de 5 intentos para cada componente. Una vez excedido se reenviará el usuario a la vista de error ("/error") y el token será bloqueado.

En el caso de querer continuar con el proceso de onboarding, será necesario generar un link seguro nuevamente.