Digital Signature

Este interceptor es responsable de validar peticiones hechas a una API. Las peticiones realizadas deben contener una firma digital compuesta por un token generado a través de clave RSA que deberá ser pasado en un header o parámetro de consulta.

Antes de utilizar el interceptor Digital Signature, es necesario generar una clave RSA. Después, hay que generar una firma digital usando la API Crypto disponible en su entorno.

A continuación, usted encontrará una guía paso a paso acerca de cómo habilitar el interceptor.

Configurando el interceptor

El interceptor Digital Signature sólo puede ser añadido al flujo de petición (request). Para que funcione, el flujo API debe identificar una aplicación y, para ello, debe haber un interceptor que valide los tokens antes del Digital Signature (Access Token Validation, Client ID Validation, JWT Validation u OAuth).

Al abrir la ventana de configuración del interceptor, seleccionar la ubicación de la firma (Location) y el algoritmo utilizado (Algorithm). Soportamos estos algoritmos de encriptamiento: SHA1, SHA224, SHA256, SHA384, SHA512, MD2 y MD5. Esta página contiene una referencia con los nombres y la implementación de estos algoritmos.

En el ejemplo de abajo, generaremos una firma en el estándar SHA1 e informada en el header:

Para que el interceptor funcione, la aplicación debe estar asociada a la API que se va a consumir. El usuario podrá firmar la información usando una herramienta propria o a través de la API Crypto disponible en su API Manager. En este segundo caso, la aplicación también debe estar asociada a la API Crypto, lo que permitirá acceder a los endpoints que generarán la firma.

Si su API retorna el status code 401 Unauthorized al utilizar este interceptor, es posible que el token no sea válido. Consulte más detalles en esta página de nuestras preguntas frecuentes.

Generando la firma digital

1. Clave RSA

Para generar la firma, es necesario generar primero la clave RSA, haciendo una petición POST para http://<su-dominio>/api-crypto/api/v1/keys

Los valores que deberán ser pasados en el header de la petición son los siguientes:

Content-Type: application/json
Authorization: Basic client_id:client_secret em Base64

El valor del client_id informado en el header deberá ser de una app vinculada a la API cuyas llamadas serán firmadas.

El cuerpo deberá contener:

 {
    "type" : "RSA"
 }

Ejemplo de curl de la petición:

curl --request POST \
  --url https://api-treinamento.sensedia.com/sandbox/api-crypto/api/v1/keys \
  --header 'authorization: Basic <client_id:client_secret base64>' \
  --header 'content-type: application/json' \
  --data '{
 "type": "RSA"
}'

Después que la petición es completada, la respuesta retornada contendrá los siguientes datos:

Las claves públicas y privadas son devueltas en formato Base64.

{
    "privateKey":"base64private",
    "publicKey":"base64public",
    "type": "RSA",
    "creationDate": 1557932655994
}

2. Firma

Después de la generación de las claves pública y privada, el usuario podrá realizar la firma de la información por medio de herramienta propia o a través de la API Crypto disponible en su API Manager.

En el caso que la opción de generación de la firma sea a través de la API Crypto, debe ser hecha una petición para http://<your-domain>/api-crypto/api/v1/sign.

El header deberá contener:

Content-Type: application/json
Authorization: Basic client_id:client_secret em Base64

El valor del client_id informado en el header deberá ser de una app vinculada a la API cuyas llamadas serán firmadas.

El cuerpo deberá contener:

{
    "type": "RSA",
    "data":<url_de_la_api>,
    "algorithm": "SHA1"
}

Ejemplo de curl:

curl --request POST \
  --url https://api-treinamento.sensedia.com/sandbox/api-crypto/api/v1/sign \
  --header 'authorization: Basic <client_id:client_secret base64>' \
  --header 'content-type: application/json' \
  --data '{
 "type": "RSA",
 "data": "api_url",
 "algorithm": "SHA1"
}'

En esta etapa, observe el campo "data", que contendrá el endpoint que será llamado con la firma. Él es sensible a "/". Por lo tanto, un endpoint "ejemplo.com/teste" no es idéntico a "ejemplo.com/teste/". Además, como usaremos SHA1 (siguiendo los ajustes informados al insertar el interceptor en el flujo de la API), "algorithm" tiene el valor "SHA1".

Después que la petición es completada, la respuesta retornada contendrá una firma digital en formato Base64, como en el siguiente ejemplo:

{
  "signature": "k4OoVH9uiNjDpVPqTho17FBdgdROJyT2FD2ngoxSmo/vMPUye8fXZFO1fqj0iI23AXtliRnLxGgndNLAqEY0PAPMtNy0C8MGoQeSSCuRema9q36gNOgUFTtXz/2HiwGN8mbI5p8+CzyPoJvwAI9Xn3nrosSJh5+NIdHFhirQziU="
}

Después de la generación de la firma digital, el usuario será capaz de utilizarla en las peticiones a la API que contenga el interceptor Digital Signature El valor de la firma deberá ser informado en el header o parámetro de consulta (query param), dependiendo de la configuración del interceptor en el flujo, a la URL definida en el campo "data" del paso 2 anterior.

No es posible utilizar la misma firma generada para una API en peticiones a otra API.

Al usar un token de firma en llamadas a su API, recordarse de realizar la codificación de la firma en el formato estándar en el caso que la firma sea informada en el query parameter de la URL. El encoding puede ser hecho aquí.

Thanks for your feedback!

EDIT

Share your suggestions with us!
Click here and then [+ Submit idea]