Guia de Suporte OAuth

Visão Geral#

Algumas instituições financeiras exigem um fluxo de autorização OAuth para conectar contas de usuários. Este guia explica como configurar corretamente o widget Pluggy Connect para lidar com redirecionamentos OAuth em diferentes plataformas e dispositivos.

Seguindo estas diretrizes, você pode garantir uma experiência de integração OAuth tranquila para seus usuários em várias plataformas e dispositivos.

O que o OAuth muda para sua integração#

OAuth é um padrão de delegação de acesso: em vez de digitar credenciais em seu aplicativo, o usuário o autoriza dentro da própria interface da instituição e a instituição emite um token. Duas coisas decorrem disso, e ambas são o motivo pelo qual esses conectores precisam de configuração extra do seu lado:

• O usuário sai do seu aplicativo — ele se autentica na instituição e precisa ser trazido de volta. Essa viagem de retorno é para isso que serve o oauthRedirectUri.
• A conexão é renovada sem pedir novamente. Um token OAuth pode ser renovado, então a conexão permanece ativa sem enviar o usuário pelo login a cada vez — o que também é o motivo pelo qual essas conexões tendem a quebrar menos do que as baseadas em credenciais.

A única coisa que geralmente dá errado é a viagem de retorno. Alguns navegadores móveis não permitem que a janela de autorização se feche sozinha, e sem um URI de redirecionamento, o usuário fica encarando uma página de autorização finalizada sem caminho de volta para seu aplicativo.

Configurando o URI de Redirecionamento OAuth#

Para lidar com redirecionamentos após o processo OAuth, você precisa definir um oauthRedirectUri. Este URI é usado para redirecionar os usuários de volta ao seu aplicativo após terem concluído o processo OAuth com a instituição financeira.

Requisitos#

O oauthRedirectUri deve cumprir as seguintes regras:

• Deve ser HTTPS ou um deep link
• Não pode ser localhost ou 127.0.0.1

Criando um Connect Token com Redirecionamento OAuth#

Ao criar um Connect Token, inclua o oauthRedirectUri nas opções:

curl --request POST \
  --url https://api.pluggy.ai/connect_token \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --data '{
    "options": {
      "clientUserId": "your-user-id",
      "oauthRedirectUri": "https://your-own-url.com"
    }
  }'

Nota: Se você criar um item com um Connect Token e também especificar o oauthRedirectUri no momento da criação do item, o sistema priorizará o parâmetro oauthRedirectUri fornecido no nível do item.

Exemplos de URIs de redirecionamento#

Testando localmente, use o esquema de deep link do seu aplicativo ou um túnel HTTPS para sua máquina — um URI localhost é recusado quando o token é criado, não depois.

Comportamento Específico do Navegador#

O fluxo OAuth se comporta de maneira diferente dependendo da plataforma do usuário:

Navegadores de Desktop#

Para navegadores de desktop, a janela de autorização tentará fechar automaticamente após a conclusão do processo OAuth.

Se fechar a janela não for possível, o usuário será redirecionado para o oauthRedirectUri fornecido.

Navegadores Móveis#

Para navegadores móveis, os usuários serão redirecionados para o oauthRedirectUri após completar a autorização OAuth.

Alguns navegadores móveis não permitem fechar a janela de autorização OAuth após a conclusão. Para resolver isso, você deve fornecer um oauthRedirectUri na solicitação do Connect Token, que será usado para redirecionar os usuários de volta ao seu aplicativo.

Lidando com o Redirecionamento#

Seu aplicativo deve estar preparado para lidar com o redirecionamento de volta para o oauthRedirectUri. Quando o usuário for redirecionado, você deve:

1. Verificar o status da conexão
2. Retomar a experiência do usuário em seu aplicativo
3. Lidar com quaisquer erros que possam ter ocorrido durante o processo OAuth

Considerações sobre a Plataforma#

Aplicativos Web#

Para aplicativos web, o oauthRedirectUri deve ser um URL HTTPS válido que aponte para uma página em seu aplicativo que possa lidar com o redirecionamento e retomar o fluxo de conexão.

Aplicativos Móveis (Nativos)#

Para aplicativos móveis nativos, você pode usar um deep link como o oauthRedirectUri. Isso permite que o fluxo OAuth redirecione de volta para seu aplicativo nativo após a autorização ser concluída.

Certifique-se de que seu aplicativo esteja devidamente configurado para lidar com o esquema de deep link tanto no iOS quanto no Android.

React Native / Flutter#

Ao usar React Native ou Flutter com o Pluggy Connect SDK, configure o oauthRedirectUri para usar o esquema de deep link do seu aplicativo. O SDK lidará com o redirecionamento e retomará o fluxo de conexão dentro do widget.

Integração Backend, sem o widget#

Se você criar itens a partir do seu próprio backend em vez de através do widget, você não precisa de um Connect Token: autentique-se com sua chave de API e passe oauthRedirectUri para items-createAPI, exatamente como você faria nas opções do token.

curl --request POST \
  --url https://api.pluggy.ai/items \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --data '{
    "connectorId": 600,
    "parameters": {
      "user": "user-ok",
      "password": "password-ok"
    },
    "oauthRedirectUri": "https://your-own-url.com"
  }'

A resposta traz a URL OAuth para enviar o usuário. Quando um valor é dado em ambos os lugares — nas opções do Connect Token e na criação do item — o que está no item vence, porque é o mais específico dos dois.

Melhores Práticas#

• Sempre forneça um oauthRedirectUri quando seus usuários puderem se conectar a instituições que usam OAuth
• Use URLs HTTPS para aplicativos web e deep links para aplicativos móveis nativos
• Teste o fluxo OAuth em navegadores de desktop e móveis para garantir uma experiência tranquila
• Lide com casos extremos onde a janela de autorização não pode ser fechada automaticamente
• O connectToken é válido por 30 minutos apenas — o uso recomendado é um token por conexão