Vinculação de conta com o OAuth

O tipo de vinculação do OAuth é compatível com dois fluxos do OAuth 2.0 padrão do setor, os fluxos de código implícito e de autorização.

No fluxo de código implícito, o Google abre o endpoint de autorização no navegador do usuário. Após o login, você retorna um token de acesso de longa duração para o Google. Esse token de acesso agora está incluído em todas as solicitações enviadas do Assistente para sua ação.

No fluxo do código de autorização, você precisa de dois endpoints:

• O endpoint de autorização, responsável por apresentar a IU de login aos usuários que ainda não fizeram login e registrar o consentimento para o acesso solicitado na forma de um código de autorização de curta duração.
• O endpoint de troca de token, que é responsável por dois tipos de trocas:
  1. troca um código de autorização por um token de atualização de longa duração e um token de acesso de curta duração. Essa troca acontece quando o usuário passa pelo fluxo de vinculação da conta.
  2. Troca um token de atualização de longa duração por um token de acesso de curta duração. Essa troca acontece quando o Google precisa de um novo token de acesso porque ele expirou.

Embora o fluxo do código implícito seja mais simples de implementar, o Google recomenda que os tokens de acesso emitidos usando o fluxo implícito nunca expirem, porque o uso do token com o fluxo implícito força o usuário a vincular a conta novamente. Se você precisar da validade do token por motivos de segurança, considere o uso do fluxo do código de autenticação.

Observação: escolha qual fluxo do OAuth 2.0 você quer implementar. Se necessário, o conteúdo deste guia será atualizado para se adaptar à sua escolha.

Código de autenticação Fluxo implícito

Implementar a vinculação de conta OAuth

Observação: se você estiver implementando a vinculação de contas para lidar com informações financeiras, outras políticas podem ser aplicadas à sua ação. A revisão de uma ação com vinculação de conta pode levar até seis semanas para ser feita com informações financeiras. Portanto, leve esse tempo em consideração ao planejar sua programação de lançamentos. Para facilitar o processo de revisão, verifique se você está em conformidade com as políticas de serviços financeiros antes de enviar a ação para análise.

Configurar o projeto

Para configurar seu projeto para usar a vinculação OAuth, siga estas etapas:

1. Abra o Console do Actions e selecione o projeto que você quer usar.
2. Clique na guia Desenvolver e escolha Vinculação de contas.
3. Ative a chave ao lado de Vinculação de contas.
4. Na seção Criação de conta, selecione Não, só quero permitir a criação de contas no meu site.

5. Em Tipo de vinculação, selecione OAuth e Implicit.

   

6. Em Informações do cliente:

   • Atribua um valor ao ID do cliente emitido pelo Actions to Google para identificar solicitações provenientes do Google.
   • Insira os URLs dos endpoints de autorização e do Exchange Exchange.

Observação: se você quiser que o ID do cliente seja enviado como uma string codificada em base64, clique na seta suspensa ao lado de Configurar seu cliente (opcional) e marque a caixa Google para transmitir clientID e secret por meio do cabeçalho de autenticação básica HTTP.

6. Clique em Salvar.

Implementar o servidor OAuth

Para oferecer suporte ao fluxo implícito do OAuth 2.0, o serviço disponibiliza um endpoint de autorização por HTTPS. Esse endpoint é responsável por autenticar e receber consentimento dos usuários para acesso aos dados. O endpoint de autorização apresenta uma IU de login aos usuários que ainda não estão conectados e registra o consentimento para o acesso solicitado.

Quando a ação precisar chamar uma das APIs autorizadas do serviço, o Google usará esse endpoint para receber permissão dos usuários para chamar essas APIs em nome deles.

Uma sessão de fluxo implícito do OAuth 2.0 típica iniciada pelo Google tem o seguinte fluxo:

1. O Google abre seu endpoint de autorização no navegador do usuário. O usuário faz login, caso ainda não tenha feito, e concede ao Google permissão para acessar os dados dele com a API, caso ainda não tenha concedido permissão.
2. Seu serviço cria um token de acesso e o retorna ao Google redirecionando o navegador do usuário de volta ao Google com o token de acesso anexado à solicitação.
3. O Google chama as APIs do seu serviço e anexa o token de acesso a cada solicitação. O serviço verifica se o token de acesso concede ao Google autorização para acessar a API e conclui a chamada de API.

Processar solicitações de autorização

Quando sua ação precisa realizar uma vinculação de conta por meio de um fluxo implícito do OAuth 2.0, o Google envia o usuário ao endpoint de autorização com uma solicitação que inclui os seguintes parâmetros:

Parâmetros do endpoint de autorização
client_id	O ID do cliente atribuído ao Google.
redirect_uri	O URL para o qual você envia a resposta para esta solicitação.
state	Um valor de contabilidade que é retornado ao Google sem alterações no URI de redirecionamento.
response_type	O tipo de valor a ser retornado na resposta. Para o fluxo implícito do OAuth 2.0, o tipo de resposta é sempre token.

Por exemplo, se o endpoint de autorização estiver disponível em https://myservice.example.com/auth, uma solicitação poderá ter esta aparência:

GET https://myservice.example.com/auth?client_id=GOOGLE_CLIENT_ID&redirect_uri=REDIRECT_URI&state=STATE_STRING&response_type=token

Para que seu endpoint de autorização processe solicitações de login, siga estas etapas:

1. Verifique os valores client_id e redirect_uri para impedir a concessão de acesso a apps cliente indesejados ou configurados incorretamente:

   • Confirme se client_id corresponde ao ID do cliente atribuído ao Google.
   • Confirme se o URL especificado pelo parâmetro redirect_uri tem o seguinte formato:

     https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID

     YOUR_PROJECT_ID é o ID encontrado na página Configurações do projeto do Console do Actions.

2. Verifique se o usuário fez login no seu serviço. Se o usuário não estiver conectado, conclua o fluxo de login ou inscrição do seu serviço.

3. Gere um token de acesso que o Google usará para acessar sua API. O token de acesso pode ser qualquer valor de string, mas precisa representar exclusivamente o usuário e o cliente a que o token pertence e não pode ser adivinhado.

4. Envia uma resposta HTTP que redireciona o navegador do usuário para o URL especificado pelo parâmetro redirect_uri. Inclua todos os seguintes parâmetros no fragmento de URL:

   • access_token: o token de acesso que você acabou de gerar
   • token_type: a string bearer
   • state: o valor do estado não modificado da solicitação original. Veja a seguir um exemplo do URL resultante:

     https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID#access_token=ACCESS_TOKEN&token_type=bearer&state=STATE_STRING

O gerenciador de redirecionamento OAuth 2.0 do Google receberá o token de acesso e confirmará que o valor state não foi alterado. Depois de receber um token de acesso para seu serviço, o Google anexará o token a chamadas subsequentes para sua ação como parte da AppRequest.

Projetar a interface de usuário do Voice para o fluxo de autenticação

Aviso: não dê aos usuários um prompt de vinculação de conta obrigatório no início da conversa com a ação. Em vez disso, ofereça aos usuários não autenticados um fluxo de convidado para mostrar como a ação funciona. Em seguida, solicite a vinculação da conta somente se for necessário continuar. Se os usuários estiverem saindo da ação com frequência por problemas de vinculação de contas, o Google não a promoverá ativamente, o que pode diminuir o tráfego de usuários da ação.

Observação: use o Criador de ações para criar uma ação que implemente a vinculação de conta.

Verificar se o usuário foi verificado e iniciar o fluxo de vinculação da conta

1. Abra seu projeto do Actions Builder no Console do Actions.
2. Crie uma nova cena para iniciar a vinculação da conta na sua ação:
   1. Clique em Cenas.
   2. Clique no ícone add (+) para adicionar uma nova cena.
3. Na cena recém-criada, clique no ícone de adição para Condições.
4. Adicione uma condição que verifique se o usuário associado à conversa é um usuário verificado. Se a verificação falhar, sua ação não poderá vincular contas durante a conversa e voltará a fornecer acesso a funcionalidades que não exijam vinculação de contas.
   1. No campo Enter new expression em Condição, insira a seguinte lógica: user.verificationStatus != "VERIFIED"
   2. Em Transição, selecione uma cena que não exija vinculação de conta ou que seja o ponto de entrada para a funcionalidade somente para convidados.

1. Clique no ícone de adição para Condições.
2. Adicione uma condição para acionar um fluxo de vinculação de conta se o usuário não tiver uma identidade associada.
   1. No campo Enter new expression em Condição, insira a seguinte lógica: user.verificationStatus == "VERIFIED"
   2. Em Transição, selecione a cena do sistema Vinculação de contas.
   3. Clique em Salvar.

Depois de salvar, uma nova cena do sistema de vinculação de contas chamada <SceneName>_AccountLinking é adicionada ao projeto.

Personalizar a cena de vinculação de contas

1. Em Cenas, selecione a cena do sistema de vinculação de contas.
2. Clique em Enviar solicitação e adicione uma frase curta para descrever ao usuário por que a ação precisa acessar a identidade dele (por exemplo, "Para salvar suas preferências").
3. Clique em Salvar.

1. Em Condições, clique em Se o usuário concluir a vinculação da conta.
2. Configure como o fluxo deve prosseguir se o usuário concordar em vincular sua conta. Por exemplo, chame o webhook para processar qualquer lógica de negócios personalizada necessária e fazer a transição de volta para a cena de origem.
3. Clique em Salvar.

1. Em Condições, clique em Se o usuário cancelar ou dispensar a vinculação da conta.
2. Configure como o fluxo deve prosseguir se o usuário não concordar em vincular a conta. Por exemplo, envie uma mensagem de confirmação e redirecione para cenas que forneçam uma funcionalidade que não exija vinculação de conta.
3. Clique em Salvar.

1. Em Condições, clique em Se ocorrer um erro de sistema ou de rede.
2. Configure como o fluxo deve prosseguir se o fluxo de vinculação da conta não puder ser concluído devido a erros do sistema ou da rede. Por exemplo, envie uma mensagem de confirmação e redirecione para cenas que forneçam uma funcionalidade que não exija vinculação de conta.
3. Clique em Salvar.

Processar solicitações de acesso a dados

Se a solicitação do Assistente tiver um token de acesso, verifique primeiro se ele é válido (e não expirou) e recupere a conta de usuário associada do seu banco de dados.