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).

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:

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.

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.

Thanks for your feedback!

EDIT

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