Se usó la API de Cloud Translation para traducir esta página.

Vinculación optimizada con OAuth y Acceso con Google

Descripción general

La vinculación optimizada para el Acceso con Google basada en OAuth agrega el Acceso con Google además de la vinculación OAuth. Esto proporciona una experiencia de vinculación fluida a los usuarios de Google y también permite la creación de cuentas, lo que permite al usuario crear una nueva cuenta en tu servicio con su Cuenta de Google.

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

Primero, pídele al usuario que dé su consentimiento para acceder a su perfil de Google.
Usa la información de su perfil para verificar si la cuenta de usuario existe.
Para los usuarios existentes, vincule las cuentas.
Si no puedes encontrar una coincidencia para el usuario de Google en tu sistema de autenticación, valida el token de ID recibido de Google. Luego, puedes crear un usuario en función de la información de perfil que contiene el token de ID.

En esta figura, se muestran los pasos que debe seguir un usuario para vincular su Cuenta de Google con el flujo de vinculación optimizado. La primera captura de pantalla muestra cómo un usuario puede seleccionar tu app para la vinculación. La segunda captura de pantalla permite al usuario confirmar si tiene o no una cuenta en tu servicio. La tercera captura de pantalla permite al usuario seleccionar la cuenta de Google que desea vincular. La cuarta captura de pantalla muestra la confirmación de que se vinculó la Cuenta de Google con tu app. La quinta captura de pantalla muestra una cuenta de usuario vinculada correctamente en Google app.

Figura 1: Vinculación de cuentas en el teléfono de un usuario con la Vinculación optimizada

Requisitos de la vinculación optimizada

Implementa el flujo de vinculación web OAuth básica. Tu servicio debe ser compatible con los extremos de autorización y intercambio de tokens que cumplan con OAuth 2.0.
El extremo del intercambio de tokens debe admitir aserciones de token web JSON (JWT) e implementar los intents check, create y get.

Registra tu ID de cliente de la API de Google.

Implementa tu servidor OAuth

Tu extremo de intercambio de tokens debe admitir los intents check, create y get. A continuación, se muestran los pasos completados a través del flujo de vinculación de la cuenta y se indica cuándo se llama a los diferentes intents:

¿El usuario tiene una cuenta en tu sistema de autenticación? (El usuario elige SÍ o NO)
1. SÍ: ¿El usuario usa el correo electrónico asociado con su Cuenta de Google para acceder a tu plataforma? (El usuario elige SÍ o NO)
  1. SÍ: ¿El usuario tiene una cuenta coincidente en tu sistema de autenticación? (check intent se llama para confirmar)
    1. SÍ : Se llama a get intent y la cuenta se vincula si el intent get se muestra correctamente.
    2. NO: ¿Desea crear una cuenta nueva? (El usuario elige SÍ o NO)
      1. SÍ : Se llama a create intent y la cuenta se vincula si se muestra correctamente el intent de creación.
      2. NO : Se activa el flujo de OAuth web, se dirige al usuario a su navegador y se le da la opción de vincularlo con un correo electrónico diferente.
  2. NO : Se activa el flujo de OAuth web, se redirecciona al usuario a su navegador y se le da la opción de vincularlo con un correo electrónico diferente.
2. NO: ¿El usuario tiene una cuenta coincidente en tu sistema de autenticación? (check intent se llama para confirmar)
  1. SÍ : Se llama a get intent y la cuenta se vincula si el intent get se muestra correctamente.
  2. NO : Se llama a create intent, y la cuenta se vincula si se crea correctamente el intent de creación.

Verificar una cuenta de usuario existente (verificar intent)

Después de que el usuario da su consentimiento para acceder a su perfil de Google, Google envía una solicitud que contiene una aserción firmada de la identidad del usuario de Google. La aserción contiene información que incluye el ID, el nombre y la dirección de correo electrónico de la Cuenta de Google del usuario. El extremo de intercambio de tokens configurado para tu proyecto controla esa solicitud.

Si la Cuenta de Google correspondiente ya está presente en el sistema de autenticación, tu extremo de intercambio de tokens responde con account_found=true. Si la Cuenta de Google no coincide con un usuario existente, el extremo del intercambio de tokens muestra un error HTTP 404 Not Found (No encontrado) con account_found=false.

La solicitud tiene el siguiente 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=check&assertion=JWT&scope=SCOPES&client_id=GOOGLE_CLIENT_ID&client_secret=GOOGLE_CLIENT_SECRET

El extremo del intercambio de tokens debe admitir los siguientes parámetros:

Parámetros del extremo del token
`intent`	Para estas solicitudes, el valor de este parámetro es `check`.
`grant_type`	El tipo de token que se intercambia. Para estas solicitudes, este parámetro tiene el valor `urn:ietf:params:oauth:grant-type:jwt-bearer`.
`assertion`	Un token web JSON (JWT) que proporciona una aserción firmada de la identidad del usuario de Google. El JWT contiene información que incluye el ID, el nombre y la dirección de correo electrónico de la Cuenta de Google del usuario.
`client_id`	El ID de cliente que le asignaste a Google
`client_secret`	El secreto de cliente que asignaste a Google

Para responder a las solicitudes de intent check, el extremo de intercambio de tokens debe realizar los siguientes pasos:

Valida y decodifica la aserción de JWT.
Verifica si la Cuenta de Google ya está presente en el sistema de autenticación.

Validar y decodificar la aserción JWT

Puede validar y decodificar la aserción JWT utilizando una biblioteca de decodificación JWT para su idioma . Utilice las claves públicas de Google, disponibles en formatos JWK o PEM , para verificar la firma del token.

Cuando se decodifica, la aserción JWT se parece al siguiente ejemplo:

{
  "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
  "email_verified": true,   // true, if Google has verified the email address
  "hd": "example.com",      // If present, the host domain of the user's GSuite email address
                            // If present, a URL to user's profile picture
  "picture": "https://lh3.googleusercontent.com/a-/AOh14GjlTnZKHAeb94A-FmEbwZv7uJD986VOF1mJGb2YYQ",
  "locale": "en_US"         // User's locale, from browser or phone settings
}

Además de verificar la firma del token, verifique que el emisor de la afirmación (campo iss ) sea https://accounts.google.com , que la audiencia (campo aud ) sea su ID de cliente asignado y que el token no haya caducado ( exp campo).

Con los campos email , email_verified y hd puede determinar si Google aloja y tiene autoridad para una dirección de correo electrónico. En los casos en que Google tiene autoridad, se sabe que el usuario es el propietario legítimo de la cuenta y puede omitir la contraseña u otros métodos de desafío. De lo contrario, estos métodos se pueden utilizar para verificar la cuenta antes de vincularla.

Casos en los que Google tiene autoridad:

email tiene un sufijo @gmail.com , esta es una cuenta de Gmail.
email_verified es verdadero y hd está configurado, esta es una cuenta de G Suite.

Los usuarios pueden registrarse para obtener cuentas de Google sin usar Gmail o G Suite. Cuando el email no contiene un sufijo @gmail.com y no hay hd Google no tiene autoridad y se recomienda utilizar una contraseña u otros métodos de desafío para verificar al usuario. email_verfied también puede ser cierto ya que Google verificó inicialmente al usuario cuando se creó la cuenta de Google, sin embargo, la propiedad de la cuenta de correo electrónico de terceros puede haber cambiado desde entonces.

Verifica si la Cuenta de Google ya está presente en el sistema de autenticación

Verifica si se cumple alguna de las siguientes condiciones:

El ID de la Cuenta de Google, que se encuentra en el campo sub de la aserción, se encuentra en tu base de datos de usuarios.
La dirección de correo electrónico en la aserción coincide con un usuario de la base de datos de usuarios.

Si se cumple alguna de las dos condiciones, el usuario ya se registró. En ese caso, muestra una respuesta como la siguiente:

HTTP/1.1 200 Success
Content-Type: application/json;charset=UTF-8

{
  "account_found":"true",
}

Si ni el ID de la Cuenta de Google ni la dirección de correo electrónico especificada en la aserción coinciden con un usuario de la base de datos, este todavía no se registró. En este caso, el extremo del intercambio de tokens debe responder con un error HTTP 404 que especifique "account_found": "false", como en el siguiente ejemplo:

HTTP/1.1 404 Not found
Content-Type: application/json;charset=UTF-8

{
  "account_found":"false",
}

处理自动链接（获取 intent）

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

如果您的身份验证系统中已存在相应的 Google 帐号，则您的令牌交换端点会返回用户的令牌。如果 Google 帐号与现有用户不匹配，您的令牌交换端点会返回 linking_error 错误和可选的 login_hint。

请求的格式如下：

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&scope=SCOPES&client_id=GOOGLE_CLIENT_ID&client_secret=GOOGLE_CLIENT_SECRET

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

令牌端点参数
`intent`	对于这些请求，此参数的值为 `get`。
`grant_type`	要交换的令牌的类型。对于这些请求，此参数的值为 `urn:ietf:params:oauth:grant-type:jwt-bearer`。
`assertion`	一个 JSON Web 令牌 (JWT)，用于提供 Google 用户身份的签名断言。JWT 包含用户的 Google 帐号 ID、姓名和电子邮件地址等信息。
`scope`	可选：您已将 Google 配置为向用户请求的任何范围。
`client_id`	您分配给 Google 的客户端 ID。
`client_secret`	您分配给 Google 的客户端密钥。

为了响应 get intent 请求，您的令牌交换端点必须执行以下步骤：

验证并解码 JWT 断言。
检查您的身份验证系统中是否已存在该 Google 帐号。

Validar y decodificar la aserción JWT

Cuando se decodifica, la aserción JWT se parece al siguiente ejemplo:

{
  "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
  "email_verified": true,   // true, if Google has verified the email address
  "hd": "example.com",      // If present, the host domain of the user's GSuite email address
                            // If present, a URL to user's profile picture
  "picture": "https://lh3.googleusercontent.com/a-/AOh14GjlTnZKHAeb94A-FmEbwZv7uJD986VOF1mJGb2YYQ",
  "locale": "en_US"         // User's locale, from browser or phone settings
}

Casos en los que Google tiene autoridad:

email tiene un sufijo @gmail.com , esta es una cuenta de Gmail.
email_verified es verdadero y hd está configurado, esta es una cuenta de G Suite.

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

检查是否满足以下任一条件：

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

如果找到了用户的帐号，请发出访问令牌，并在 HTTPS 响应的正文中以 JSON 对象形式返回值，如以下示例所示：

{
  "token_type": "Bearer",
  "access_token": "ACCESS_TOKEN",

  "expires_in": SECONDS_TO_EXPIRATION
}

在某些情况下，基于 ID 令牌的帐号关联可能会为用户失败。如果出现任何此类情况，您的令牌交换端点都需要使用返回 error=linking_error 的 HTTP 401 错误进行响应，如以下示例所示：

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

{
  "error":"linking_error",
  "login_hint":"foo@bar.com"
}

Google 收到包含 linking_error 的 401 错误响应后，会将用户作为授权参数 login_hint 发送到您的授权端点。用户在浏览器中使用 OAuth 关联流程完成帐号关联。

通过 Google 登录功能创建帐号（创建 intent）

当用户需要在您的服务上创建帐号时，Google 会向您的令牌交换端点发出请求，并指定 intent=create。

请求的格式如下：

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&assertion=JWT&client_id=GOOGLE_CLIENT_ID&client_secret=GOOGLE_CLIENT_SECRET

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

令牌端点参数
`intent`	对于这些请求，此参数的值为 `create`。
`grant_type`	要交换的令牌的类型。对于这些请求，此参数的值为 `urn:ietf:params:oauth:grant-type:jwt-bearer`。
`assertion`	一个 JSON Web 令牌 (JWT)，用于提供 Google 用户身份的签名断言。JWT 包含用户的 Google 帐号 ID、姓名和电子邮件地址等信息。
`client_id`	您分配给 Google 的客户端 ID。
`client_secret`	您分配给 Google 的客户端密钥。

assertion 参数中的 JWT 包含用户的 Google 帐号 ID、名称和电子邮件地址，您可以使用这些信息在服务中创建新帐号。

为了响应 create intent 请求，您的令牌交换端点必须执行以下步骤：

验证并解码 JWT 断言。
验证用户信息并创建新帐号。

Validar y decodificar la aserción JWT

Cuando se decodifica, la aserción JWT se parece al siguiente ejemplo:

{
  "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
  "email_verified": true,   // true, if Google has verified the email address
  "hd": "example.com",      // If present, the host domain of the user's GSuite email address
                            // If present, a URL to user's profile picture
  "picture": "https://lh3.googleusercontent.com/a-/AOh14GjlTnZKHAeb94A-FmEbwZv7uJD986VOF1mJGb2YYQ",
  "locale": "en_US"         // User's locale, from browser or phone settings
}

Casos en los que Google tiene autoridad:

email tiene un sufijo @gmail.com , esta es una cuenta de Gmail.
email_verified es verdadero y hd está configurado, esta es una cuenta de G Suite.

验证用户信息并创建新帐号

检查是否满足以下任一条件：

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

如果任一条件为 true，请提示用户将其现有帐号与其 Google 帐号相关联。为此，请对请求进行响应，并提供指定 error=linking_error 并将用户的电子邮件地址作为 login_hint 的 HTTP 401 错误。以下是一个示例响应：

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

{
  "error":"linking_error",
  "login_hint":"foo@bar.com"
}

如果两个条件都不满足，请使用 JWT 中提供的信息创建新的用户帐号。新帐号通常不会设置密码。建议您将 Google 登录功能添加到其他平台，以便用户能够在应用界面使用 Google 帐号登录。或者，您也可以通过电子邮件向用户发送一个启动密码恢复流程的链接，以便用户设置密码以在其他平台上登录。

创建完成后，发出访问令牌，并在 HTTPS 响应的正文中以 JSON 对象形式返回值，如以下示例所示：

{
  "token_type": "Bearer",
  "access_token": "ACCESS_TOKEN",

  "expires_in": SECONDS_TO_EXPIRATION
}

Obtén tu ID de cliente de la API de Google

Deberá proporcionar su ID de cliente de la API de Google durante el proceso de registro de la vinculación de cuentas.

Para obtener tu ID de cliente de la API mediante el proyecto que creaste mientras completaste los pasos de vinculación de OAuth. Para ello, completa los siguientes pasos:

Abre la página Credenciales de la consola de la API de Google.
Crea o selecciona un proyecto de las API de Google.

Si tu proyecto no tiene un ID de cliente para el tipo de aplicación web, haz clic en Crear credenciales > ID de cliente de OAuth para crear uno. Asegúrate de incluir el dominio de tu sitio en el cuadro Orígenes autorizados de JavaScript. Cuando realizas pruebas o desarrollos locales, debes agregar http://localhost y http://localhost:<port_number> al campo Orígenes autorizados de JavaScript.

Punto clave: Agrega http://localhost y http://localhost:<port_number> al campo Orígenes autorizados de JavaScript para pruebas o desarrollos locales.
Nota: Un ID de cliente se parece al siguiente ejemplo:
```
1234567890-abc123def456.apps.googleusercontent.com
```

Cómo validar la implementación

您可以通过使用验证实现的OAuth 2.0游乐场工具。

在工具中，执行以下步骤：

单击配置打开的OAuth 2.0配置窗口。
在OAuth流场中，选择客户端。
在OAuth端点字段中，选择自定义。
在相应字段中指定您的 OAuth 2.0 端点和您分配给 Google 的客户端 ID。
在步骤1部分，不要选择任何谷歌范围。相反，将此字段留空或键入对您的服务器有效的范围（如果不使用 OAuth 范围，则输入任意字符串）。当您完成后，单击授权的API。
在步骤2和步骤3段，完成OAuth 2.0流程和验证每个步骤按预期工作。

您可以通过验证您的实现谷歌帐户链接演示工具。

在工具中，执行以下步骤：

点击登录在与谷歌按钮。
选择您要关联的帐户。
输入服务标识。
（可选）输入您将请求访问的一个或多个范围。
单击开始演示。
出现提示时，确认您可以同意并拒绝链接请求。
确认您被重定向到您的平台。