Vinculación de cuentas con OAuth y Acceso con Google (Dialogflow)

El tipo de vinculación OAuth y Acceso con Google agrega el Acceso con Google a la vinculación de cuentas basada en OAuth. Esto proporciona una vinculación basada en la voz sin interrupciones para los usuarios de Google y, al mismo tiempo, permite la vinculación de cuentas para los usuarios que se registraron en tu servicio con una identidad ajena a Google.

Este tipo de vinculación comienza con el Acceso con Google, que te permite verificar si la información de perfil de Google del usuario existe en tu sistema. Si no se encuentra la información del usuario en tu sistema, se iniciará un flujo de OAuth estándar. El usuario también puede elegir crear una cuenta nueva con la información de su perfil de Google.

Figura 1: Después de que tu acción obtiene acceso al perfil de Google del usuario, puedes usarlo para encontrar una coincidencia para el usuario en tu sistema de autenticación.

Para vincular cuentas con OAuth y el Acceso con Google, sigue estos pasos generales:

1. En primer lugar, pídele al usuario que otorgue su consentimiento para acceder a su perfil de Google.
2. Utilizar la información de su perfil para identificar al usuario
3. Si no puedes encontrar una coincidencia para el usuario de Google en tu sistema de autenticación, el flujo continúa dependiendo de si configuraste tu proyecto de acciones en la Consola de Actions para permitir la creación de cuentas de usuario con la voz o solo en tu sitio web.
   • Si permites la creación de cuentas por voz, valida el token de ID que recibiste de Google. Luego, puedes crear un usuario según la información de perfil que contiene el token de ID.
   • Si no permites la creación de cuentas por voz, el usuario se transfiere a un navegador en el que puede cargar tu página de autorización y completar el flujo de creación de usuarios.

Figura 2: Representación visual del flujo de OAuth y Acceso con Google cuando no se encuentra la información de un usuario en tu sistema.

Cómo admitir la creación de cuentas mediante la voz

Si permites la creación de cuentas de usuario por voz, Asistente le preguntará al usuario si desea hacer lo siguiente:

• Crear una cuenta nueva en el sistema con la información de la Cuenta de Google
• Accede al sistema de autenticación con una cuenta diferente si ya tiene una Cuenta que no es de Google.

Se recomienda permitir la creación de cuentas mediante la voz si deseas minimizar los inconvenientes del flujo de creación de cuentas. El usuario solo debe abandonar el flujo de voz si quiere acceder con una cuenta existente que no sea de Google.

No permitir la creación de cuentas con la voz

Si inhabilitaste la creación de cuentas de usuario por voz, Asistente abrirá la URL que te dirigirá al sitio web que proporcionaste para la autenticación del usuario. Si la interacción ocurre en un dispositivo que no tiene pantalla, Asistente dirigirá al usuario a un teléfono para continuar con el flujo de vinculación de cuentas.

Se recomienda no permitir la creación en los siguientes casos:

• No quieres permitir que los usuarios que tienen cuentas ajenas a Google creen una cuenta de usuario nueva y quieres que se vinculen a sus cuentas de usuario existentes en tu sistema de autenticación. Por ejemplo, si ofreces un programa de lealtad, es posible que quieras asegurarte de que el usuario no pierda los puntos acumulados en su cuenta existente.

• Debes tener el control total del flujo de creación de cuentas. Por ejemplo, puedes inhabilitar la creación si necesitas mostrarle tus Condiciones del Servicio al usuario durante el proceso.

Nota: Selecciona una de las siguientes opciones de flujo para obtener más información sobre la implementación del flujo seleccionado. Si es necesario, el contenido de la guía se volverá a cargar para adaptarlo a tu elección.

Permitir la creación de cuentas mediante la voz No permitir la creación de cuentas mediante la voz

Implementa la vinculación de cuentas de OAuth y Acceso con Google

Las cuentas están vinculadas con los flujos OAuth 2.0 estándares de la industria. Actions on Google admite los flujos de código implícito y de autorización.

Nota: Si estás implementando la vinculación de cuentas para administrar información financiera, ten en cuenta que podrían aplicarse políticas adicionales a tu Acción. La revisión de una Acción con vinculación de cuentas para información financiera puede tardar hasta seis semanas, por lo que debes tener en cuenta ese tiempo cuando planifiques tu programa de lanzamientos. Para facilitar el proceso de revisión, asegúrate de cumplir con las políticas de servicios financieros antes de enviar tu Acción a revisión.

In the implicit code flow, Google opens your authorization endpoint in the user's browser. After successful sign in, you return a long-lived access token to Google. This access token is now included in every request sent from the Assistant to your Action.

In the authorization code flow, you need two endpoints:

• The authorization endpoint, which is responsible for presenting the sign-in UI to your users that aren't already signed in and recording consent to the requested access in the form of a short-lived authorization code.
• The token exchange endpoint, which is responsible for two types of exchanges:
  1. Exchanges an authorization code for a long-lived refresh token and a short-lived access token. This exchange happens when the user goes through the account linking flow.
  2. Exchanges a long-lived refresh token for a short-lived access token. This exchange happens when Google needs a new access token because the one it had expired.

Although the implicit code flow is simpler to implement, Google recommends that access tokens issued using the implicit flow never expire, because using token expiration with the implicit flow forces the user to link their account again. If you need token expiration for security reasons, you should strongly consider using the auth code flow instead.

Note: Please choose which OAuth2 flow you want to implement. If needed, the content of this guide reloads to adapt to your choice.

Auth code Implicit flow

Configura el proyecto

Si deseas configurar tu proyecto para usar la vinculación de cuentas de OAuth y Acceso con Google, sigue estos pasos:

1. Abre la Consola de Actions y selecciona el proyecto que deseas usar.
2. Haz clic en la pestaña Desarrollo y selecciona Vinculación de cuentas.
3. Habilita el interruptor junto a Vinculación de cuentas.
4. En la sección Creación de cuenta, selecciona Sí.

5. En Tipo de vinculación, selecciona Implícito y OAuth y Acceso con Google.

   

6. En Información del cliente, haz lo siguiente:

   • Asigna un valor al ID de cliente emitido por tus acciones a Google para identificar las solicitudes que provienen de Google.
   • Inserta las URL para tus extremos de autorización y de intercambio de tokens.

7. Haz clic en Guardar.

Implementa tu servidor OAuth

Para admitir el flujo implícito de OAuth 2.0, tu servicio pone a disposición un extremo de autorización mediante HTTPS. Este extremo es responsable de autenticar y obtener el consentimiento de los usuarios para el acceso a los datos. El extremo de autorización presenta una IU de acceso a los usuarios que aún no accedieron y registra su consentimiento para el acceso solicitado.

Cuando tu Acción necesita llamar a una de las APIs autorizadas de tu servicio, Google usa este extremo a fin de obtener permiso de los usuarios para llamar a estas APIs en su nombre.

Una sesión típica de flujo implícito de OAuth 2.0 que inicia Google tiene el siguiente flujo:

1. Google abrirá tu extremo de autorización en el navegador del usuario. El usuario accede si aún no lo ha hecho y le otorga permiso a Google para acceder a sus datos con tu API si aún no lo ha hecho.
2. Tu servicio crea un token de acceso y lo muestra a Google. Para ello, redirecciona el navegador del usuario a Google con el token de acceso adjunto a la solicitud.
3. Google llama a las APIs de tu servicio y adjunta el token de acceso a cada solicitud. El servicio verifica que el token de acceso otorgue a Google autorización para acceder a la API y, luego, completa la llamada a la API.

Cómo controlar solicitudes de autorización

Cuando tu Acción necesita realizar una vinculación de cuentas a través de un flujo implícito de OAuth2, Google envía al usuario a tu extremo de autorización con una solicitud que incluye los siguientes parámetros:

Parámetros del extremo de autorización
client_id	El ID de cliente que asignaste a Google.
redirect_uri	La URL a la que envías la respuesta a esta solicitud.
state	Es un valor de contabilidad que se pasa a Google sin cambios en el URI de redireccionamiento.
response_type	Es el tipo de valor que se muestra en la respuesta. Para el flujo implícito de OAuth 2.0, el tipo de respuesta siempre es token.

Por ejemplo, si tu extremo de autorización está disponible en https://myservice.example.com/auth, una solicitud podría verse de la siguiente manera:

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

Para que tu extremo de autorización controle las solicitudes de acceso, sigue estos pasos:

1. Verifica los valores client_id y redirect_uri para evitar otorgar acceso a apps cliente no deseadas o mal configuradas:

   • Confirma que el client_id coincida con el ID de cliente que asignaste a Google.
   • Confirma que la URL que especifica el parámetro redirect_uri tenga el siguiente formato:

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

     YOUR_PROJECT_ID es el ID que se encuentra en la página Configuración del proyecto de la Consola de Actions.

2. Verifica si el usuario accedió a tu servicio. Si el usuario no accedió, completa el flujo de acceso o registro de tu servicio.

3. Genera un token de acceso que Google usará para acceder a tu API. El token de acceso puede ser cualquier valor de string, pero debe representar de manera inequívoca al usuario y al cliente para el que se trata el token, y no debe ser adivinable.

4. Envía una respuesta HTTP que redireccione el navegador del usuario a la URL que especifica el parámetro redirect_uri. Incluye todos los siguientes parámetros en el fragmento de URL:

   • access_token: Es el token de acceso que acabas de generar.
   • token_type: Es la cadena bearer.
   • state: Es el valor del estado sin modificar de la solicitud original. El siguiente es un ejemplo de la URL resultante:

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

El controlador de redireccionamiento de OAuth 2.0 de Google recibirá el token de acceso y confirmará que el valor state no cambió. Después de que Google haya obtenido un token de acceso para tu servicio, lo adjuntará a las llamadas posteriores a tu acción como parte de AppRequest.

Handle automatic linking

After the user gives your Action consent to access their Google profile, Google sends a request that contains a signed assertion of the Google user's identity. The assertion contains information that includes the user's Google Account ID, name, and email address. The token exchange endpoint configured for your project handles that request.

If the corresponding Google account is already present in your authentication system, your token exchange endpoint returns a token for the user. If the Google account doesn't match an existing user, your token exchange endpoint returns a user_not_found error.

The request has the following form:

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

Your token exchange endpoint must be able to handle the following parameters:

Token endpoint parameters
grant_type	The type of token being exchanged. For these requests, this parameter has the value urn:ietf:params:oauth:grant-type:jwt-bearer.
intent	For these requests, the value of this parameter is `get`.
assertion	A JSON Web Token (JWT) that provides a signed assertion of the Google user's identity. The JWT contains information that includes the user's Google Account ID, name, and email address.
consent_code	Optional: When present, a one-time code that indicates that the user has granted consent for your Action to access the specified scopes.
scope	Optional: Any scopes you configured Google to request from users.

When your token exchange endpoint receives the linking request, it should do the following:

验证和解码 JWT 断言

您可以使用适合您的语言的 JWT 解码库来验证和解码 JWT 断言。使用 Google 的公钥（以 JWK 或 PEM 格式提供）来验证令牌的签名。

注意 ：键不应采用硬编码。而应按照 OpenID connect Discovery Protocol 并检查 cache-control 标头，以确定应将密钥缓存多长时间。

解码后，JWT 断言如下所示：

{
  "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"
}

除了验证令牌的签名之外，请验证断言的颁发者（iss 字段）是否为 https://accounts.google.com，以及目标对象群组（aud 字段）是否为分配给您的 Action 的客户端 ID。

Check if the Google account is already present in your authentication system

Check whether either of the following conditions are true:

• The Google Account ID, found in the assertion's sub field, is in your user database.
• The email address in the assertion matches a user in your user database.

If either condition is true, the user has already signed up and you can issue an access token.

If neither the Google Account ID nor the email address specified in the assertion matches a user in your database, the user hasn't signed up yet. In this case, your token exchange endpoint should reply with a HTTP 401 error, that specifies error=user_not_found, as in the following example:

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

{
  "error":"user_not_found",
}

When Google receives the 401 error response with a user_not_found error, Google calls your token exchange endpoint with the value of the intent parameter set to create and sending an ID token that contains the user's profile information with the request.

Handle account creation via Google Sign-In

When a user needs to create an account on your service, Google makes a request to your token exchange endpoint that specifies intent=create, as in the following example:

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]

The assertion parameter contains A JSON Web Token (JWT) that provides a signed assertion of the Google user's identity. The JWT contains information that includes the user's Google Account ID, name, and email address, which you can use to create a new account on your service.

To respond to account creation requests, your token exchange endpoint must do the following:

验证和解码 JWT 断言

您可以使用适合您的语言的 JWT 解码库来验证和解码 JWT 断言。使用 Google 的公钥（以 JWK 或 PEM 格式提供）来验证令牌的签名。

注意 ：键不应采用硬编码。而应按照 OpenID connect Discovery Protocol 并检查 cache-control 标头，以确定应将密钥缓存多长时间。

解码后，JWT 断言如下所示：

{
  "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"
}

除了验证令牌的签名之外，请验证断言的颁发者（iss 字段）是否为 https://accounts.google.com，以及目标对象群组（aud 字段）是否为分配给您的 Action 的客户端 ID。

Validate user information and create new account

Check whether either of the following conditions are true:

• The Google Account ID, found in the assertion's sub field, is in your user database.
• The email address in the assertion matches a user in your user database.

If either condition is true, prompt the user to link their existing account with their Google Account by responding to the request with an HTTP 401 error, specifying error=linking_error and the user's email address as the login_hint, as in the following example:

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

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

If neither condition is true, create a new user account using the information provided in the JWT. New accounts do not typically have a password set. It is recommended that you add Google Sign In to other platforms to enable users to log in via Google across the surfaces of your application. Alternatively, you can email the user a link that starts your password recovery flow to allow the user to set a password for signing in on other platforms.

When the creation is completed, issue an access token and return the values in a JSON object in the body of your HTTPS response, like in the following example:

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

Inicia el flujo de autenticación

Advertencia: No proporciones a los usuarios una solicitud de vinculación de cuenta obligatoria al comienzo de la conversación con tu acción. En su lugar, proporciona a los usuarios no autenticados un flujo de invitado para mostrar cómo funciona tu acción y, luego, solicita la vinculación de cuentas solo si es necesario para continuar. Si los usuarios abandonan la Acción de manera constante debido a problemas de vinculación de cuentas, Google no la promocionará de forma activa, lo que podría disminuir su tráfico de usuarios.

Ten en cuenta que solo los usuarios verificados pueden vincular cuentas. Si el usuario es un invitado, la vinculación de cuentas fallará. Obtén más información para identificar y administrar a los usuarios invitados.

Usa el intent auxiliar de acceso a la cuenta para iniciar el flujo de autenticación.

Dialogflow (Node.js)

const app = dialogflow({
  // REPLACE THE PLACEHOLDER WITH THE CLIENT_ID OF YOUR ACTIONS PROJECT
  clientId: CLIENT_ID,
})

// Intent that starts the account linking flow.
app.intent('Start Signin', conv => {
  conv.ask(new SignIn('To get your account details'))
})

Dialogflow (Java)

private String clientId = "<your_client_id>";

@ForIntent("Start Signin")
public ActionResponse text(ActionRequest request) {
  ResponseBuilder rb = getResponseBuilder(request);
  return rb.add(new SignIn().setContext("To get your account details")).build();
}

SDK de Actions (Node.js)

const app = actionssdk({
  clientId: CLIENT_ID,
})

app.intent('Start Signin', conv => {
  conv.ask(new SignIn('To get your account details'))
})

SDK de Actions (Java)

private String clientId = "<your_client_id>";

@ForIntent("actions.intent.TEXT")
public ActionResponse text(ActionRequest request) {
  ResponseBuilder rb = getResponseBuilder(request);
  return rb.add(new SignIn().setContext("To get your account details")).build();
}

Controla las solicitudes de acceso a los datos

Si la solicitud de Asistente contiene un token de acceso, primero verifica que el token de acceso sea válido y no haya vencido. Luego, recupera la cuenta de usuario asociada con el token en tu base de datos de la cuenta de usuario.