Visão geral
Bem-vindo a uma exploração do OAuth 2.0, um protocolo de autenticação poderoso, mas muitas vezes mal compreendido, no universo do Tulip. Neste artigo, vamos desvendar os fundamentos, orientá-lo pelos fluxos de autenticação suportados pelo Tulip, esclarecer a configuração do seu conector inicial e compartilhar dicas rápidas para um início sem complicações.
Para saber como o Tulip lida com tokens de atualização, gerenciamento de escopo e público-alvo, além de configurações de conectores personalizados, consulte a seção Detalhes técnicos.
Tipos de autenticação
O Tulip oferece suporte a três tipos de autenticação OAuth 2.0: OAuth 2.0 (Conta de Serviço), OAuth 2.0 (Credenciais do Usuário) e OAuth 2.0 (Credenciais do Cliente). A principal diferença está na forma como as credenciais são compartilhadas entre os usuários e no fluxo executado de acordo com a especificação OAuth. Uma lista completa e uma descrição dos fluxos exclusivos do OAuth estão disponíveis aqui: https://frontegg.com/blog/oauth-flows.
In older Tulip versions, OAuth2.0 (Service Account) was called OAuth2 (Admin), and OAuth2.0 (User Credentials) was called OAuth2 (Operator).
Fluxo de código de autorização:
- OAuth 2.0 (Conta de Serviço): utiliza as credenciais fornecidas durante os testes do conector para todos os usuários no Tulip Player. Ideal para credenciais compartilhadas em toda a sua organização. É necessária uma reautenticação do administrador caso as credenciais expirem.
- OAuth 2.0 (Credenciais do usuário): segmenta a autenticação com base no usuário conectado ao Tulip Player. Se um usuário não tiver se autenticado ou se a autenticação expirar, ele passará pelo fluxo OAuth dentro do Tulip Player.
Fluxo de credenciais do cliente:
- OAuth 2.0 (Credenciais do Cliente): Esse tipo de concessão é usado pelo Tulip para obter um token de acesso por meio da autenticação no servidor de autorização usando as credenciais do cliente (ID do cliente e segredo do cliente), normalmente para acessar recursos em nome do próprio cliente, e não em nome de um usuário.
Antes de nos aprofundarmos nos detalhes, sugerimos que você se familiarize com os Ambientes e obtenha uma visão geral dos Hosts de Conectores e suas funções.
O OAuth 2.0 funciona como um mecanismo para que o Tulip (o cliente) comprove sua identidade junto aos sistemas da sua empresa.
Fluxo de código de autorização
:::(Aviso) (Aviso)
Para concluir o processo de autenticação do usuário, seu navegador precisa permitir janelas pop-up. Se o seu connector estiver configurado com vários ambientes, cada ambiente abrirá uma janela pop-up separada durante a autenticação.
Verifique se as janelas pop-up estão habilitadas no Chrome:
- Abra o Chrome e clique no menu de três pontos no canto superior direito da janela.
- Selecione “Configurações” no menu suspenso.
- Role a página para baixo e clique em “Privacidade e segurança”.
- Na seção “Privacidade e segurança”, clique em “Configurações do site”.
- Role a página para baixo e clique em “Janelas pop-up e redirecionamentos”.
- Verifique se a opção está configurada para permitir pop-ups ou adicione manualmente o site à lista de sites autorizados a exibir pop-ups.
Se os pop-ups estiverem bloqueados, o Chrome exibirá um pequeno ícone na barra de endereços sempre que um pop-up for bloqueado. Você pode clicar nesse ícone para permitir rapidamente os pop-ups do Tulip.
:::
O acesso é concedido por meio de um handshake, e o Tulip oferece suporte principalmente ao Fluxo de Código de Autorização, o fluxo OAuth mais comum. Aqui está uma visão geral resumida de como esse fluxo se desenrola:
- O usuário inicia o fluxo clicando no botão “Testar” antes de salvar um conector.
- O Tulip se comunica com o servidor de autorização do seu provedor OAuth, compartilhando parâmetros específicos, como identidade do cliente, escopos (o que você está tentando acessar) e outros detalhes relevantes.
- O servidor de autorização solicita que o usuário conceda acesso, conforme exemplificado abaixo:
- Após o consentimento do usuário, o servidor de autorização gera um código de autorização e encerra a janela de autenticação.
- Com o código de autorização em mãos, o Tulip solicita um token de forma segura, acessando o endpoint de token e fornecendo o código de autorização, o ID do cliente, o segredo do cliente e propriedades adicionais.
- Após validar o código de autorização, o servidor responde com um token e, opcionalmente, um token de atualização. Esse token serve para solicitações autorizadas pelo usuário.
- O Tulip agora pode executar solicitações em nome dos usuários, utilizando o token fornecido para autorização.
Consulte os diagramas abaixo para entender o caminho de execução:
Fluxo de credenciais do cliente
O fluxo de credenciais do cliente é usado principalmente para a interação entre dois sistemas de negócios. Esse fluxo é configurado uma vez e, em seguida, compartilhado por todos os usuários.
- O usuário inicia o fluxo clicando no botão “Testar” antes de salvar um conector.
- O Tulip se comunica com o servidor de autorização do seu provedor OAuth, compartilhando parâmetros específicos, como identidade do cliente, escopos (o que você está tentando acessar) e outros detalhes relevantes.
- O servidor de autorização retorna um token de acesso, desde que o ID do cliente e o segredo do cliente estejam corretos. Opcionalmente, um token de atualização também pode ser retornado. Esse token serve para solicitações autorizadas pelo usuário.
- O Tulip agora pode executar solicitações em nome dos usuários, utilizando o token fornecido para autorização.
Configurar o OAuth
The Authorize and Token endpoints must be accessible to the cloud for Tulip to execute authentication for connectors.
URL do código de autorização
Esta é a URL que o Tulip acessa na etapa 2 do fluxo de código de autenticação. Encontrada na documentação da API do seu provedor OAuth, ela geralmente termina em /auth ou /authorize.
Observação: este campo não está presente para credenciais de cliente.
URL do token de acesso
Após a resposta do servidor de autorização, é feita uma solicitação à URL do token de acesso para obter um token para autenticação. Geralmente termina em /token.
ID do cliente e segredo do cliente
Gerado a partir da interface do usuário do seu provedor OAuth, o ID do cliente é enviado junto com a solicitação inicial de um código de autorização. O ID do cliente e o segredo do cliente acompanham todas as solicitações de token.
Tempo de validade padrão (segundos)
Este campo especifica o tempo padrão (em segundos) após o qual os tokens serão atualizados, caso nenhum tempo de validade seja explicitamente fornecido ou definido por meio de outro mecanismo fora do campo expires_in.
Público-alvo e escopo
O público-alvo especifica os ativos específicos aos quais seu usuário deseja acessar, enquanto o escopo define as ações desejadas nesses ativos. Ambos são transmitidos durante a solicitação do código de autorização na etapa 2.
Opções adicionais
- Enviar dados da solicitação de token como JSON: altera o tipo de codificação da solicitação enviada à URL do token. Habilite se necessário para integrações específicas.
- Enviar cabeçalho de autenticação para solicitação de atualização: adiciona um cabeçalho extra às solicitações de atualização quando ativado.
- Ignorar solicitação de consentimento do usuário: controla o atributo de solicitação da solicitação de código de autenticação. Quando desativado, define-o como
“consentimento”, enquanto, quando ativado, define-o como“login”, permitindo que o provedor OAuth decida qual tela de login exibir.
For some integrations, exclude or set the prompt attribute to none. Reach out to support@tulip.co for further functionality.
Detalhes técnicos
Aqui estão os detalhes sobre o que o Tulip suporta e como o OAuth é integrado para a autenticação do conector.
The Client Credentials flow differs some from the authorization code flow. Steps 1 and 2 are not relevant for the Client Credential flow.
Fluxo de código de autorização do Tulip
The Authorize and Token endpoints must be accessible to the cloud for Tulip to execute authentication for connectors
O Tulip inicia o processo de autenticação ao testar um conector ou ao executar uma função de conector dentro de um aplicativo.
1. Redirecionamento para o servidor de autorização
O aplicativo do Tulip redireciona o usuário para o servidor de autorização (AS) juntamente com parâmetros específicos, incluindo o response_type (definido como “code” para o fluxo de código de autorização), client_id (atribuído na interface do conector), redirect_uri (predefinido pelo Tulip), scope e audience (definidos na interface) e state (uma sequência aleatória para proteção contra ataques de falsificação de solicitação entre sites).
Exemplo: GET /authorize?response_type=code&client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&scope=SCOPE&audience=AUDIENCE&state=STATE
2. O usuário concede consentimento
O servidor de autorização autentica o usuário e exibe uma tela de consentimento. O usuário pode revisar as permissões solicitadas e decidir se concede ou nega acesso ao aplicativo de terceiros.
:::(Aviso) (Observação)
Na configuração de um determinado connector, o controle “Ignorar solicitação de consentimento do usuário” permite controlar o atributo prompt na solicitação de autorização. Com esse controle desativado, será usado o valor consent; quando ativado, será usado o valor login.
Caso sejam necessários valores adicionais para o atributo prompt, entre em contato com support@tulip.co, e habilitaremos mais opções para essa propriedade.
:::
3. Código de autorização
Se o usuário conceder consentimento, o Servidor de Autorização gera um código de autorização e redireciona o usuário de volta para o Tulip, juntamente com o código de autorização. O parâmetro “state” também é incluído, permitindo que o cliente verifique a integridade da resposta. Esse parâmetro “state” deve corresponder ao parâmetro “state” passado na Etapa 1.
Exemplo de redirecionamento para o URI de redirecionamento do cliente:
REDIRECT_URI?code=AUTHORIZATION_CODE&state=STATE
4. Solicitação de token
O cliente agora possui o código de autorização e o utiliza para fazer uma solicitação segura, de servidor para servidor, ao endpoint de token do Servidor de Autorização. O cliente inclui o grant_type (definido como “authorization_code”), client_id, client_secret (um segredo conhecido apenas pelo cliente e pelo Servidor de Autorização), redirect_uri e o código de autorização.
Exemplo de solicitação de token:
grant\_type=authorization\_code&code=AUTHORIZATION\_CODE&redirect\_uri=REDIRECT\_URI&client\_id=CLIENT\_ID&client\_secret=CLIENT\_SECRET```
### 5. Resposta do token de acesso:
Se o código de autorização for válido, o servidor de autorização responde com um token de acesso e, opcionalmente, um token de atualização. O token de acesso é usado pelo cliente para se autenticar ao fazer solicitações à API protegida em nome do usuário.
**Exemplo de resposta com token:**
`{ "access_token": "ACCESS_TOKEN", "token_type": "Bearer", "expires_in": 3600, "refresh_token": "REFRESH_TOKEN", "scope": "SCOPE"}`
:::(Warning) (Services Not Using `expires_in`)
If the token's expiration time is not provided via the `expires_in` key, the "Default Expiration Time (seconds)" field in the authentication configuration will be used to automate token renewal.
:::
### 6. Acessando o servidor de recursos
O Tulip agora pode usar o token de acesso obtido para fazer solicitações autorizadas ao servidor de recursos (API) em nome do usuário. O token de acesso geralmente é incluído no cabeçalho Authorization da solicitação HTTP.
**Exemplo de solicitação de API:**`GET /api/resource Authorization: Bearer ACCESS_TOKEN`
## Gerencie a expiração do token com tokens de atualização
Os servidores de autorização normalmente definem datas de validade para os tokens a fim de regular o acesso, com prazos de validade variáveis dependendo do sistema conectado. No entanto, tokens de curta duração representam um desafio, pois a autenticação constante do usuário prejudica a experiência do usuário nos aplicativos do Tulip.
Para resolver essa questão, o OAuth oferece suporte a tokens de atualização. Embora sejam opcionais, eles são altamente recomendados, pois otimizam a experiência do usuário, permitindo que o Tulip atualize os tokens de forma contínua, sem exigir intervenção manual dos operadores.
### Como o Tulip gerencia a atualização de tokens?
Quando o Tulip detecta que um token de acesso expirou, ele tenta automaticamente usar o token de atualização associado para obter um novo token. O objetivo principal é minimizar a reautenticação do usuário. As etapas a seguir descrevem a lógica executada pelo Tulip:
**1. Detecção de expiração:** - O Tulip identifica um token expirado com base em seu atributo `` `expires_in` ``, recebido na [etapa 5](/r230/docs/oauth20-configuration-and-technical-details#5-access-token-response) do fluxo de autenticação.
:::(Warning) (Services Not Using `expires_in`)
If the token's expiration time is not provided via the `expires_in` key, the "Default Expiration Time (seconds)" field in the authentication configuration will be used to automate token renewal.
:::
**2. Tentativa de fluxo de tokens:** - O Tulip inicia o fluxo de tokens usando o tipo de concessão `` `refresh_token` ``, substituindo o tipo de concessão usado no fluxo de autenticação inicial.
**3. Validação do token:** - Se um novo token for obtido, o Tulip o armazena e prossegue com a execução da ação solicitada pelo usuário ( connector function). - Se for bem-sucedido, os dados são fornecidos ao ambiente de execução do aplicativo Tulip. - Se o novo token falhar com um erro OAuth, o Tulip repete o processo até 5 vezes, voltando à etapa 1 a cada vez. - Se o novo token falhar com qualquer outro erro, um erro é exibido no ambiente de execução do player.
**4. Tratamento da ausência de token:** - Se um novo token não for fornecido, o Tulip solicita ao usuário no player que realize a autenticação, iniciando todo o processo de autenticação. - Após a conclusão, a função connector function é executada e os dados são retornados.
Ao implementar tokens de atualização, o Tulip garante uma experiência de usuário mais fluida, gerenciando de forma inteligente a expiração e a renovação dos tokens, minimizando interrupções no fluxo de trabalho.
---
Você encontrou o que estava procurando?
Você também pode acessar [community.tulip.co](https://community.tulip.co/?utm_source=intercom&utm_medium=article-link&utm_campaign=all) para postar sua pergunta ou ver se outras pessoas já tiveram uma dúvida semelhante!