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
Updated 6 days ago