Ir para o conteúdo

Implementar um fluxo de código de autorização OAuth 2.0 com armazenamento de token no Jitterbit Studio

Introdução

O fluxo de código de autorização OAuth 2.0 permite que uma operação do Studio acesse uma API de terceiros em nome de um usuário específico, usando as credenciais delegadas desse usuário em vez de uma conta de serviço compartilhada. Este guia aborda o fluxo completo: construir a URL de autorização, receber o código de autorização em um endpoint de callback, trocar o código por tokens de acesso e atualização, armazenar o token de atualização no Cloud Datastore e atualizar o token de acesso em execuções subsequentes sem interação do usuário.

Os exemplos neste guia usam o Google como provedor de autorização. O mesmo padrão se aplica a qualquer provedor OAuth 2.0 que suporte o tipo de concessão de código de autorização: substitua as URLs, escopos e nomes de parâmetros específicos do provedor pelos valores do seu serviço de destino.

Use este padrão quando:

  • A API de destino exige permissões no nível do usuário que uma conta de serviço não pode fornecer.
  • Você precisa de acesso de longa duração usando tokens de atualização sem autorização manual repetida.
  • Você está criando um agente de IA ou fluxo de trabalho automatizado que acessa caixas de correio, calendários ou documentos do usuário.

Para APIs que usam chaves de API ou credenciais de cliente em vez de autorização do usuário, consulte Gerenciar credenciais de endpoint e Chamar uma API REST usando o conector HTTP v2.

Este guia pressupõe:

  • Uma API personalizada está configurada e publicada no API Manager no mesmo ambiente do projeto.
  • Existe um armazenamento de chave do Cloud Datastore ou será criado para manter registros de token por usuário. Consulte Armazenar e recuperar estado de sessão usando Cloud Datastore para as etapas de configuração.
  • O projeto tem uma maneira de entregar uma URL ao usuário, como uma mensagem do Slack ou uma interface do App Builder.

Padrão de design

Três operações implementam o fluxo de código de autorização OAuth 2.0:

flowchart TD A["Connect operation
Build auth URL → Deliver to user"] --> B["User browser
Approve access at provider"] B -->|"Redirect with ?code="| C["Callback operation
Extract code → Exchange for tokens → Store refresh token → Serve confirmation page"] D["Check Auth operation
Read refresh token → Exchange for access token"] --> E["API calls using access token"]

A operação Connect constrói a URL de autorização e a entrega ao usuário. A operação OAuth Callback recebe o código de autorização quando o provedor redireciona o navegador do usuário, troca o código por tokens e armazena o token de atualização para uso futuro. A operação Check Auth é executada antes de qualquer chamada de API: ela lê o token de atualização armazenado do Cloud Datastore e o troca por um token de acesso atualizado.

Parte 1: Registrar a aplicação OAuth e armazenar credenciais

Antes de escrever qualquer script, registre o Studio como uma aplicação OAuth com o provedor de autorização e armazene as credenciais resultantes como variáveis de projeto.

Registrar a aplicação

No console do desenvolvedor do seu provedor OAuth (por exemplo, o Google Cloud Console), crie uma credencial OAuth 2.0 do tipo Aplicação web e configure:

  • URIs de redirecionamento autorizados: Adicione a URL completa do endpoint de callback que você criará na Parte 2. Por exemplo: https://<seu-host-do-agente>/<ambiente>/<versão>/<raiz-do-serviço>/oauth/callback. Você deve conhecer esta URL antes de concluir o registro.

O provedor emitirá uma ID do cliente e um Segredo do cliente.

Armazenar credenciais como variáveis de projeto

No Studio, abra o menu de ações do projeto e selecione Variáveis de Projeto. Crie as seguintes variáveis de projeto com seus valores ocultos:

  • client_id: A ID do cliente da aplicação OAuth emitida pelo provedor.
  • client_secret: O segredo do cliente da aplicação OAuth.
  • redirect_uri: A URL de callback completa configurada no console do provedor.

Faça referência a essas variáveis em scripts usando o prefixo $ (por exemplo, $client_id, $client_secret, $redirect_uri).

Dica

Armazenar redirect_uri como uma variável de projeto facilita a atualização ao se mover entre ambientes sem editar scripts.

Parte 2: Criar o endpoint de callback

O endpoint de callback recebe o código de autorização do provedor após o usuário aprovar o acesso. Crie-o antes de escrever qualquer script para que a URL completa esteja disponível para configurar no console do provedor.

Criar a operação de callback

  1. No Studio, crie uma nova operação. Nomeie-a como OAuth Callback ou um nome similar.

  2. Adicione uma etapa de Script como a primeira etapa. Deixe o corpo do script vazio por enquanto. Você adicionará a lógica de callback na Parte 4.

Publicar a operação de callback como um endpoint de API

Siga Expor uma operação do Studio como uma API REST para publicar a operação OAuth Callback. Ao configurar o endpoint, defina:

  • Método: GET. Os provedores OAuth redirecionam o navegador do usuário para a URL de callback usando uma solicitação GET com parâmetros de consulta.
  • Caminho: /oauth/callback (ou qualquer caminho que corresponda ao URI de redirecionamento que você registrará com o provedor).
  • Tipo de Resposta: Variável do Sistema. O script de callback define $jitterbit.api.response.body e $jitterbit.api.response.headers.Content_Type para servir uma página de confirmação HTML.

Copie a URL do endpoint publicado. Use-a como o valor da variável de projeto redirect_uri e registre-a com o provedor como um URI de redirecionamento autorizado.

Parte 3: Construir a URL de autorização

A operação Connect constrói a URL de autorização e a entrega ao usuário.

Criar a operação de conexão

Crie uma nova operação. Nomeie-a como Connect ou um nome similar. Adicione uma etapa de script com o seguinte script:

<trans>
$authUrl = "https://accounts.google.com/o/oauth2/v2/auth"
    + "?client_id=" + $client_id
    + "&redirect_uri=" + URLEncode($redirect_uri)
    + "&response_type=code"
    + "&scope=" + URLEncode("https://mail.google.com/ openid email")
    + "&access_type=offline"
    + "&prompt=consent";
</trans>

Os parâmetros principais:

  • response_type=code: Solicita o tipo de concessão de código de autorização.
  • scope: As permissões que a aplicação solicita. Separe múltiplos escopos com espaços e codifique a string combinada usando URLEncode. Ajuste os valores de escopo para corresponder ao que sua API de destino requer.
  • access_type=offline: Instrui o provedor a emitir um token de atualização além do token de acesso.
  • prompt=consent: Força a tela de consentimento a aparecer mesmo que o usuário tenha autorizado a aplicação anteriormente. Isso garante que um novo token de atualização seja emitido a cada vez.

Substitua a URL do endpoint de autorização do Google e os valores de escopo pelos do seu provedor de destino.

Entregar a URL ao usuário

Após construir a URL, entregue-a para que o usuário possa abri-la em um navegador. Para enviar a URL como uma mensagem efêmera do Slack (por exemplo, em um agente que usa o Slack como sua interface):

<trans>
$jitterbit.api.response = "{\"response_type\": \"ephemeral\", \"text\": \"To connect your account, open this link: " + $authUrl + "\"}";
</trans>

Alternativamente, retorne a URL como uma resposta de API simples ou inclua-a no corpo de um email.

Parte 4: Processar o callback e trocar o código de autorização

A operação OAuth Callback é executada quando o provedor redireciona o navegador do usuário para a URL de callback registrada. Ela deve extrair o código de autorização, servir uma página de confirmação HTML ao navegador, trocar o código por tokens e armazenar o token de atualização.

Etapa 1: Extrair o código de autorização e servir a página de confirmação

Na operação OAuth Callback, abra a etapa de script e adicione:

<trans>
$authCode = $jitterbit.api.request.parameters.code;

$jitterbit.api.response.body = "<html><body><h2>Connected successfully!</h2><p>You can close this window and return to the application.</p></body></html>";
$jitterbit.api.response.headers.Content_Type = "text/html";
$jitterbit.api.response.status_code = "200";

RunOperation("<TAG>Operations/Exchange Token</TAG>");
</trans>

$jitterbit.api.request.parameters.code contém o código de autorização da string de consulta da URL de redirecionamento. O corpo da resposta, tipo de conteúdo e código de status definidos aqui são retornados ao navegador quando a operação é concluída. RunOperation chama a operação Exchange Token de forma síncrona: a troca de token ocorre antes da resposta ser retornada, e a variável global authCode fica disponível para a operação chamada.

Etapa 2: Configurar a conexão do endpoint de token

Crie um endpoint HTTP v2 conectado ao endpoint de token do provedor:

  1. Na aba Project endpoints and connectors da paleta de componentes de design, clique em HTTP v2 para abrir uma nova conexão.

  2. Connection Name: Digite um nome (por exemplo, Google OAuth).

  3. Base URL: Digite a URL base do endpoint de token do provedor (por exemplo, https://oauth2.googleapis.com).

  4. Authorization: Selecione No Auth. As credenciais do cliente são incluídas no corpo da solicitação, não em um cabeçalho de autorização.

  5. Clique em Test e depois em Save Changes.

Etapa 3: Criar a operação Exchange Token

Crie uma nova operação chamada Exchange Token. Esta operação envia o código de autorização para o endpoint de token e extrai os tokens retornados.

Etapa de script (antes da atividade POST)

Crie o corpo da solicitação codificado em formulário:

<trans>
$tokenRequestBody = "code=" + URLEncode($authCode)
    + "&client_id=" + URLEncode($client_id)
    + "&client_secret=" + URLEncode($client_secret)
    + "&redirect_uri=" + URLEncode($redirect_uri)
    + "&grant_type=authorization_code";
</trans>

Atividade HTTP v2 POST

  1. Arraste uma atividade POST do endpoint Google OAuth para a tela da operação.

  2. Clique duas vezes na atividade para abrir sua configuração.

  3. Name: Digite Exchange Token POST ou similar.

  4. Path: Digite /token.

  5. Request Headers: Adicione Content-Type / application/x-www-form-urlencoded.

  6. Na etapa de schema, forneça um schema de solicitação com um único campo de texto (por exemplo, body) para manter a string codificada em URL. Na transformação upstream, mapeie tokenRequestBody para este campo.

  7. Clique em Finished.

Etapa de script (após a atividade POST)

Analise a resposta JSON e extraia os tokens:

<trans>
$refresh_token = TrimChars(GetJSONString($jitterbit.response, "/refresh_token"), "\"");
$access_token = TrimChars(GetJSONString($jitterbit.response, "/access_token"), "\"");
RunOperation("<TAG>Operations/Store Refresh Token</TAG>");
</trans>

$jitterbit.response contém o corpo da resposta bruta da atividade POST. GetJSONString extrai campos individuais por caminho JSON. TrimChars remove as aspas circundantes que GetJSONString inclui em sua saída.

Etapa 4: Armazenar o token de atualização

Crie uma nova operação chamada Store Refresh Token. Use as atividades Insert Items e Update Items do Cloud Datastore com o padrão query-then-branch para persistir o token de atualização com chave por um identificador de usuário único (por exemplo, o endereço de email do usuário ou ID de usuário do Slack). Mapeie refresh_token para o campo de token de atualização no armazenamento do Cloud Datastore.

Consulte Store and retrieve session state using Cloud Datastore para o padrão completo de query-insert-update.

Aviso

O Cloud Datastore armazena dados em texto simples. Não o use para armazenar o segredo do cliente ou qualquer outra credencial de aplicação. O token de atualização armazenado aqui é intencionalmente com escopo de usuário e deve ser tratado como sensível. Restrinja o acesso ao armazenamento do Cloud Datastore aos ambientes mínimos necessários.

Parte 5: Atualizar o token de acesso em execuções subsequentes

Após a autorização inicial, o token de atualização armazenado pode ser trocado por um novo token de acesso sem interação do usuário. Uma operação Check Auth lida com isso e deve ser executada no início de qualquer cadeia de operações que chame a API de destino.

Criar a operação Check Auth

Crie uma nova operação chamada Check Auth. Adicione uma etapa de script com:

<trans>
RunOperation("<TAG>Operations/Query Token</TAG>");
If(length(trim($refresh_token)) == 0,
    RaiseError("No refresh token found. Run the Connect operation to authorize access.")
);
RunOperation("<TAG>Operations/Refresh Access Token</TAG>");
</trans>

A operação Query Token lê o token de atualização armazenado do Cloud Datastore em refresh_token (usando o mesmo padrão query-by-key descrito em Store and retrieve session state using Cloud Datastore). Se nenhum token for encontrado, RaiseError interrompe a cadeia antes de qualquer chamada de API ser tentada.

Criar a operação Refresh Access Token

Crie uma nova operação chamada Refresh Access Token. Adicione uma etapa de script seguida por uma atividade HTTP v2 POST.

Etapa de script

<trans>
$tokenRequestBody = "refresh_token=" + URLEncode($refresh_token)
    + "&client_id=" + URLEncode($client_id)
    + "&client_secret=" + URLEncode($client_secret)
    + "&grant_type=refresh_token";
</trans>

Atividade HTTP v2 POST: Use a mesma conexão Google OAuth criada em Parte 4. Defina o caminho como /token e adicione o cabeçalho Content-Type: application/x-www-form-urlencoded. Mapeie tokenRequestBody para o corpo da solicitação na transformação upstream.

Etapa de script (após a atividade POST)

<trans>
$access_token = TrimChars(GetJSONString($jitterbit.response, "/access_token"), "\"");
</trans>

A variável access_token agora está disponível para qualquer operação subsequente na cadeia. Passe-a como um token Bearer no cabeçalho Authorization das solicitações de API de saída:

<trans>
$jitterbit.api.request.headers.Authorization = "Bearer " + $access_token;
</trans>

Nota

A maioria dos provedores OAuth emite tokens de acesso com validade curta (normalmente uma hora). Chame a operação Check Auth antes de cada chamada de API que exija um token válido em vez de armazenar o token de acesso entre execuções.

Verificar a integração

  1. Implante o projeto.

  2. Execute a operação Connect e abra a URL de autorização que ela produz em um navegador.

  3. Siga o fluxo de consentimento OAuth no navegador. Após aprovar o acesso, o navegador deve exibir a página de confirmação HTML fornecida pela operação OAuth Callback.

  4. Em Management Console > Cloud Datastore, abra o armazenamento de chaves e confirme que um registro com o identificador de usuário esperado e um campo de token de atualização não vazio foi criado.

  5. Execute a operação Check Auth manualmente. No log de operação, confirme que a operação Refresh Access Token foi concluída e que access_token não está vazio.

  6. Se o navegador mostrar uma página de erro do provedor em vez da página de confirmação:

    • Confirme que a variável de projeto redirect_uri corresponde exatamente à URI registrada no console do provedor, incluindo esquema, host e caminho. Os provedores OAuth rejeitam qualquer incompatibilidade.
    • Verifique os logs de API no API Manager para confirmar que a solicitação de callback chegou ao endpoint.

  7. Se a operação Exchange Token falhar com uma resposta 400 ou 401:

    • Confirme que client_id e client_secret estão definidos corretamente.
    • Confirme que authCode ainda não foi usado. Os códigos de autorização são de uso único e expiram após um curto período (normalmente 10 minutos).

  8. Se a operação Refresh Access Token falhar com uma resposta 401, o token de atualização armazenado pode ser inválido ou revogado. Execute novamente a operação Connect para esse usuário a fim de obter um novo token de atualização e atualizar o valor armazenado.