Fluxos de Autorização e Autenticação

Protocolo OAuth2

O Oauth2 é um protocolo de autorização muito utilizado na indústria de tecnologia. Ele permite que uma aplicação se autentique na outra de forma segura. Esse protocolo soluciona justamente o cenário que iremos precisar aqui, afinal precisaremos que sua aplicação converse com a nossa aplicação da Cora. Para que sejam validadas essas trocas de informações, os sistemas precisam confiar um no outro. Para estabelecer esse vínculo de confiança utilizamos 2 dos fluxos definidos pelo protocolo OAuth2, o Authorization Code Flow(incluir link) e o Client Credentials.

Considerações importantes

Tempo para expirar o Access Token 24 horas

Tempo para expirar o Refresh Token Não expira.

Utilizações do Refresh Token O Refresh Token pode ser utilizado apenas 3 vezes. Após a terceira utilização ele será invalidado.

Tempo para expirar a sessão do Cliente Final O Cliente Final perderá a sessão após 60 dias de inatividade. Perder sessão significa que o access_token e o refresh_token irão expirar. Dessa maneira, o cliente precisará fazer o fluxo de autorização novamente.

Authorization Code

Como o próprio nome já diz, esse é um fluxo de autorização que produzirá como resultado um token de acesso ao sistema desejado, ou seja, o seu sistema terá acesso as APIs da Cora se percorrer com sucesso esse fluxo.

Para que é utilizado esse fluxo?

É utilizado para que o Cliente Final dê o consentimento para a Empresa Parceira possa executar ações na conta deste cliente. Após o consentimento a empresa parceira terá acesso por exemplo a artefatos de cobrança, pagamentos, além de dados sensíveis do Cliente Final.

Mas como funciona na prática?

Há várias descrições bem completas na internet, sobre os atores participantes do fluxo e diagramas de sequência, porém resolvemos simplificar no diagrama abaixo.

Vamos adotar algumas premissas para facilitar o exemplo:

• O nome do seu sistema é SISPAR

• Você deseja disponibilizar a emissão de boletos da Cora dentro de seu sistema

Legenda do diagrama API de Boleto - API responsável pela geração do artefato de cobrança do tipo boleto AS_Cora - Authorization Server da Cora. Ele é o responsável por conceder e gerenciar os tokens de acesso do cliente na Cora Cliente Corajoser - É o usuário do seu sistema e também é cliente da Cora. SISPAR - Authorization Server da Cora. Ele é o responsável por conceder e gerenciar os tokens de acesso do cliente na Cora

Bora pro código

Premissas Para percorrer o fluxo e acessar as nossas APIs da Cora, você (Empresa parceira) precisa ter as credenciais. Saiba como solicitar as credenciais de acesso.

Para exemplificar, iremos listar alguns parâmetros fictícios:

• Client-id: app-teste-doc
• Redirect URI: https://exemplo.com.br
• scopes: invoice, account, payment

Como você pôde perceber no diagrama, há 4 retângulos envolvendo algumas ações entre os atores. Abaixo, iremos listar e detalhar os passos na ordem correta.

1. Redirecionamento

Para direcionar o cliente para a Cora, é preciso que você monte o link com os parâmetros específicos de seu sistema. Veja só como ficaria o link para o client-id de exemplo:

https://api.stage.cora.com.br/oauth/authorize?client_id=app-teste-docs&response_type=code&redirect_uri=https://exemplo.com.br&scopes=invoice%20account%20payment

Tabela explicativa dos parâmetros:

Gestão de escopos

2. Autorização

Após ser redirecionado para a Cora, o Cliente Final precisa fazer login e autorizar o sistema da Empresa Parceira nos escopos solicitados. Trouxemos ao lado as telas que o Cliente Final verá no processo.

3. Volta para o sistema

Após a etapa anterior o Cliente Final é direcionado de volta para o sistema da Empresa Parceira e enviaremos como parâmetro da url, um código que a Empresa Parceira irá utilizar para pegar os tokens de acesso às APIs da Cora.

Trouxemos abaixo um exemplo de como virá o parâmetro code na URL:

https://exemplo.com.br/?session_state=18dc33de-d69f-4c16-ac1f-c1d0ac075712&code=006081d3-9f5a-41ac-80b1-c64888962332.18dc33de-d69f-4c16-ac1f-c1d0ac075712.3cfcfebb-6d4a-4845-91f9-d01572e8ce69

Tabela explicativa dos parâmetros:

4. Autenticação

Com o parâmetro code capturado na URL de redirecionamento, será preciso fazer uma requisição para nosso Servidor de Autorização para solicitar os tokens de acesso. Veja abaixo um exemplo dessa requisição:

cURL de exemplo:

curl --location --request POST 'https://api.stage.cora.com.br/oauth/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic YXBwLXRlc3RlLWRvYzo4MWQyMzFmNC1mOGU1LTRiNTItOWMwOC0yNGRjNDUzMjFhMTYK' \
--data-urlencode 'grant_type=authorization_code' \
--data-urlencode 'code={{auth_code}}' \
--data-urlencode 'redirect_uri=https://exemplo.com.br'

Aqui temos algumas informações novas, vamos explicá-las na tabela abaixo:

Campo Authorization no header

Esse campo é a uma concatenação de duas Strings. A primeira string "Basic" é fixa, mas a segunda é a junção de suas credenciais codificadas em base64. Trouxemos o exemplo:

Para verificar se o código está correto, você pode executar o seguinte comando no terminal de seu computador, para fazer o encode em base64

echo "app-teste-doc:81d231f4-f8e5-4b52-9c08-24dc45321a16" | base64

Após enviar a requisição o Servidor de Autorização da Cora responderá com a seguinte mensagem:

{
    "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJPUXhETFpxNmFJb1EzS1Q0dWFEWWhQai1IUUVpMm5iNGl1WEdWV0diVWh3In0.eyJleHAiOjE2NjM3Nzk5NTgsImlhdCI6MTY2MzY5MzU1OCwiYXV0aF90aW1lIjoxNjYzNjkzNTI5LCJqdGkiOiJiMDYzYjJhNi03OTdiLTQ4ZjQtYjQyMi1lYzczNTY4Yjc3ZGYiLCJpc3MiOiJodHRwczovL2F1dGguc3RhZ2UuY29yYS5jb20uYnIvcmVhbG1zL2NvcmEiLCJzdWIiOiJhcHAtYmVja2VyZXAiLCJ0eXAiOiJCZWFyZXIiLCJhenAiOiJhcHAtYmVja2VyZXAiLCJzZXNzaW9uX3N0YXRlIjoiZDhlNzhmYTAtNWRlMi00MDE4LTkwOWItNDNjZjQ2YTYwMWVhIiwiYWNyIjoiMSIsInNjb3BlIjoib2ZmbGluZV9hY2Nlc3MiLCJzaWQiOiJkOGU3OGZhMC01ZGUyLTQwMTgtOTA5Yi00M2NmNDZhNjAxZWEiLCJjbnBqIjoiMTA4MTA4MzAwMDAxMzgiLCJidXNpbmVzc19pZCI6Ijc3Njc3Nzk0LTdkNWMtNGQ1YS1iYjdlLWE4MmE0NGU4ZDEzMCIsInBlcnNvbl9pZCI6IjQwNzFmMGZjLTk1MzctNDVhOC05ZWY2LTc3NDdjNTBmODM1YyJ9.R6oTl-Sb2N5brQh6qe9VB6pH7MOfneDAxpoC_cA3Hba7kzjG8RUlmDlOhciRgVbhmQKbwJlsEUpFbvKIwlr3GoPmnxIOTFihIfEG4xQ8eLw1275t8_dPyRy8DoLQF2GLYcFPIRHoxH2FXH5bzRu6D2n2G50SKgVJyhT_KegVEqAPcQq9Aii1FNGDGgt8qp2mbDiWq3B199QF7NkJFeo50qllflfVN5t7gCOonNfzhTLJAJ-KZuHA4__bwXxeKD9TI0rd4_gloHIxziTRqhkPjEBHAW8iLLI7REkOMvW8wFYegTbZSqhhAz7pEJnMAJq06MmVTPQmlq1_gg_THmY4AA",
    "expires_in": 86400,
    "refresh_expires_in": 0,
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICI5Y2JjMzEyZS04ODA2LTRiM2UtOWExMi1jMjg0NGQ2MjM0YjcifQ.eyJpYXQiOjE2NjM2OTM1NTgsImp0aSI6IjRlZDFmYzEzLTIyZjctNDU4Yy05Mzg2LWFkZTU5OTg1ZDNhYSIsImlzcyI6Imh0dHBzOi8vYXV0aC5zdGFnZS5jb3JhLmNvbS5ici9yZWFsbXMvY29yYSIsImF1ZCI6Imh0dHBzOi8vYXV0aC5zdGFnZS5jb3JhLmNvbS5ici9yZWFsbXMvY29yYSIsInN1YiI6ImFwcC1iZWNrZXJlcCIsInR5cCI6Ik9mZmxpbmUiLCJhenAiOiJhcHAtYmVja2VyZXAiLCJzZXNzaW9uX3N0YXRlIjoiZDhlNzhmYTAtNWRlMi00MDE4LTkwOWItNDNjZjQ2YTYwMWVhIiwic2NvcGUiOiJvZmZsaW5lX2FjY2VzcyIsInNpZCI6ImQ4ZTc4ZmEwLTVkZTItNDAxOC05MDliLTQzY2Y0NmE2MDFlYSJ9.c864NeMer1njXuoQ2m7YZQgvegLuOK5UpsshFWH8DOk",
    "token_type": "Bearer",
    "not-before-policy": 1614056798,
    "session_state": "d8e78fa0-5de2-4018-909b-43cf46a601ea",
    "scope": "offline_access"
}

Após receber o par de tokens é imprescindível que tanto o access_token quanto o refresh_token sejam persistidos, pois são eles que serão usados em nossas APIs.

Tabela explicativa dos campos da resposta

Importante Apesar de terem o mesmo nome, o campo scope na resposta abaixo não tem relação com os escopos solicitados e configurados no link de permissão (invoice, payment, transfer e etc)

5. Consumo do recurso

No diagrama de exemplo, colocamos como objetivo final o consumo da API de emissão de Boleto, mas poderia ser qualquer um dos recursos que temos disponíveis e que tem como exigência o Access Token, pois trafegam dados sensíveis de nossos Clientes Finais.

Veja a cURL de exemplo com parte da requisição para emissão de Boleto:

curl --location --request POST 'https://api.stage.cora.com.br/invoices' \
--header 'Idempotency-Key: 33766506-1850-42f6-a96a-bf2c67adb0e8' \
--header 'Authorization: Bearer {{access_token}}' \
--data-raw '{
	"code": "meu_id",
	 ...
	}
}'

Perceba que é nesse momento que você irá utilizar o Access Token que seu sistema acabou de gerar. No header Authorization será necessário concatenar a String "Bearer" com o Access Token recebido: Bearer {{access_token}}

6. Renovação do Token

O Access Token é o elemento essencial. Sem ele não é possível acessar as APIs da Cora. Porém, ele tem um prazo relativamente curto para expirar (24 horas). Dessa maneira será preciso renová-lo constantemente.

O fluxo de renovação de token é muito simples. Basta fazer uma requisição utilizando o refresh_token que foi retornado na Autenticação (Passo 4).

Trouxemos como ficaria a requisição abaixo:

curl --location --request POST 'https://api.stage.cora.com.br/oauth/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic Base64(SEU_CLIENT_ID:SEU_CLIENT_SECRET)' \
--data-urlencode 'grant_type=refresh_token' \
--data-urlencode 'refresh_token={{refresh_token}}'

Os campos Authorization e Content-Type também já foram mencionados no passo de Autenticação, porém há mudanças no corpo da mensagem

Após enviar a requisição acima, o nosso Servidor de Autorização irá responder a mesma mensagem do passo de Autenticação (Passo 4).

Agora é hora do Café! Sim, finalizamos a etapa de Authorization Code