Digital Signature
Este interceptor é responsável por validar requisições feitas a uma API. As requisições realizadas precisam conter uma assinatura digital — composta por um token gerado através de chave RSA — que deverá ser passado via header ou query parameter.
Antes de utilizar o interceptor Digital Signature, é necessário gerar uma chave RSA. Feito isso, é necessário gerar uma assinatura digital, por aplicativo próprio ou usando a API Crypto disponível em seu ambiente.
Aqui você encontra um passo-a-passo para habilitar o interceptor.
Configurando o interceptor
Este interceptor só pode ser adicionado ao fluxo de requisição. Para que funcione, é necessário que o fluxo da API identifique uma app e, para tanto, deve haver um interceptor que valide token antes do Digital Signature (Access Token Validation, Client ID Validation, JWT Validation ou OAuth).
![digital signature flow](_images/digital-signature-flow.png)
Quando aberta a janela de configuração do interceptor, será necessário selecionar a localização da assinatura (Location) e o algoritmo usado (Algorithm). Temos suporte aos seguintes algoritmos de criptografia: SHA1, SHA224, SHA256, SHA384, SHA512, MD2 e MD5. Esta página contém uma referência com os nomes e implementação desses algoritmos.
No exemplo abaixo, geraremos uma assinatura no padrão SHA1 e passada no header:
![digital signature](_images/digital-signature.png)
Para que o interceptor funcione, é necessário que a app esteja associada à API que se deseja consumir. O usuário poderá realizar a assinatura da informação por meio de aplicativo próprio ou via a API Crypto disponível no API Manager. Neste segundo caso, é necessário que a app esteja associada também à API Crypto, que possibilitará acessar os endpoints que gerarão a assinatura.
![digital signature app](_images/digital-signature-app.png)
Gerando a assinatura digital
1. Chave RSA
Para gerar a assinatura, é preciso gerar a chave RSA primeiro, fazendo uma requisição POST para http://<your-domain>/api-crypto/api/v1/keys
.
Os valores que deverão ser passados no header da requisição são estes:
Content-Type: application/json Authorization: Basic client_id:client_secret em Base64
O valor do client_id informado deverá ser o de uma app vinculada à API que terá as chamadas assinadas.
|
O corpo deve conter:
{ "type" : "RSA" }
Exemplo de curl da requisição:
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"
}'
Quando a requisição houver sido completada, a resposta retornada terá os dados a seguir:
As chaves públicas e privadas são devolvidas em Base64. |
{ "privateKey":"base64private", "publicKey":"base64public", "type": "RSA", "creationDate": 1557932655994 }
2. Assinatura
Depois da geração das chaves pública e privada, o usuário poderá realizar a assinatura da informação por meio de aplicativo próprio ou via a API Crypto disponível no API Manager.
Caso a opção de geração da assinatura seja via API Crypto, deve ser feita uma requisição POST para http://<your-domain>/api-crypto/api/v1/sign
.
O header deverá conter:
Content-Type: application/json Authorization: Basic client_id:client_secret em Base64
O valor do client_id informado deverá ser o de uma app vinculada à API que terá as chamadas assinadas.
|
O corpo deverá conter:
{ "type": "RSA", "data":<url_da_api>, "algorithm": "SHA1" }
Exemplo 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"
}'
Nesta etapa, atente-se ao campo "data" , que conterá o endpoint que será chamado com a assinatura.
Ele é sensível a "/".
Portanto, um endpoint "exemplo.com/teste" não é idêntico a "exemplo.com/teste/" .
Além disso, como iremos usar SHA1 (seguindo as configurações informadas ao inserir o interceptor no fluxo da API), "algorithm" tem o valor "SHA1" .
|
Depois que a requisição for completada, a resposta retornada será um JSON contendo a assinatura digital em formato Base64, como o exemplo abaixo.
{ "signature": "k4OoVH9uiNjDpVPqTho17FBdgdROJyT2FD2ngoxSmo/vMPUye8fXZFO1fqj0iI23AXtliRnLxGgndNLAqEY0PAPMtNy0C8MGoQeSSCuRema9q36gNOgUFTtXz/2HiwGN8mbI5p8+CzyPoJvwAI9Xn3nrosSJh5+NIdHFhirQziU=" }
Após a geração da assinatura digital, o usuário deverá utiliza-lá nas requisições à API que contenha o interceptor de Digital Signature.
O valor da assinatura deverá ser enviado no header ou query param, dependendo da configuração do interceptor no fluxo, para a URL definida no campo "data"
da etapa 2 acima.
Não é possível utilizar a mesma assinatura gerada para uma determinada API em requisições a outra API. |
Ao usar um token de assinatura nas chamadas da sua API, lembre-se de codificar a assinatura no formato padrão caso ela seja informada no query parameter da URL. Você pode fazer o encoding aqui. |
Share your suggestions with us!
Click here and then [+ Submit idea]