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

Cómo controlar vínculos automáticos (obtener intent)

Si la Cuenta de Google correspondiente ya está presente en el sistema de autenticación, el extremo del intercambio de tokens muestra un token al usuario. Si la Cuenta de Google no coincide con un usuario existente, el extremo del intercambio de tokens muestra un error linking_error y un login_hint opcional.

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=get&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 `get`.
`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.
`scope`	Opcional: Cualquier alcance que hayas configurado para que Google solicite a los usuarios.
`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 get, 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

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.

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 encuentra una cuenta para el usuario, emite un token de acceso 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
}

En algunos casos, es posible que el usuario no pueda vincular su cuenta según el token de ID. Si lo hace por cualquier motivo, el extremo de intercambio de tokens debe responder con un error HTTP 401 que especifique error=linking_error, como se muestra en el siguiente ejemplo:

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.

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

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.

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

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:

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

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

En la herramienta, siga los siguientes pasos:

Haga clic en Configuración de para abrir la ventana de configuración de OAuth 2.0.
En el campo de flujo de OAuth, seleccione el lado del cliente.
En el campo de OAuth puntos finales, seleccione Personalizar.
Especifique su punto final de OAuth 2.0 y el ID de cliente que asignó a Google en los campos correspondientes.
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.
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:

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