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 Código de autorização.
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.
- Anote o valor do ID do cliente emitido pelo Google para suas Ações.
- Insira os URLs dos endpoints de autorização e de troca de tokens.
- Clique em Salvar.
Implementar o servidor OAuth
Uma implementação do servidor OAuth 2.0 do fluxo do código de autorização consiste em dois endpoints que seu serviço disponibiliza por HTTPS. O primeiro é o de autorização, responsável por encontrar ou receber o consentimento dos usuários para acessar os 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. O segundo é o endpoint de troca de token, usado para receber strings criptografadas chamadas de tokens que autorizam o usuário da ação a acessar seu serviço.
Quando a Ação precisa chamar uma das APIs do serviço, o Google usa esses endpoints juntos para receber permissão dos usuários para chamar essas APIs em nome deles.
A sessão do fluxo do código de autenticação do OAuth 2.0 iniciada pelo Google tem o seguinte fluxo:
- O Google abre seu endpoint de autorização no navegador do usuário. Se o fluxo começasse em um dispositivo que só usa voz para uma ação, o Google transferiria a execução para um smartphone.
O usuário faz login (se ainda não tiver feito isso) e concede permissão ao Google para acessar os dados com sua API, caso ainda não tenha concedido.
O serviço cria um código de autorização e o retorna ao Google redirecionando o navegador do usuário de volta para o Google com o código de autorização anexado à solicitação.
O Google envia o código de autorização para o endpoint de troca de token, que verifica a autenticidade do código e retorna um token de acesso e um token de atualização. O token de acesso é de curta duração e é aceito pelo seu serviço como credenciais para acessar APIs. O token de atualização é de longa duração e pode ser armazenado pelo Google para adquirir novos tokens de acesso quando eles expirarem.
Depois que o usuário concluir o fluxo de vinculação da conta, todas as solicitações subsequentes enviadas do Google Assistente para o webhook de fulfillment vão conter um token de acesso.
Processar solicitações de autorização
Quando sua Ação precisa fazer a vinculação de contas por um fluxo de código de autorização 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 do Google que você registrou no Google. |
redirect_uri |
O URL para onde você envia a resposta para a solicitação. |
state |
Um valor de registro que é retornado ao Google inalterado no URI de redirecionamento. |
scope |
Opcional: um conjunto de strings de escopo delimitado por espaço que especifica para quais dados o Google está solicitando autorização. |
response_type |
A string code . |
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&scope=REQUESTED_SCOPES&response_type=code
Para que o endpoint de autorização processe solicitações de login, siga estas etapas:
Verifique se o
client_id
corresponde ao ID do cliente do Google registrado no Google e seredirect_uri
corresponde ao URL de redirecionamento fornecido pelo Google para seu serviço. Essas verificações são importantes para evitar a concessão de acesso a apps cliente não intencionais ou configurados incorretamente.Se você oferece suporte a vários fluxos do OAuth 2.0, confirme também se
response_type
écode
.Verifique se o usuário está conectado ao serviço. Se o usuário não estiver conectado, conclua o fluxo de inscrição ou login do seu serviço.
Gere um código de autorização que o Google usará para acessar sua API. O código de autorização pode ser qualquer valor de string, mas precisa representar exclusivamente o usuário, o cliente ao qual o token se destina e o prazo de validade do código. Além disso, ele não pode ser adivinhado. Normalmente, códigos de autorização que expiram em aproximadamente 10 minutos são emitidos.
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.Redirecione o navegador do usuário para o URL especificado pelo parâmetro
redirect_uri
. Inclua o código de autorização que você acabou de gerar e o valor do estado original e não modificado ao redirecionar anexando os parâmetroscode
estate
. Este é um exemplo do URL resultante:https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID?code=AUTHORIZATION_CODE&state=STATE_STRING
Processar solicitações de troca de token
O endpoint de troca de token do seu serviço é responsável por dois tipos de trocas de tokens:
- Troque códigos de autorização por tokens de acesso e de atualização
- Trocar tokens de atualização por tokens de acesso
As solicitações de troca de token incluem os seguintes parâmetros:
Parâmetros de endpoint de troca de token | |
---|---|
client_id |
String que identifica a origem da solicitação como o Google. Essa string precisa ser registrada no seu sistema como o identificador exclusivo do Google. |
client_secret |
Uma string secreta que você registrou no Google para seu serviço. |
grant_type |
O tipo de token que está sendo trocado. authorization_code ou refresh_token . |
code |
Quando grant_type=authorization_code , o código que o Google
recebeu do endpoint de login ou de troca de token. |
redirect_uri |
Quando grant_type=authorization_code , esse parâmetro é o URL usado na solicitação de autorização inicial. |
refresh_token |
Quando grant_type=refresh_token , o token de atualização que o Google recebeu do endpoint de troca de token. |
Troque códigos de autorização por tokens de acesso e de atualização
Depois que o usuário faz login e o endpoint de autorização retorna um código de autorização de curta duração para o Google, o Google envia uma solicitação ao endpoint de troca de token para trocar o código de autorização por um token de acesso e um token de atualização.
Para essas solicitações, o valor de grant_type
é authorization_code
, e o valor
de code
é o valor do código de autorização concedido anteriormente ao Google.
Veja a seguir um exemplo de solicitação para trocar um código de autorização por um
token de acesso e um de atualização:
POST /token HTTP/1.1 Host: oauth2.example.com Content-Type: application/x-www-form-urlencoded client_id=GOOGLE_CLIENT_ID&client_secret=GOOGLE_CLIENT_SECRET&grant_type=authorization_code&code=AUTHORIZATION_CODE&redirect_uri=REDIRECT_URI
Para trocar códigos de autorização por um token de acesso e um token de atualização, o
endpoint de troca de token responde a solicitações POST
executando as seguintes etapas:
- Verifique se o
client_id
identifica a origem da solicitação como uma origem autorizada e seclient_secret
corresponde ao valor esperado. - Verifique o seguinte:
- O código de autorização é válido e não expirou, e o ID do cliente especificado na solicitação corresponde ao ID do cliente associado ao código de autorização.
- O URL especificado pelo parâmetro
redirect_uri
é idêntico ao valor usado na solicitação de autorização inicial.
- Se não for possível verificar todos os critérios acima, retorne um erro
HTTP 400 de solicitação inválida com
{"error": "invalid_grant"}
como o corpo. - Caso contrário, usando o ID do usuário do código de autorização, gere um token de atualização e um token de acesso. Esses tokens podem ser qualquer valor de string, mas precisam representar exclusivamente o usuário e o cliente ao qual o token se destina e não podem ser adivinhados. Para tokens de acesso, registre também o prazo de validade do token (normalmente uma hora após a emissão). Os tokens de atualização não expiram.
- Retorne o seguinte objeto JSON no corpo da resposta HTTPS:
{ "token_type": "Bearer", "access_token": "ACCESS_TOKEN", "refresh_token": "REFRESH_TOKEN", "expires_in": SECONDS_TO_EXPIRATION }
O Google armazena o token de acesso e de atualização do usuário e registra a expiração do token de acesso. O Google usa o token de atualização para receber um novo do endpoint de troca de tokens quando ele expira.
Trocar tokens de atualização por tokens de acesso
Quando um token de acesso expira, o Google envia uma solicitação ao seu endpoint de troca de token para trocar um token de atualização por um novo.
Para essas solicitações, o valor de grant_type
é refresh_token
, e o valor
de refresh_token
é o valor do token de atualização concedido anteriormente ao Google.
Veja a seguir um exemplo de solicitação para trocar um token de atualização por um
de acesso:
POST /token HTTP/1.1 Host: oauth2.example.com Content-Type: application/x-www-form-urlencoded client_id=GOOGLE_CLIENT_ID&client_secret=GOOGLE_CLIENT_SECRET&grant_type=refresh_token&refresh_token=REFRESH_TOKEN
Para trocar um token de atualização por um de acesso, o endpoint de troca de token responde às solicitações POST
executando as seguintes etapas:
- Verifique se o
client_id
identifica a origem da solicitação como Google e seclient_secret
corresponde ao valor esperado. - Verifique se o token de atualização é válido e se o ID do cliente especificado na solicitação corresponde ao ID do cliente associado ao token de atualização.
- Se não for possível verificar todos os critérios acima, retorne um erro
HTTP 400 de solicitação inválida com
{"error": "invalid_grant"}
como o corpo. - Caso contrário, use o ID do usuário do token de atualização para gerar um token de acesso. Esses tokens podem ser qualquer valor de string, mas precisam representar exclusivamente o usuário e o cliente ao qual o token se destina e não podem ser adivinhados. Para tokens de acesso, registre também o prazo de validade do token (normalmente uma hora após a emissão).
- Retorne o seguinte objeto JSON no corpo da resposta
HTTPS:
{ "token_type": "Bearer", "access_token": "ACCESS_TOKEN", "expires_in": SECONDS_TO_EXPIRATION }
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.