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:

  1. Primero, pídele al usuario que dé su consentimiento para acceder a su perfil de Google.
  2. Usa la información de su perfil para verificar si la cuenta de usuario existe.
  3. Para los usuarios existentes, vincule las cuentas.
  4. 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 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:

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

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.

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

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

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

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

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

  "refresh_token": "REFRESH_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 关联流程完成帐号关联。

Controla la creación de cuentas mediante el Acceso con Google (crear intent)

Cuando un usuario necesita crear una cuenta en tu servicio, Google realiza una solicitud a tu extremo del intercambio de tokens que especifica intent=create.

La solicitud tiene el siguiente formato:

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

Tu extremo de 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 create.
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

El JWT dentro del parámetro assertion contiene el ID, el nombre y la dirección de correo electrónico de la Cuenta de Google del usuario, que puedes usar para crear una cuenta nueva en tu servicio.

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

  • Valida y decodifica la aserción de JWT.
  • Valide la información de los usuarios y cree una cuenta nueva.
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.

Valide la información de los usuarios y cree una cuenta nueva

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, pídele al usuario que vincule su cuenta existente con la Cuenta de Google. Para hacerlo, responde a la solicitud con un error HTTP 401 que especifique error=linking_error y proporcione la dirección de correo electrónico del usuario como login_hint. La siguiente es una respuesta de muestra:

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

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

Cuando Google recibe una respuesta de error 401 con linking_error, envía al usuario al extremo de autorización con login_hint como parámetro. El usuario completa la vinculación de cuentas mediante el flujo de vinculación de OAuth en su navegador.

Si ninguna de las condiciones es verdadera, crea una cuenta de usuario nueva con la información proporcionada en el JWT. Por lo general, las cuentas nuevas no tienen una contraseña establecida. Se recomienda que agregues el Acceso con Google a otras plataformas para permitir que los usuarios accedan con Google a través de las plataformas de tu aplicación. Como alternativa, puedes enviarle por correo electrónico un vínculo que inicie el flujo de recuperación de contraseña para que el usuario pueda configurar una contraseña de acceso en otras plataformas.

Cuando se complete la creación, emite un token de acceso y un token de actualización y muestra los valores en un objeto JSON en el cuerpo de tu respuesta HTTPS, como en el siguiente ejemplo:

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

  "refresh_token": "REFRESH_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:

  1. Abre la página Credenciales de la consola de la API de Google.
  2. 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.

Cómo validar la implementación

Puede validar su aplicación mediante el uso de la Zona de juegos OAuth 2.0 herramienta.

En la herramienta, siga los siguientes pasos:

  1. Haga clic en Configuración de para abrir la ventana de configuración de OAuth 2.0.
  2. En el campo de flujo de OAuth, seleccione el lado del cliente.
  3. En el campo de OAuth puntos finales, seleccione Personalizar.
  4. Especifique su punto final de OAuth 2.0 y el ID de cliente que asignó a Google en los campos correspondientes.
  5. En la sección Paso 1, no seleccione ninguna alcances de Google. En su lugar, deje este campo en blanco o escriba un ámbito válido para su servidor (o una cadena arbitraria si no utiliza ámbitos OAuth). Cuando haya terminado, haga clic en Autorizar API.
  6. En las secciones Paso 2 y el Paso 3, vaya a través del flujo de OAuth 2.0 y verificar que cada paso funciona como se pretende.

Puede validar su aplicación mediante el uso de la cuenta de Google Vinculación demostración herramienta.

En la herramienta, siga los siguientes pasos:

  1. Haga clic en el Inicio de sesión con el botón de Google.
  2. Elija la cuenta que desea vincular.
  3. Ingrese la identificación del servicio.
  4. Opcionalmente, ingrese uno o más ámbitos para los que solicitará acceso.
  5. Haga clic en Inicio de demostración.
  6. Cuando se le solicite, confirme que puede dar su consentimiento y rechazar la solicitud de vinculación.
  7. Confirme que se le redirige a su plataforma.