O tipo de vinculação 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:
- 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.
- 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.
Implementar a vinculação de conta OAuth
Configurar o projeto
Para configurar seu projeto para usar a vinculação OAuth, siga estas etapas:
- Abra o Console do Actions e selecione o projeto que você quer usar.
- Clique na guia Desenvolver e escolha Vinculação de contas.
- Ative a chave ao lado de Vinculação de contas.
- Na seção Criação de conta, selecione Não, quero permitir apenas a criação de contas no meu site.
Em Tipo de vinculação, selecione OAuth e Implícito.
Em Informações do cliente:
- Atribua um valor ao ID do cliente emitido pelas suas ações para o Google para identificar solicitações do Google.
- Insira os URLs dos endpoints de autorização e de troca de tokens.
- Clique em Salvar.
Implementar o servidor OAuth
为了支持 OAuth 2.0 隐式流程,您的服务会通过 HTTPS 提供授权端点。此端点负责验证数据访问并从用户那里获得同意。授权端点会向尚未登录的用户呈现登录界面,并记录用户同意所请求的访问。
当您的 Action 需要调用某项服务的已授权 API 时,Google 会使用此端点从您的用户处获取权限,以便代表他们调用这些 API。
由 Google 发起的典型 OAuth 2.0 隐式流会话具有以下流程:
- Google 会在用户的浏览器中打开您的授权端点。用户如果尚未登录,则登录;如果用户尚未授予权限,则授予 Google 使用您的 API 访问其数据的权限。
- 您的服务会创建访问令牌,并使用附加到请求的访问令牌将用户的浏览器重定向回 Google,从而将其返回给 Google。
- Google 会调用您的服务的 API,并为每个请求附加访问令牌。您的服务会验证访问令牌是否授予 Google 访问 API 的授权,然后完成 API 调用。
处理授权请求
当您的 Action 需要通过 OAuth 2.0 隐式流程执行帐号关联时,Google 会通过包含以下参数的请求将用户发送到您的授权端点:
授权端点参数 | |
---|---|
client_id |
您分配给 Google 的客户端 ID。 |
redirect_uri |
您要将该请求的响应发送到的网址。 |
state |
在重定向 URI 中原封不动地传回 Google 的簿记值。 |
response_type |
要在响应中返回的值的类型。对于 OAuth 2.0 隐式流程,响应类型始终为 token 。 |
例如,如果您的授权端点位于 https://myservice.example.com/auth
,请求可能如下所示:
GET https://myservice.example.com/auth?client_id=GOOGLE_CLIENT_ID&redirect_uri=REDIRECT_URI&state=STATE_STRING&response_type=token
为了让授权端点能够处理登录请求,请执行以下步骤:
验证
client_id
和redirect_uri
值,以防止授予对意外或配置错误的客户端应用的访问权限:- 确认
client_id
与您分配给 Google 的客户端 ID 匹配。 - 确认
redirect_uri
参数指定的网址采用以下格式:https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID
YOUR_PROJECT_ID 是在 Actions 控制台的 Project settings 页面上找到的 ID。
- 确认
检查用户是否登录了您的服务。如果用户未登录,请完成服务的登录或注册流程。
生成 Google 将用于访问您的 API 的访问令牌。访问令牌可以是任何字符串值,但它必须唯一地代表用户和令牌所面向的客户端,并且必须不可猜测。
发送 HTTP 响应,将用户浏览器重定向到
redirect_uri
参数指定的网址。在网址片段中添加以下所有参数:access_token
:您刚刚生成的访问令牌token_type
:字符串bearer
state
:原始请求中的未修改状态值 以下是所生成网址的示例:https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID#access_token=ACCESS_TOKEN&token_type=bearer&state=STATE_STRING
Google 的 OAuth 2.0 重定向处理程序将接收访问令牌,并确认 state
值未更改。Google 为您的服务获取访问令牌后,会将该令牌作为 AppRequest 的一部分附加到对您的 Action 的后续调用。
Projetar a interface do usuário de voz para o fluxo de autenticação
Conferir se o usuário foi verificado e iniciar o fluxo de vinculação da conta
- Abra seu projeto do Actions Builder no Actions Console.
- Crie um novo cenário para começar a vinculação da conta na sua Ação:
- Clique em Cenas.
- Clique no ícone add (+) para adicionar uma nova cena.
- No cenário recém-criado, clique no ícone de adição add para Condições.
- Adicione uma condição que verifica se o usuário associado à conversa é um
usuário verificado. Se a verificação falhar, a Ação não poderá fazer a vinculação da conta
durante a conversa e vai voltar a fornecer acesso a
recursos que não exijam a vinculação de conta.
- No campo
Enter new expression
em Condição, insira a seguinte lógica:user.verificationStatus != "VERIFIED"
- Em Transição, selecione uma cena que não exija vinculação de conta ou uma cena que seja o ponto de entrada para a funcionalidade exclusiva para convidados.
- No campo
- Clique no ícone de adição add para Condições.
- Adicione uma condição para acionar um fluxo de vinculação de conta se o usuário não tiver
uma identidade associada.
- No campo
Enter new expression
em Condição, insira a seguinte lógica:user.verificationStatus == "VERIFIED"
- Em Transição, selecione a cena do sistema Vinculação de contas.
- Clique em Salvar.
- No campo
Depois de salvar, uma nova cena do sistema de vinculação de contas chamada <SceneName>_AccountLinking
será adicionada ao projeto.
Personalizar o cenário de vinculação da conta
- Em Scenes, selecione a cena do sistema de vinculação de contas.
- 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").
- Clique em Salvar.
- Em Condições, clique em Se o usuário concluir a vinculação da conta.
- Configure como o fluxo deve proceder se o usuário concordar em vincular a 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.
- Clique em Salvar.
- Em Condições, clique em Se o usuário cancelar ou dispensar a vinculação da conta.
- Configure como o fluxo deve proceder se o usuário não concordar em vincular a conta. Por exemplo, envie uma mensagem de confirmação e redirecione para cenas que fornecem funcionalidades que não exigem vinculação de conta.
- Clique em Salvar.
- Em Condições, clique em Se ocorrer um erro de sistema ou rede.
- Configure como o fluxo vai proceder se não for possível concluir o fluxo de vinculação da conta devido a erros no sistema ou na rede. Por exemplo, envie uma mensagem de confirmação e redirecione para cenas que fornecem funcionalidades que não exigem vinculação de conta.
- Clique em Salvar.
Processar solicitações de acesso a dados
Se a solicitação do Google Assistente contiver um token de acesso, primeiro verifique se o token de acesso é válido (e não expirou) e, em seguida, recupere a conta de usuário associada do seu banco de dados.