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

# criando a sua chave privada:
ssh-keygen -t rsa -b 4096 -m PEM -f jwtRS256.key

# criando uma chave pública a partir da chave privada criada:
openssl rsa -in jwtRS256.key -pubout -outform PEM -out jwtRS256.key.pub

No Windows:

Utilizar ssh-keygen no prompt de comando

# criando a sua chave privada:
ssh-keygen -t rsa -b 4096 -m PEM -f jwtRS256.key

Utilizar uma versão do openssl para windows, executar como administrador e executar o seguinte comando:

# criando uma chave pública a partir da chave privada criada:
openssl rsa -in jwtRS256.key -pubout -outform PEM -out jwtRS256.key.pub

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:

{
  "alg": "RS256",
  "typ": "JWT"
}

Cabeçalho Base64:

{TOKEN_JWT_EXAMPLE}

Segunda parte (payload)

A parte de dados (payload) varia de acordo com a operação a ser assinada. Exemplo:

{
  "merchant_id": "XXXXX",
  "merchant_key": "XXXXXXXXXXXXXXX",
  "order_id": "182367r12831t29b",
  "merchant_usn": "92837429837",
  "timestamp": "1605034925174"
}

Payload Base64:

{TOKEN_JWT_EXAMPLE}

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

{
  "merchant_id": "XXXXX",
  "merchant_key": "XXXXXXXXXXXXXXX",
  "timestamp": "1605034925174"
}

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

{
  "merchant_id": "XXXXX",
  "merchant_key": "XXXXXXXXXXXXXXX",
  "registered_merchant_id": "YYYYYYY",
  "timestamp": "1605034925174"
}

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_id e merchant_usn nã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:

{
  "merchant_id": "XXXXX",
  "merchant_key": "XXXXXXXXXXXXXXX",
  "order_id": "182367r12831t29b",
  "merchant_usn": "92837429837",
  "timestamp": "1605034925174"
}

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:

{
  "nit": "asdfghjk12345678asdfghjk12345678asdfghjk12345678asdfghjk12345678",
  "merchant_id": "XXXXX",
  "merchant_key": "XXXXXXXXXXXXXXX",
  "timestamp": "1605034925174"
}

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:

{TOKEN_JWT_EXAMPLE}

Por fim, uma criptografia RSA, usando a chave privada loja, deve ser feita neste conteúdo. Exemplo:

SIGNATURE_EXAMPLE_DO_NOT_USE_IN_PRODUCTION

Assinatura final

A assinatura final é a concatenação das 3 partes separadas por ("."):

{TOKEN_JWT_EXAMPLE}

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. "Jwt" -no-filter

Caso a chave pública não esteja válida a mensagem "Invalid Signature" será exibida. "Jwt" -no-filter