Introducción

Las APIs del INS utilizan un modelo de seguridad basado en el protocolo de autorización OAuth 2.0. Este es un protocolo diseñado para permitir que una determinada aplicación pueda acceder de forma segura recursos alojados en servidores de terceros, mediante el uso de tokens de acceso. Esta tecnología es actualmente el estándar de la industria para dar seguridad a las transacciones en línea.

El estándar OAuth 2.0 define una serie de grants (tipos de concesión), que definen los flujos para obtener los tokens de seguridad. Cada grant tiene sus particularidades y cubre un caso de uso específico.

El INS utiliza un grant denominado client_credentials. Este grant está diseñado para ser utilizado en comunicaciones servidor a servidor y fuera del contexto del usuario, es decir, sin necesidad de que el usuario ingrese sus credenciales o brinde algún consentimiento para establecer la comunicación. El flujo asociado a este grant establece que la solicitud para obtener un token de acceso debe incluir un client_id y un client_secret, equivalentes a credenciales de acceso. Estas credenciales deben ser enviadas a un servidor de autorización, que se encarga de verificarlas. Si la validación es satisfactoria, el servidor de autorización retorna un token de acceso, que será utilizado por la aplicación cliente para acceder los recursos del API. Esta interacción se presenta en el siguiente diagrama.

Para solicitar un token de acceso al servidor de autorización del INS, se debe enviar una solicitud con las siguientes características:

Método: POST
Content-type: application/x-www-form-urlencoded
Contenido del mensaje:

grant_type=client_credentials&client_id=<client_id>&client_secret=<client_secret>

Donde <client_id> y <client_secret> corresponden a las credenciales entregadas por el INS.

Ejemplo:

POST https://servidor-autorizacion-ins/connect/v1/token HTTP/1.0
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials&client_id=123456&client_secret=abcxyz

El INS dispone de dos ambientes para el consumo de APIs: ambiente de pruebas y de producción. Los URLs para la obtención de tokens de acceso en cada uno de estos ambientes son:

Pruebas:

https://apiintegracion.grupoins.com/connect/v1/token

Producción

https://apiintegracion.grupoins.com/connect/v1/token

A continuación se explica como obtener tokens de acceso mediante distintas herramientas:

cURL

Puede obtener un token de acceso mediante el comando cURL de la siguiente forma:

curl --request POST \
--url 'https://apiintegracion.grupoins.com/connect/v1/token' 
--header 'content-type: application/x-www-form-urlencoded' \
--data grant_type=client_credentials \
--data 'client_id=client_id_asignado_por_el_ins' \
--data 'client_secret=client_secret_asignado_por_el_ins'

El ejemplo anterior utiliza el ambiente de pruebas. Para el ambiente de producción, substituir apiintegracion por apiproduccion en el parámetro --url. Substituir además los valores de los parámetros client_id y client_secret con sus credenciales.

POSTMAN

También puede configurar la herramienta Postman para obtener tokens de acceso, siguiendo los siguientes pasos:

  1. Seleccionar la pestaña "Authorization".

  2. En la lista desplegable "Auth Type", seleccionar "OAuth 2.0".

  3. En el campo "Token Name" ingresar un nombre para identificar el token.

  4. En la lista desplegable "Grant type" seleccionar "Client Credentials".

  5. En el campo "Access Token URL" ingresar el URL para la obtención de tokens. Este varía según el ambiente.

  6. En el campo "Client ID" ingresar su client_id.

  7. En el campo "Client Secret" ingresar su client_secret.

  8. En la lista "Client Authentication" seleccionar "Send as Basic Auth header".

  9. Mediante el botón "Get New Access Token" se solicita el token de acceso. Esto despliega el siguiente diálogo.

Utilizar el botón "Use token" para cargar el token obtenido en la solicitud actual.

Si requiere conocer como obtener un token de acceso desde el código fuente, en este enlace encontrará ejemplos en los lenguajes de programación más comunes.

Estructura del token de acceso

La respuesta retornada por el servidor de autorización del INS, tiene una estructura como la siguiente:

{
"access_token":"eyJhbGciOiJSUzI1NiIsImtpZCI6IjU3RkY0MDg0QThFNThFQjk2ODJBQzIzRTJEMTI3REU4OTEzRkJDMERSUzI1NiIsInR5cCI6ImF0K2p3dCIsIng1dCI6IlZfOUFoS2psanJsb0tzSS1MUko5NkpFX3ZBMCJ9.eyJuYmYiOjE3NDcwNzg2MTYsImV4cCI6MTc0NzA4MjIxNiwiaXNzIjoiaHR0cE140lil2nOaSOQevg6qqe4xULwv6L5MVxk603EXnnKGxiccOvuyHVFoAER7T62A-FqhYsOMVvw1tXMF-5U_Qt1t1c-LOd1q5jFITVRJ_2ePGMNGY3vKZYUfigrlPa7qdUvDBm5kdaQJ8gG9eYZSXknyEA9qulJqGmFy5-a3qm9vGo58ymRF-k67tY-BHUB8i93YnYrBdGEqZTGLSq0xmHMxRUvlep82K3rj9CaECCETESE7MPY325-A",
"expires_in": 3600,
"token_type": "Bearer",
"scope": "IniciarSesion"
}

Consiste en un mensaje en formato JSON (Content-type application/json) y que tiene por los siguientes atributos:

  • access_token: Corresponde al token de acceso como tal. Es el atributo más importante de la respuesta y debe adjuntarse en cada llamado del API.

  • expires_in: Tiempo de expiración en segundos a partir de la fecha de obtención del token. En el ejemplo, el valor corresponde a 3600 segundos o 1 hora. Una vez transcurra el tiempo indicado por este atributo, el token de acceso expira y se vuelve inválido, siendo necesario obtener otro token para continuar consumiendo los APIs. Cuando un token expira, todas las solicitudes que se realicen con ese token recibirán un código HTTP 401 (No autorizado). La expiración de un token siempre debe leerse de este atributo, no debe estar es un archivo de configuración ni en mecanismos similares, ya que, podría modificarse en cualquier momento según las necesidades del INS.

  • token_type: Indica el tipo de token. Para el caso del INS el valor siempre será "Bearer".

  • Scope: Lista de scopes.

Uso del token de acceso

El token de acceso retornado por el servidor de autorización, debe enviarse en un encabezado HTTP para todos los llamados que se realicen a los APIs del INS. Este encabezado se denomina Authorization y tiene el siguiente formato:

Authorization: Bearer <token de acceso>

Donde <token de acceso> corresponde al valor del atributo access_token, retornado por el servidor de autorización. Ejemplo:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRt...
GET https://apiintegracion.grupoins.com/polizas/v1/consulta?parametro1=valor1

Anotar que la palabra Bearer es obligatoria.

Proteger credenciales

Es indispensable que las aplicaciones que interactuen con los APIs del INS, protejan adecuadamente las credenciales (client_id/client_secret) proporcionadas por el INS. Si un atacante logra tener acceso a las credenciales, podría generar tokens y utilizarlos para manipular o extraer información de los sistemas del INS, con los riesgos que esto implica.

Las APIs del INS utilizan un modelo de autorización basado en el grant denominado client_credentials. Este grant se diseñó para ser utilizado en comunicaciones servidor a servidor y fuera del contexto del usuario, es decir, sin necesidad de que el usuario ingrese sus credenciales o brinde algún consentimiento para establecer la comunicación. El flujo asociado a este grant, establece que la solicitud para obtener un token debe incluir el client_id y el client_secret, por lo cual, dependiendo desde donde se realice la solicitud para obtener el token, esta información podría verse comprometida Es por esto, que deben seguirse las siguientes recomendaciones:

  • En sistemas Web, las credenciales de acceso nunca deben almacenarse en el front end. Un navegador de internet se considera un lugar inseguro por defecto y no debe utilizarse para almacenar usuarios, contraseñas u otros datos confidenciales. En estos casos, la aplicación Web debe almacenar las credenciales en su servidor de backend y que este sea el encargado de comunicarse con los APIs del INS.

    Si la arquitectura de la aplicación carece de un servidor, por ejemplo, aplicaciones tipo SPA (Single Page Application), deben utilizarse alternativas como el patrón Backend For Frontend (BFF) para gestionar las credenciales.

Llave de subscripción

Para consumir los APIs del INS, se requiere enviar, además del token de acceso, una llave de subscripción. El valor de esta llave es suministrado por el INS, en conjunto con el client_id y el client_secret.

La llave de subscripción se debe enviar en un encabezado HTTP denominado subscription-key. Ejemplo:

GET https://apiintegracion.grupoins.com/polizas/v1/recibos/consulta?numeroPoliza=ABCXYZ HTTP/1.0
Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZC....Wup7nKKLcq0sjc29H0sJ84rMe_5rySm5FDBpOlNm6cxK56ajxZUydEjIjVMzR_niFEdFsk
subscription-key: f4027603-e270-4a2b-b633-5a6a1dad7785