Esta página foi traduzida pela API Cloud Translation.

Vinculação de conta com o login do Google baseado em login "Simplificado"

O tipo de vinculação "simplificada" do Login do Google com base em OAuth adiciona o Login do Google à vinculação de conta baseada em OAuth. Isso fornece uma vinculação por voz perfeita para usuários do Google, além de ativar a vinculação de contas para usuários que se registraram 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 Google do usuário existem no 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 optar por criar uma nova conta com as informações do perfil do Google.

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

Para realizar a vinculação de conta com o tipo de vinculação simplificada, siga estas etapas gerais:

Primeiro, peça para o usuário autorizar o acesso ao perfil do Google.
Use as informações no perfil para identificar o usuário.
Se não for possível encontrar uma correspondência para o usuário do Google no seu sistema de autenticação, o fluxo prossegue, dependendo de você ter configurado seu projeto do Actions no Console do Actions para permitir a criação de conta de usuário por voz ou apenas em seu site.
- Se você permitir a criação de conta por voz, valide o token de código recebido do Google. Em seguida, crie um usuário com base nas informações de perfil contidas no token de ID.
- Se você não permitir a criação de conta por voz, o usuário será transferido para um navegador em que ele poderá carregar a página de autorização e concluir o fluxo de criação de usuário.

Se você permitir a criação de conta por voz e não encontrar uma correspondência para o perfil do Google no seu sistema de autenticação, precisará validar o token de ID recebido do Google. Em seguida, crie um usuário com base nas informações de perfil contidas no token de ID.
Se você não permitir a criação de uma conta de usuário por voz, ele será transferido para um navegador em que poderá carregar a página de autorização e concluir o fluxo. — **Figura 2**. Uma representação visual do fluxo do OAuth e do Login do Google quando as informações de um usuário não são encontradas no seu sistema.

Suporte para criação de conta por voz

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

criar uma nova conta no seu sistema usando as informações da Conta do Google; ou
Faça login no seu sistema de autenticação com uma conta diferente se ela já tiver uma conta que não seja do Google.

Se você quiser minimizar o fluxo de criação da conta, permita a criação de contas por voz. 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 conta por voz

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

É recomendável não permitir a criação se:

Você não quer permitir que usuários que tenham contas que não sejam do Google criem uma nova conta de usuário e vincule-os às contas de usuário existentes no sistema de autenticação deles. Por exemplo, se você oferece um programa de fidelidade, convém garantir que o usuário não perca os pontos acumulados na conta existente.
Você precisa ter controle total do fluxo de criação de contas. Por exemplo, você pode desativar a criação se precisar mostrar os Termos de Serviço ao usuário durante a criação da conta.

Implementar a vinculação simplificada do Login do Google com base em OAuth

As contas são vinculadas a fluxos do OAuth 2.0 padrão do setor. O Actions on Google é compatível com os fluxos de código de autorização implícitos 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.

Configurar o projeto

Para configurar seu projeto para usar a vinculação simplificada, 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 Sim.
Em Tipo de vinculação, selecione OAuth e Login do Google e Implicit.
Em Informações do cliente, faça o seguinte:
- 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.
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:

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.
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.
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:

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.
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.
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.
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.

Gerenciar vinculação automática

Depois que o usuário autoriza a ação a acessar o perfil do Google, ele envia uma solicitação com uma declaração assinada de identidade do usuário. A declaração contém informações que incluem o ID, o nome e o endereço de e-mail da Conta do Google do usuário. O endpoint de troca de token configurado para seu projeto processa essa solicitação.

Se a Conta do Google correspondente já estiver presente no seu sistema de autenticação, o endpoint de troca de token retornará um token para o usuário. Se a Conta do Google não corresponder a um usuário atual, o endpoint de troca de token retornará um erro user_not_found.

A solicitação tem o seguinte formato:

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

Seu endpoint de troca de token precisa processar os seguintes parâmetros:

Parâmetros de endpoint do token
`grant_type`	O tipo de token sendo trocado. Para essas solicitações, o parâmetro tem o valor `urn:ietf:params:oauth:grant-type:jwt-bearer`.
`intent`	Para essas solicitações, o valor desse parâmetro é `get`.
`assertion`	Um JSON Web Token (JWT) que fornece uma declaração assinada de identidade do usuário do Google. O JWT contém informações que incluem o ID, o nome e o endereço de e-mail da Conta do Google do usuário.
`consent_code`	Opcional: quando presente, um código único que indica que o usuário permitiu a ação para acessar os escopos especificados.
`scope`	Opcional: os escopos que você configurou o Google para solicitar aos usuários.

Quando o endpoint de troca de token recebe a solicitação de vinculação, ele precisa:

Validar e decodificar a declaração JWT

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

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": "jan@gmail.com", // 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 se o público (campo aud) é o ID do cliente atribuído à sua ação.

Verificar se a Conta do Google já está presente no sistema de autenticação

Verifique se uma das seguintes condições é 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, o usuário já se inscreveu, e você pode emitir um token de acesso.

Se o ID da Conta do Google e o endereço de e-mail especificados na declaração não corresponderem a um usuário no seu banco de dados, o usuário ainda não se inscreveu. Nesse caso, o endpoint de troca de token responderá com um erro HTTP 401, que especifica error=user_not_found, como no exemplo a seguir:

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

{
  "error":"user_not_found",
}

Quando o Google recebe a resposta de erro 401 com um erro user_not_found, ele chama o endpoint de troca de token com o valor do parâmetro intent definido como create e envia um token de ID que contém as informações de perfil do usuário com a solicitação.

Processar a criação da conta pelo Login do Google

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

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 de identidade do usuário do Google. O JWT contém informações que incluem o ID, o nome e o endereço de e-mail da Conta do Google do usuário, que podem ser usados para criar uma nova conta no serviço.

Para responder às solicitações de criação de conta, o endpoint de troca de token precisa fazer o seguinte:

Validar e decodificar a declaração JWT

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": "jan@gmail.com", // If present, the user's email address
  "locale": "en_US"
}

Validar as informações do usuário e criar uma nova conta

Verifique se uma das seguintes condições é 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 alguma das condições for verdadeira, solicite que o usuário vincule a conta existente à 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":"foo@bar.com"
}

Se nenhuma das condições for verdadeira, crie uma nova conta de usuário usando as informações fornecidas no JWT. As novas contas geralmente não têm uma senha definida. É recomendável adicionar o Login do Google a outras plataformas para permitir que os usuários façam login por meio do Google nas plataformas do seu aplicativo. Se preferir, envie um e-mail ao usuário com um link que inicie o fluxo de recuperação de senha para permitir que ele defina uma senha para fazer login em outras plataformas.

Quando a criação estiver concluída, emita um token de acesso e retorne os valores em um objeto JSON no corpo da 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 do Voice para o fluxo de autenticação

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

Abra seu projeto do Actions Builder no Console do Actions.
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.
Na cena recém-criada, clique no ícone de adição para Condições.
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.

Clique no ícone de adição 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.
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

Em Cenas, 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 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.
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 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.
Clique em Salvar.

Em Condições, clique em Se ocorrer um erro de sistema ou de rede.
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.
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. Em seguida, recupere do banco de dados da conta de usuário a conta de usuário associada ao token.