Ir para o conteúdo

Implemente 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, utilizando as credenciais delegadas desse usuário em vez de uma conta de serviço compartilhada. Este guia cobre todo o fluxo: construção da URL de autorização, recebimento do código de autorização em um endpoint de callback, troca do código por tokens de acesso e de atualização, armazenamento do token de atualização no Cloud Datastore e atualização do 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 requer permissões em nível de 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á construindo um agente de IA ou um fluxo de trabalho automatizado que acessa caixas de entrada, calendários ou documentos de usuários.

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

Este guia assume:

  • Uma API personalizada está configurada e publicada no API Manager no mesmo ambiente que o projeto.
  • Um armazenamento de chave do Cloud Datastore existe ou será criado para manter registros de token por usuário. Consulte Armazenar e recuperar o estado da sessão usando o Cloud Datastore para 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 no Cloud Datastore e o troca por um novo token de acesso.

Parte 1: Registre o aplicativo OAuth e armazene as credenciais

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

Registre o aplicativo

No console de desenvolvedor do seu provedor OAuth (por exemplo, o Google Cloud Console), crie uma credencial OAuth 2.0 do tipo Aplicativo da 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-agente>/<ambiente>/<versão>/<raiz-do-serviço>/oauth/callback. Você deve conhecer essa URL antes de concluir o registro.

O provedor emitirá um ID do Cliente e um Segredo do Cliente.

Armazene as credenciais como variáveis do projeto

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

  • client_id: O ID do cliente do aplicativo OAuth emitido pelo provedor.
  • client_secret: O segredo do cliente do aplicativo OAuth.
  • redirect_uri: A URL completa de callback configurada no console do provedor.

Referencie essas variáveis em scripts usando o prefixo $ (por exemplo, $client_id, $client_secret, $redirect_uri).

Dica

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

Parte 2: Crie 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 configuração 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 semelhante.

  2. Adicione um passo de Script como o primeiro passo. 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 Expose a Studio operation as a REST API para publicar a operação OAuth Callback. Ao configurar o endpoint, defina:

  • Método: GET. 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. O script de callback define $jitterbit.api.response.body e $jitterbit.api.response.headers.Content_Type para servir uma página de confirmação em 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 semelhante. Adicione um passo 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 o aplicativo 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: Instruções para o provedor 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 o aplicativo 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 correspondentes do seu provedor de destino.

Entregue 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 no Slack (por exemplo, em um agente que usa o Slack como interface):

<trans>
$jitterbit.api.response = "{\"response_type\": \"ephemeral\", \"text\": \"Para conectar sua conta, abra este link: " + $authUrl + "\"}";
</trans>

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

Parte 4: Lidar com 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 em HTML para o navegador, trocar o código por tokens e armazenar o token de atualização.

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

Na operação OAuth Callback, abra a etapa do 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, o tipo de conteúdo e o 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 acontece antes que a resposta seja retornada, e a variável global authCode está disponível para a operação chamada.

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

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

  1. Na aba Endpoints e conectores do projeto do painel de componentes de design, clique em HTTP v2 para abrir uma nova conexão.

  2. Nome da Conexão: Insira um nome (por exemplo, Google OAuth).

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

  4. Autorização: Selecione Sem Autenticação. As credenciais do cliente estão incluídas no corpo da solicitação, não em um cabeçalho de autorização.

  5. Clique em Testar, depois em Salvar Alterações.

Etapa 3: Criar a operação de Troca de Token

Crie uma nova operação chamada Troca de 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)

Construa 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. Nome: Insira Troca de Token POST ou similar.

  4. Caminho: Insira /token.

  5. Cabeçalhos da Solicitação: Adicione Content-Type / application/x-www-form-urlencoded.

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

  7. Clique em Concluído.

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 pelo caminho JSON. TrimChars remove as aspas ao redor que GetJSONString inclui em sua saída.

Etapa 4: Armazenar o token de atualização

Crie uma nova operação chamada Armazenar Token de Atualização. Use as atividades Inserir Itens e Atualizar Itens do Cloud Datastore com o padrão de consulta-depois-ramificação para persistir o token de atualização associado a um identificador de usuário único (por exemplo, o endereço de e-mail do usuário ou o ID do usuário do Slack). Mapeie refresh_token para o campo do token de atualização no armazenamento do Cloud Datastore.

Veja Armazenar e recuperar o estado da sessão usando o Cloud Datastore para o padrão completo de consulta-inserção-atualização.

Aviso

O Cloud Datastore armazena dados em texto simples. Não o utilize para armazenar o segredo do cliente ou qualquer outra credencial de aplicativo. O token de atualização armazenado aqui é intencionalmente limitado ao usuário e deve ser tratado como sensível. Restringir o acesso ao armazenamento do Cloud Datastore ao mínimo necessário.

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 gerencia isso e deve ser executada no início de qualquer cadeia de operações que chama a API de destino.

Criar a operação Check Auth

Crie uma nova operação chamada Check Auth. Adicione um passo 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 para refresh_token (usando o mesmo padrão de consulta por chave descrito em Armazenar e recuperar o estado da sessão usando o Cloud Datastore). Se nenhum token for encontrado, RaiseError interrompe a cadeia antes que qualquer chamada de API seja tentada.

Criar a operação Refresh Access Token

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

Passo 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: Utilize a mesma conexão do Google OAuth criada na 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 a montante.

Passo 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 uma expiração curta (normalmente uma hora). Chame a operação Check Auth antes de cada chamada de API que requer um token válido, em vez de armazenar o token de acesso entre as execuções.

Verifique a integração

  1. Implantar 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 servida pela operação OAuth Callback.

  4. Em Console de Gerenciamento > 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 da 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. Provedores OAuth rejeitam qualquer discrepância.
    • Verifique os logs da API no Gerenciador de API 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 configurados corretamente.
    • Confirme que authCode não foi utilizado anteriormente. 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 para obter um novo token de atualização e atualizar o valor armazenado.