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:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9

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:

eyJtZXJjaGFudF9pZCI6IlhYWFhYIiwibWVyY2hhbnRfa2V5IjoiWFhYWFhYWFhYWFhYWFhYIiwib3JkZXJfaWQiOiIxODIzNjdyMTI4MzF0MjliIiwibWVyY2hhbnRfdXNuIjoiOTI4Mzc0Mjk4MzciLCJ0aW1lc3RhbXAiOiIxNjA1MDM0OTI1MTc0In0

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âmetroDescriçãoFormatoObrigatório
merchant_idCódigo da loja no Carat.= 15 ANSIM
merchant_keyChave de autenticação da loja no Carat.< 80 ANSIM
timestampRepresentação em milissegundos do momento de geração da assinatura. Enfatizando que o campo timestamp possui um limite de validade de 10 minutos.< 13 NSIM
{
"merchant_id": "XXXXX",
"merchant_key": "XXXXXXXXXXXXXXX",
"timestamp": "1605034925174"
}

Serviços de edição e consulta de loja#

ParâmetroDescriçãoFormatoObrigatório
merchant_idCódigo da loja no Carat. Os códigos de produção e certificação serão diferentes.= 15 ANSIM
merchant_keyChave de autenticação da loja no Carat. As chaves de produção e certificação serão diferentes.< 80 ANSIM
timestampRepresentação em milissegundos do momento de geração da assinatura. Enfatizando que o campo timestamp possui um limite de validade de 10 minutos.< 13 NSIM
registered_merchant_idCódigo da loja criada ou a ser criada no Carat. Os códigos de produção e certificação serão diferentes.= 15 ANSIM
{
"merchant_id": "XXXXX",
"merchant_key": "XXXXXXXXXXXXXXX",
"registered_merchant_id": "YYYYYYY",
"timestamp": "1605034925174"
}

Serviços de criação de transação#

ParâmetroDescriçãoFormatoObrigatório
merchant_idCódigo da loja no Carat. Os códigos de produção e certificação serão diferentes.= 15 ANSIM
merchant_keyChave de autenticação da loja no Carat. As chaves de produção e certificação serão diferentes.< 80 ANSIM
order_idCódigo do pedido definido pelo lojista.< 40 ANCondicional
merchant_usnNúmero sequencial único para cada pedido, criado pela loja.< 12 NCondicional
timestampRepresentação em milissegundos do momento de geração da assinatura. Enfatizando que o campo timestamp possui um limite de validade de 10 minutos.< 13 NSIM

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âmetroDescriçãoFormatoObrigatório
nitIdentificador da transação no Carat.= 64 ANSIM
merchant_idCódigo da loja no Carat. Os códigos de produção e certificação serão diferentes.= 15 ANSIM
merchant_keyChave de autenticação da loja no Carat. As chaves de produção e certificação serão diferentes.< 80 ANSIM
timestampRepresentação em milissegundos do momento de geração da assinatura. Enfatizando que o campo timestamp possui um limite de validade de 10 minutos.< 13 NSIM

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:

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJtZXJjaGFudF9pZCI6IlhYWFhYIiwibWVyY2hhbnRfa2V5IjoiWFhYWFhYWFhYWFhYWFhYIiwib3JkZXJfaWQiOiIxODIzNjdyMTI4MzF0MjliIiwibWVyY2hhbnRfdXNuIjoiOTI4Mzc0Mjk4MzciLCJ0aW1lc3RhbXAiOiIxNjA1MDM0OTI1MTc0In0

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

LLQ2kaC3dG0tsu78JyEIbvd8c1G05lo-1qLDBb0lBXsS2lrJ98-rcusEhuodhHDBE701a_RZwCfOH9ebPZXYdEtuLldqp_Q47y_AYOBYuz3eexuVC0sH3MvmljjHEiMYEIKtFyhsSFrBuQBFvBOT4tJCA779j_cP-JnW4MeDazDehsydEa6phsmkGg_0YfN2xdRzaaTrQqldYibUeI7_YEwLTYrZg0Ys7r45quT7veAzNFLEL4I3iJmMJUcBaCfIQl6NKvX7meoSBeFBaj_MRw8WwXnNTjCFXjU6w_iUiYPg0VVAAKGaEYKP7sHUcw1hn-BawMDMorLcvT9YwP4OxQ

Assinatura final#

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

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJtZXJjaGFudF9pZCI6IlhYWFhYIiwibWVyY2hhbnRfa2V5IjoiWFhYWFhYWFhYWFhYWFhYIiwib3JkZXJfaWQiOiIxODIzNjdyMTI4MzF0MjliIiwibWVyY2hhbnRfdXNuIjoiOTI4Mzc0Mjk4MzciLCJ0aW1lc3RhbXAiOiIxNjA1MDM0OTI1MTc0In0.LLQ2kaC3dG0tsu78JyEIbvd8c1G05lo-1qLDBb0lBXsS2lrJ98-rcusEhuodhHDBE701a_RZwCfOH9ebPZXYdEtuLldqp_Q47y_AYOBYuz3eexuVC0sH3MvmljjHEiMYEIKtFyhsSFrBuQBFvBOT4tJCA779j_cP-JnW4MeDazDehsydEa6phsmkGg_0YfN2xdRzaaTrQqldYibUeI7_YEwLTYrZg0Ys7r45quT7veAzNFLEL4I3iJmMJUcBaCfIQl6NKvX7meoSBeFBaj_MRw8WwXnNTjCFXjU6w_iUiYPg0VVAAKGaEYKP7sHUcw1hn-BawMDMorLcvT9YwP4OxQ

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. &quot;Jwt&quot; -no-filter

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