Obtendo um Access Token com Auth Code Flow

Bem vindo, desenvolvedor! Nessa seção nós vamos aprender a gerar o nosso primeiro Access Token! com Authorization Code para consumir as APIs do BTG PACTUAL EMPRESAS! Espero que você já tenha criado o seu primeiro Aplicativo para que possa acompanhar o conteúdo de forma satisfatória!

O Access Token obtido por meio do Auth Code Flow dá acesso às informações que o usuário concordar compartilhar, portanto, ele é o token NECESSÁRIO para consumir as APIs de banking!

Este tutorial é válido para ambos os ambientes de Sandbox e Produção então não se preocupe caso ainda não tenha tido seu Aplicativo Verificado.

Segurança

Lembre-se sempre que algumas informações são confidenciais e em nenhum momento elas serão necessárias para que possamos resolver quaisquer problemas que você possa encontrar. Portanto, é extremamente importante que sempre ofusque informações como o Secret, Access Token...

Todas as informações sensiveis neste tutorial estarão ofuscadas.

Área do Desenvolvedor

A nossa primeira parada é na Área do desenvolvedor, onde se espera que você já tenha um aplicativo criado conforme Criação de Aplicativos para consumir o serviço de APIs.

Com seu aplicativo já criado, você deverá encontrar um aplicativo semelhante a este nos seus aplicativos:

Aqui nós navegaremos até os três pontos na direita e clicaremos neles:

Ao clicar em detalhes, encontraremos a seguinte página:

Aqui algumas coisas nos interessam nesse primeiro momento de desenvolvimento

Chaves: Aqui é onde estarão o Client Id e Client Secret do seu aplicativo.
Versôes: Aqui é onde você verá as edições realizadas no seu aplicativo e os detalhes da versão atual do seu aplicativo. Clicando em "ver detalhes" da versão atual, você encontrará um resumo do estado do seu aplicativo. Aqui nós queremos a URI de redirecionamento que cadastramos e os Escopos que selecionamos na criação.

Escopos

O escopo openid é obrigatório, mas os outros você deverá escolher conforme as necessidade do seu sistema pois eles definem quais APIs o seu sistema terá acesso.

Tendo definidos os nossos escopos e nossa URI de redirecionamento, vamos começar a preparar o nosso ambiente para realizar nossas requisições!

Fluxos de autenticação

É interessante que você visite nossas páginas sobre os Fluxos que utilizaremos aqui para que entenda melhor quais são os protocolos, mas basicamente nossos servidores utilizam o Oauth2.0!

Postman

Muitas ferramentas podem ser utilizadas, desde mais genéricas como o Insomnia e Postman até ferramentas especificas como o Oauth tools. Aqui no tutorial, vou utilizar a extensão do Postman para o VS code, mas o mesmo processo pode ser feito em qualquer uma dessas ferramentas!

Configurando o ambiente

Vamos criar variáveis de ambiente para facilitar o nosso processo e ao mesmo tempo facilitar a visualização de qual informação está indo onde. Eu optei por criar um ambiente chamado "Tutorial-Access_token_ambiente" e lá criei as seguinte váriaveis:

E as preenchi da seguinte forma:

base_uri: https://id.sandbox.btgpactual.com
client_id: Client Id que está na Área do Desenvolvedor
scope: escopos que selecionei na Área do Desenvolvedor, nesse caso openid
prompt: por padrão mantive login
redirect_uri: https://localhost.com a nossa URI fictícia

Nosso ambiente, então, ficou assim:

Com isso nós podemos dar inicio ao nosso fluxo!

Authorization code

Aqui é o primeiro passo para obtermos nosso tão almejado Access Token e finalmente acessar as APIs. Nessa etapa nós enviamos para o servidor de autenticação algumas informações e ele nos devolve um authorization code referente a isso!
No postman, nós montamos a URI de acordo com a descrita na nossa página sobre o fluxo de Authorization Code e ela fica da seguinte forma:

Depois disso, pegamos o cURL clicando em "code":

E utilizaremos a url no navegador, como se tivesse clicado em um link ou então como se um botão no seu sistema no tivesse levado a ele para darmos inicio no fluxo de access grant:

É só fazer login com sua conta do BTG Pactual Empresas.

Aqui é onde aparecem os escopos que você incluiu no fluxo. A cada escopo adicionado, um item referente a ele aparecerá no fluxo. Neste observe que temos o Open Id referente ao escopo openId e um escopo adicional que incluimos apenas para demonstrar como funciona quando possuimos mais de um escopo.

Após confirmar, você será levado para a sua redirect_uri, que será no nosso caso uma página não encontrada, porém ao olharmos na URL do navegador:

Temos o nosso Authorization Code(tudo entre "?code=" e "&"). Esse nós copiamos e poderemos dar inicio ao fluxo do Access Token.

Consentimento

O consentimento é um ponto que difere o ambiente de sandbox do ambiente de produção. Em sandbox, pelo ambiente não possuir conexão com as bases de dados reais, você terá apenas a empresa de sandbox do BTG Pactual Empresas para selecionar.

No ambiente de produção, por outro lado, é possível e obrigatório que seja emitido um consentimento para uma empresa real.

Uma lista de empresas em que você é usuário aparecerá logo após a confirmação dos escopos. Nesta lista é possível selecionar apenas uma empresa. Sendo assim, a relação entre token e empresa é de Um para Um. Caso tenha mais de uma empresas que deseja operar, deverá administrar um token por empresa.

Access Token

O Access Token obtemos ao realizar uma requisição POST enviando o Authorization Code e algumas de nossas credenciais conforme nossa página sobre o fluxo:

Depois disso, precisamos configurar o protocolo de autenticação:

Utilizamos o esquema básico de autenticação:

Username é o nosso client_id configurado no ambiente
Password é o nosso Secret que fica lá na Área do Desenvolvedor

Caso opte por fazer de maneira programática é preciso encodar em base64 uma string que consista de client_id:client_secret

Agora, configuramos o body da request:

É extremamente importante que seja enviado como form-urlencoded!
O campo code é onde colocamos o nosso Authorization code obtido anteriormente e o campo grant_type não precisamos nos preocupar, basta por conforme a documentação mostra.

Basta enviarmos a request que receberemos de volta o nosso Access Token:

E é assim, desenvolvedor, que obtemos o Access Token por meio do Authorization Code Flow!

Postman

Temos uma collection do postman com todas as requests mais utilizadas e demandadas pelos nossos clientes. Para encontra-lá basta visitar nossa página Postman Collections