IMPORTANTE: esta documentação foi descontinuada. Leia a documentação Nova arquitetura OAuth atualizada no nosso novo portal de documentação.
O OAuth2 é um protocolo padrão para autorização comumente utilizado por APIs web. Para realizar integrações que utilizem o OAuth2, basta logar-se em um provedor - podendo ser o Google, Microsoft, Mercado Livre, Amazon, etc. - e receber um token de acesso. Através deste token, é possível acessar os dados de um usuário sem precisar informar suas credenciais.
Para adicioná-lo em nossa Plataforma, é necessário criar previamente uma aplicação no provedor que deseja utilizar. Uma vez criada a aplicação no provedor, será possível cadastrar e utilizar o protocolo OAuth2 na Plataforma Digibee.
1. Cadastrando um novo provedor OAuth a partir de um provedor existente
Para criar a sua aplicação, siga as instruções de acordo com o provedor que deseja adicionar à Plataforma clicando nos links abaixo:
No campo Redirect URI, será preciso utilizar o seguinte endereço:
Para SaaS: https://www.godigibee.io/oauth2/success
Para SaaS dedicado: https://www.${DEDICATED_SAAS_HOST}/oauth2/success
Criada a aplicação, você terá em mãos o Client ID e o Client Secret, que são as chaves de autenticação do OAuth que deverão ser informados posteriormente durante a criação do novo provedor, em uma conta da Plataforma Digibee (vide o tutorial ao final deste artigo).
2. Como funciona a obtenção do token?
Para explicar a obtenção do token, iremos utilizar o fluxo do Google, que é o mesmo para todos os provedores OAuth2 que seguem o fluxo Code Grant Type:
O primeiro passo é requisitar um token intermediário. Isso ocorre quando o usuário, durante o login, aceita os escopos e permite o uso dos seus dados;
Após o consentimento por parte do usuário, é gerado um token intermediário (chamado code) que será utilizado para retornar o access token, o qual é o token final;
Com o access token em mãos, é possível realizar os chamados para os serviços do provedor.
3. Como funciona a duração do token?
O tempo de expiração do access token é dado pela propriedade expires_in. Por exemplo, o valor "7200" indica que o token de acesso irá expirar em duas horas a partir do momento em que a resposta foi gerada.
No que se refere aos provedores cadastrados pela Digibee, temos os seguintes tempos de expiração:
6 meses de duração para o Google e Mercado Live;
3 meses de duração para a Microsoft.
IMPORTANTE: É necessário realizar um novo login na tela de contas depois que o refresh token expirar.
4. O que fazer caso o refresh token não seja retornado?
O refresh token pode não retornar por diversos motivos, mas são frequentes os casos em que ele não é retornado devido ao número excessivo de logins. Caso a sua nova conta não tenha sido salva pelo refresh token, você deverá remover a app OAuth2 da sua conta de e-mail de acordo com as diretrizes do provedor utilizado para fazer login na Plataforma. Para saber como, acesse o link abaixo:
Após isso, é necessário realizar o login no provedor através da Plataforma Digibee novamente e, por fim, salvar a sua conta.
5. Como solicitar novos provedores?
Para solicitar um provedor inexistente em nossa lista, entre em contato conosco através do chat da Plataforma Digibee. Assim, poderemos adicioná-lo manualmente.
6. Como utilizar o token no pipeline?
Uma vez que a conta oauth-2 esteja criada dentro da Plataforma, basta usá-la no campo Account selecionando o conector Rest V2 no canvas. Também é necessário informar a URL do serviço a ser chamado, headers e query parameters necessários para que a chamada seja feita utilizando os tokens de acesso gerados.
Exemplos de chamadas:
Google:
Chamando a API de listagem de arquivos do Google Drive no componente Rest V2:
Verb: GET
Microsoft
Chamando a API de listagem de arquivos do OneDrive no componente Rest V2:
Verb: GET
Mercado Livre:
Chamando a API que retorna informações sobre sua conta no Mercado Livre:
Verb: GET
IMPORTANTE: Uma vez que a conta OAuth criada anteriormente seja informada no campo Account do componente Rest V2, o cabeçalho Authorization será adicionado automaticamente.
Uma vez criada a aplicação no provedor, será possível cadastrar seu novo provedor OAuth2 na Plataforma Digibee seguindo o tutorial Cadastro de novos provedores.