Vinculação de contas com a vinculação "simplificada" do Login do Google com base em OAuth

O tipo de vinculação "simplificada" do Login do Google baseada em OAuth adiciona o Login do Google à vinculação de contas baseada em OAuth. Isso oferece uma vinculação por voz perfeita para usuários do Google e também permite a vinculação de contas para usuários que se inscreveram no seu serviço com uma identidade que não é do Google.

Esse tipo de vinculação começa com o Login do Google, que permite verificar se as informações do perfil do usuário no Google existem no seu sistema. Se as informações do usuário não forem encontradas no seu sistema, um fluxo OAuth padrão será iniciado. O usuário também pode criar uma conta com as informações do perfil do Google.

Figura 1: depois que sua ação tiver acesso ao perfil do Google do usuário, você poderá usá-lo para encontrar uma correspondência no seu sistema de autenticação.

Para fazer a vinculação de contas com o tipo simplificado, siga estas etapas gerais:

1. Primeiro, peça ao usuário para dar consentimento de acesso ao perfil do Google dele.
2. Use as informações no perfil para identificar o usuário.
3. Se não for possível encontrar uma correspondência para o usuário do Google no seu sistema de autenticação, o fluxo vai continuar dependendo de como você configurou o projeto do Actions no console do Actions para permitir a criação de contas de usuário por voz ou apenas no seu site.
   • Se você permitir a criação de contas por voz, valide o token de ID recebido do Google. Em seguida, você pode criar um usuário com base nas informações do perfil contidas no token de ID.
   • Se você não permitir a criação de contas por voz, o usuário será transferido para um navegador em que poderá carregar sua página de autorização e concluir o fluxo de criação de usuário.

Figura 2. Uma representação visual do fluxo de OAuth e Login do Google quando as informações de um usuário não são encontradas no seu sistema.

Criar contas de suporte por voz

Se você permitir a criação de contas de usuário por voz, o Google Assistente vai perguntar se o usuário quer fazer o seguinte:

• Crie uma conta no seu sistema usando as informações da Conta do Google dela ou
• Faça login no sistema de autenticação com outra conta, se ela tiver uma conta que não seja do Google.

Recomendamos permitir a criação de contas por voz se você quiser minimizar o atrito do fluxo de criação de contas. O usuário só precisa sair do fluxo de voz se quiser fazer login usando uma conta que não seja do Google.

Não permitir a criação de contas por voz

Se você não permitir a criação de contas de usuário por voz, o Google Assistente vai abrir o URL do site que você forneceu para autenticação do usuário. Se a interação estiver acontecendo em um dispositivo sem tela, o Google Assistente vai direcionar o usuário para um smartphone para continuar o fluxo de vinculação de contas.

Recomendamos desativar a criação se:

• Você não quer permitir que usuários com contas que não são do Google criem uma nova conta de usuário e quer que eles vinculem as contas de usuário atuais ao seu sistema de autenticação. Por exemplo, se você oferece um programa de fidelidade, talvez queira garantir que o usuário não perca os pontos acumulados na conta atual.

• Você precisa ter controle total do fluxo de criação de contas. Por exemplo, é possível impedir a criação se você precisar mostrar os Termos de Serviço ao usuário durante a criação da conta.

Observação: selecione uma das opções de fluxo abaixo para saber mais sobre a implementação do fluxo selecionado. Se necessário, o conteúdo do guia será atualizado para se adaptar à sua escolha.

Permitir a criação de contas por voz Não permitir a criação de contas por voz

Implementar a vinculação "simplificada" do login do Google baseada em OAuth

As contas são vinculadas com fluxos OAuth 2.0 padrão do setor. O Actions on Google é compatível com os fluxos implícito e de código de autorização.

Observação: se você estiver implementando a vinculação de contas para processar informações financeiras, outras políticas poderão ser aplicadas à sua ação. Pode levar até seis semanas para analisarmos uma ação com vinculação de conta para informações financeiras. Portanto, considere esse tempo ao planejar seu cronograma de lançamento. Para facilitar o processo de análise, verifique se você está em conformidade com as políticas de serviços financeiros antes de enviar sua ação para análise.

在隐式代码流程中，Google 会在用户浏览器中打开您的授权端点。成功登录后，系统会向 Google 返回长期访问令牌。现在，从 Google 助理向你的 Action 发送的每个请求中都包含此访问令牌。

在授权代码流程中，您需要两个端点：

• 授权端点，该端点负责向尚未登录的用户显示登录界面，并以短期授权代码的形式记录所请求的访问。
• 令牌交换端点，负责两种类型的交换：
  1. 将授权代码交换为长期刷新令牌和短期访问令牌。用户完成帐号关联流程后，系统会进行这种交换。
  2. 将长期刷新令牌换成短期访问令牌。Google 需要新访问令牌时，由于此令牌已过期，因此会进行此交换。

虽然隐式代码流程的实现更简单，但 Google 建议通过隐式流程发出的访问令牌永远不会过期，因为将令牌过期与隐式流程一起使用会强制用户再次关联其帐号。如果出于安全考虑需要令牌到期，强烈建议您考虑使用身份验证代码流程。

注意 ：请选择您希望实施的 OAuth 2.0 流程。如果需要，本指南的内容会根据您的选择重新加载。

身份验证代码 隐式流程

Configurar o projeto

Para configurar seu projeto para usar a vinculação simplificada, 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 Sim.

5. Em Tipo de vinculação, selecione OAuth e Login do Google e Implícito.

   

6. Em Informações do cliente, faça o seguinte:

   • Atribua um valor a ID do cliente emitido pelo Actions on Google para identificar solicitações do Google.
   • Insira os URLs dos endpoints de autorização e troca de token.

7. Clique em Salvar.

Implementar seu servidor OAuth

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

Quando seu Action precisa chamar uma das APIs autorizadas do serviço, o Google usa endpoint para obter permissão de seus usuários para chamar essas APIs em seus nome de usuário.

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. A o usuário faz login caso ainda não tenha feito isso e concede ao Google permissão para acessar os dados dele com a API, caso ainda não tenham concedido permissão.
2. Seu serviço cria um token de acesso e o retorna para o Google redirecionando o navegador do usuário de volta para o Google com o token de acesso; anexada à solicitação.
3. O Google chama as APIs do seu serviço e anexa o token de acesso com cada solicitação. O serviço verifica se o token de acesso concede ao Google autorização para acessar a API e, em seguida, conclui a chamada de API.

Processar solicitações de autorização

Quando sua ação precisar vincular a conta usando um fluxo implícito do OAuth 2.0, O Google envia o usuário para seu endpoint de autorização com uma solicitação que inclui os seguintes parâmetros:

Parâmetros de endpoint de autorização
client_id	O ID do cliente que você atribuiu ao Google.
redirect_uri	O URL para o qual você envia a resposta para essa solicitação.
state	Um valor de contabilidade que é retornado ao Google inalterado na URI de redirecionamento.
response_type	O tipo de valor a ser retornado na resposta. Para a implementação implícita do OAuth 2.0 fluxo, o tipo de resposta será sempre token.

Por exemplo, se o endpoint de autorização estiver disponível em https://myservice.example.com/auth, uma solicitação será semelhante a esta:

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

Para que o 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 clientes não intencionais ou configurados incorretamente:

   • Confirme se o client_id corresponde ao ID do cliente que você atribuídas ao Google.
   • Confirme se o URL especificado pelo 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 está conectado ao seu serviço. Se o usuário não tiver feito login conclua o fluxo de login ou inscrição do serviço.

3. Gere um token de acesso que o Google usará para acessar sua API. A token de acesso pode ser qualquer valor de string, mas deve representar exclusivamente o usuário e o cliente a que o token se destina 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 elementos parâmetros a seguir 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 do original. solicitação Veja a seguir um exemplo de 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 recebe o token de acesso e confirma que o valor state não mudou. Depois que o Google tiver token de acesso do seu serviço, o Google o anexa às chamadas subsequentes à sua ação como parte do AppRequest.

处理自动关联

在用户同意你的 Action 访问他们的 Google 个人资料后，Google 发送请求，其中包含 Google 用户身份的已签名断言。 该断言包含的信息包括用户的 Google 账号 ID、姓名、 和电子邮件地址。为项目配置的令牌交换端点处理 请求。

如果您的身份验证系统中已经存在相应的 Google 账号， 您的令牌交换端点为用户返回令牌。如果 Google 账号没有 匹配现有用户，您的令牌交换端点会返回 user_not_found 错误。

请求的格式如下：

POST /token HTTP/1.1
Host: oauth2.example.com
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&intent=get&assertion=JWT&consent_code=CONSENT_CODE&scope=SCOPES

您的令牌交换端点必须能够处理以下参数：

令牌端点参数
grant_type	所交换的令牌的类型。对于这类请求 参数的值为 urn:ietf:params:oauth:grant-type:jwt-bearer。
intent	对于这些请求，此参数的值为 `get`。
assertion	一个 JSON Web 令牌 (JWT)，提供 Google 用户身份。JWT 包含的信息包括 账号 ID、名称和电子邮件地址。
consent_code	可选：一个一次性代码（如果存在）用于表明 用户已同意你的 Action 访问指定范围。
scope	可选：您配置 Google 向用户请求的任何范围。

当您的令牌交换端点收到关联请求时，它应该 以下：

Valide e decodifique a declaração do JWT

É possível validar e decodificar a declaração JWT usando uma biblioteca de decodificação JWT para sua linguagem. Use as chaves públicas do Google, disponíveis no JWK (link em inglês) ou PEM) para verificar assinatura.

Observação: as chaves não podem ser fixadas no código. Siga as instruções da Descoberta de conexão do OpenID protocolo e verifique o cabeçalho cache-control para decidir por quanto tempo a chave deve ser armazenada em cache.

Quando decodificada, a declaração JWT se parece com o seguinte exemplo:

{
  "sub": 1234567890,        // The unique ID of the user's Google Account
  "iss": "https://accounts.google.com",        // The assertion's issuer
  "aud": "123-abc.apps.googleusercontent.com", // Your server's client ID
  "iat": 233366400,         // Unix timestamp of the assertion's creation time
  "exp": 233370000,         // Unix timestamp of the assertion's expiration time
  "name": "Jan Jansen",
  "given_name": "Jan",
  "family_name": "Jansen",
  "email": "[e-mail]", // If present, the user's email address
  "locale": "en_US"
}

Além de verificar a assinatura do token, verifique se o emissor da declaração (campo iss) é https://accounts.google.com e que o público-alvo (campo aud) é o ID do cliente atribuído à sua ação.

检查您的身份验证系统中是否已存在该 Google 账号

请检查以下任一条件是否成立：

• Google 账号 ID 可在断言的 sub 字段中找到，也可位于您的用户数据库中。
• 断言中的电子邮件地址与用户数据库中的用户匹配。

如果满足上述任一条件，则表明用户已经注册，您可以发出 访问令牌。

如果断言中指定的 Google 账号 ID 和电子邮件地址都没有 与您数据库中的用户匹配，表示该用户尚未注册。在这种情况下，您的 令牌交换端点应回复 HTTP 401 错误，指定 error=user_not_found， 如以下示例中所示：

HTTP/1.1 401 Unauthorized
Content-Type: application/json;charset=UTF-8

{
  "error":"user_not_found",
}

当 Google 收到包含 user_not_found 错误的 401 错误响应时， 使用 intent 参数的值调用您的令牌交换端点 设置为 create 并发送包含用户个人资料信息的 ID 令牌 一起发送。

Processar a criação de contas pelo Login do Google

Quando um usuário precisa criar uma conta no seu serviço, o Google solicitação ao seu endpoint de troca de token que especifica intent=create, como no exemplo abaixo:

POST /token HTTP/1.1
Host: oauth2.example.com
Content-Type: application/x-www-form-urlencoded

response_type=token&grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&scope=SCOPES&intent=create&consent_code=CONSENT_CODE&assertion=JWT[&NEW_ACCOUNT_INFO]

O parâmetro assertion contém um JSON Web Token (JWT) que fornece uma declaração assinada da identidade do usuário do Google. O JWT contém informações incluindo o ID, o nome e o endereço de e-mail da Conta do Google do usuário, que você pode usar para criar uma nova conta no serviço.

Para responder a solicitações de criação de conta, seu endpoint de troca de token precisa: o seguinte:

Valide e decodifique a declaração do JWT

É possível validar e decodificar a declaração JWT usando uma biblioteca de decodificação JWT para sua linguagem. Use as chaves públicas do Google, disponíveis no JWK (link em inglês) ou PEM) para verificar assinatura.

Observação: as chaves não podem ser fixadas no código. Siga as instruções da Descoberta de conexão do OpenID protocolo e verifique o cabeçalho cache-control para decidir por quanto tempo a chave deve ser armazenada em cache.

Quando decodificada, a declaração JWT se parece com o seguinte exemplo:

{
  "sub": 1234567890,        // The unique ID of the user's Google Account
  "iss": "https://accounts.google.com",        // The assertion's issuer
  "aud": "123-abc.apps.googleusercontent.com", // Your server's client ID
  "iat": 233366400,         // Unix timestamp of the assertion's creation time
  "exp": 233370000,         // Unix timestamp of the assertion's expiration time
  "name": "Jan Jansen",
  "given_name": "Jan",
  "family_name": "Jansen",
  "email": "[e-mail]", // If present, the user's email address
  "locale": "en_US"
}

Além de verificar a assinatura do token, verifique se o emissor da declaração (campo iss) é https://accounts.google.com e que o público-alvo (campo aud) é o ID do cliente atribuído à sua ação.

Valide as informações do usuário e crie uma nova conta

Verifique se uma das condições a seguir é verdadeira:

• O ID da Conta do Google, encontrado no campo sub da declaração, está no seu banco de dados de usuários.
• O endereço de e-mail na declaração corresponde a um usuário no seu banco de dados de usuários.

Se uma das condições for verdadeira, solicite que o usuário vincule a conta atual dele com sua Conta do Google respondendo à solicitação com um erro HTTP 401, especificando error=linking_error e o endereço de e-mail do usuário como login_hint, como no exemplo a seguir:

HTTP/1.1 401 Unauthorized
Content-Type: application/json;charset=UTF-8

{
  "error":"linking_error",
  "login_hint":"[e-mail]"
}

Se nenhuma das condições for verdadeira, crie uma nova conta de usuário usando as informações. fornecidos no JWT. Em geral, novas contas não têm uma senha definida. É recomendamos que você adicione o Login do Google a outras plataformas para permitir que os usuários façam login pelo Google em todas as plataformas do seu aplicativo. Também é possível enviar ao usuário um link por e-mail que inicie seu fluxo de recuperação de senha para permitir que ele defina uma senha para fazer login em outras plataformas.

Quando a criação for concluída, emita um token de acesso e retorna os valores em um objeto JSON o corpo da sua resposta HTTPS, como no exemplo a seguir:

{
  "token_type": "Bearer",
  "access_token": "ACCESS_TOKEN",
  
  "expires_in": SECONDS_TO_EXPIRATION
}

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

Aviso:não peça aos usuários para vincular uma conta no início da conversa com sua ação. Em vez disso, ofereça aos usuários não autenticados um fluxo de convidados para mostrar como sua ação funciona e só peça a vinculação de contas se for necessário para continuar. Se os usuários estiverem abandonando a ação de forma consistente devido a problemas de vinculação de conta, o Google não vai promover ativamente a ação, o que pode diminuir o tráfego de usuários dela.

Observação: você precisa usar o Actions Builder para criar uma ação que implemente a vinculação de contas.

Verificar se o usuário está 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 de contas na sua ação:
   1. Clique em Cenas.
   2. Clique no ícone de adição (+) 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, a Ação não poderá vincular contas durante a conversa e precisará oferecer acesso a funcionalidades que não exigem 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 uma cena que seja o ponto de entrada para a funcionalidade somente para convidados.

1. Clique no ícone de adição em Condições.
2. Adicione uma condição para acionar um fluxo de vinculação de contas 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 conta.
   3. Clique em Salvar.

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

Personalizar a cena de vinculação de conta

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 de contas.
2. Configure como o fluxo vai prosseguir 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 volte 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 de contas.
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 oferecem funcionalidades que não exigem vinculação de contas.
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 a vinculação de conta não puder ser concluída devido a erros de sistema ou de rede. Por exemplo, envie uma mensagem de confirmação e redirecione para cenas que oferecem funcionalidades que não exigem vinculação de contas.
3. 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 é válido e não expirou. Depois, recupere do banco de dados da conta de usuário a conta associada ao token.