Autenticação com assinatura
Para garantir maior comodidade e segurança aos seus clientes, o Carat oferece, além da autenticação através da chamada POST à URL cadastrada (saiba mais), a opção de assinatura de mensagens, em que conteúdo e remetente passam a ter garantias de integridade e autenticidade, respectivamente. Dessa forma, a loja recebe as informações da transação recém-criada diretamente na resposta de sua chamada REST e não mais através do POST de autenticidade.
O que você precisará#
- Cadastro ativo no ambiente de homologação do Carat (obtido com nossa equipe de suporte);
- A criação de uma chave pública e o gerenciamento da sua respectiva chave privada;
- Cadastro da chave pública no Carat (feito através da nossa equipe de suporte).
Criando as chaves pública e privada#
Exemplos de como criar as chaves privada e pública:
- No Linux (utilizando o terminal):
- No Windows:
Utilizar ssh-keygen no prompt de comando
Utilizar uma versão do openssl para windows, executar como administrador e executar o seguinte comando:
Atenção:
Esse arquivo de chave pública
jwtRS256.key.pubé o único arquivo que você deverá enviar pra nossa equipe de suporte. Sempre mantenha seguros a sua chave privada e a sua senha, caso tenha cadastrado uma.
Algoritmo de assinatura#
O algoritmo suportado pela aplicação é o RS256 em conjunto com o padrão JWT (RFC 7519).
Ao utilizar este padrão, uma assinatura é composta por três partes: cabeçalho, dados (payload) e a verificação de assinatura. A cada uma dessas partes, é aplicada uma codificação Base64.
Primeira parte (cabeçalho)#
O cabeçalho deve conter o seguinte conteúdo fixo:
Cabeçalho Base64:
Segunda parte (payload)#
A parte de dados (payload) varia de acordo com a operação a ser assinada. Exemplo:
Payload Base64:
Composição do payload#
Dependendo do serviço chamado, os campos do payload serão diferentes. Abaixo estão descritos os campos necessários para cada serviço.
Serviços de criação e listagem de lojas#
| Parâmetro | Descrição | Formato | Obrigatório |
|---|---|---|---|
merchant_id | Código da loja no Carat. | = 15 AN | SIM |
merchant_key | Chave de autenticação da loja no Carat. | < 80 AN | SIM |
timestamp | Representação em milissegundos do momento de geração da assinatura. Enfatizando que o campo timestamp possui um limite de validade de 10 minutos. | < 13 N | SIM |
Serviços de edição e consulta de loja#
| Parâmetro | Descrição | Formato | Obrigatório |
|---|---|---|---|
merchant_id | Código da loja no Carat. Os códigos de produção e certificação serão diferentes. | = 15 AN | SIM |
merchant_key | Chave de autenticação da loja no Carat. As chaves de produção e certificação serão diferentes. | < 80 AN | SIM |
timestamp | Representação em milissegundos do momento de geração da assinatura. Enfatizando que o campo timestamp possui um limite de validade de 10 minutos. | < 13 N | SIM |
registered_merchant_id | Código da loja criada ou a ser criada no Carat. Os códigos de produção e certificação serão diferentes. | = 15 AN | SIM |
Serviços de criação de transação#
| Parâmetro | Descrição | Formato | Obrigatório |
|---|---|---|---|
merchant_id | Código da loja no Carat. Os códigos de produção e certificação serão diferentes. | = 15 AN | SIM |
merchant_key | Chave de autenticação da loja no Carat. As chaves de produção e certificação serão diferentes. | < 80 AN | SIM |
order_id | Código do pedido definido pelo lojista. | < 40 AN | Condicional |
merchant_usn | Número sequencial único para cada pedido, criado pela loja. | < 12 N | Condicional |
timestamp | Representação em milissegundos do momento de geração da assinatura. Enfatizando que o campo timestamp possui um limite de validade de 10 minutos. | < 13 N | SIM |
Importante:
Os campos
order_idemerchant_usnnão são obrigatórios para algums serviços de criação de transações e, por isto, devem seguir a mesma regra, sendo informados com os mesmos valores contidos no corpo da requisição.
Exemplo:
Demais serviços#
| Parâmetro | Descrição | Formato | Obrigatório |
|---|---|---|---|
nit | Identificador da transação no Carat. | = 64 AN | SIM |
merchant_id | Código da loja no Carat. Os códigos de produção e certificação serão diferentes. | = 15 AN | SIM |
merchant_key | Chave de autenticação da loja no Carat. As chaves de produção e certificação serão diferentes. | < 80 AN | SIM |
timestamp | Representação em milissegundos do momento de geração da assinatura. Enfatizando que o campo timestamp possui um limite de validade de 10 minutos. | < 13 N | SIM |
Exemplo:
Terceira parte (verificação)#
A terceira e última parte é o resultado da criptografia RSA das duas partes anteriores codificadas separadamente em Base64 e concatenadas por um ponto (".").
Duas partes anteriores codificadas seperadamente em Base64 e concatenadas por um ponto ("."), onde o primeiro segmento do texto - anterior ao ponto - corresponde ao cabeçalho e o segundo corresponde ao payload:
Por fim, uma criptografia RSA, usando a chave privada loja, deve ser feita neste conteúdo. Exemplo:
Assinatura final#
A assinatura final é a concatenação das 3 partes separadas por ("."):
Essas três partes da assinatura, representada pelo exemplo anterior, devem ser enviadas no header Authorization com valor Bearer <assinatura>. Com isso, o Carat poderá validar a assinatura utilizando a chave pública da loja.
Utilizando site JWT para testes#
É possível utilizar o site do JWT para criar uma assinatura válida para testes. Para isso é necessário selecionar o algoritmo RS256 e passar o respectivo payload e uma chave pública e privada.
Caso a chave pública não esteja válida a mensagem "Invalid Signature" será exibida.
