Descripción general
La vinculación optimizada del Acceso con Google basado en OAuth agrega el Acceso con Google por encima de Vinculación de OAuth. Esto proporciona una experiencia de vinculación fluida para a los usuarios de Google y, además, habilita la creación de cuentas, que les permite crear una cuenta nueva en tu servicio con su Cuenta de Google.
Para vincular las cuentas con OAuth y el Acceso con Google, sigue estas indicaciones generales pasos:
- En primer lugar, solicita al usuario que dé su consentimiento para acceder a su perfil de Google.
- Usa la información de su perfil para comprobar si existe la cuenta de usuario.
- Para los usuarios existentes, vincula las cuentas.
- Si no encuentras una coincidencia para el usuario de Google en tu sistema de autenticación, validar el token de ID que se recibió de Google. Luego, puedes crear un usuario basado en en la información de perfil que se encuentra en el token de ID.
![En esta figura, se muestran los pasos para que un usuario vincule 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 vincularla. La segunda captura de pantalla le permite al usuario confirmar si tiene una cuenta existente en tu servicio. La tercera captura de pantalla le permite al usuario seleccionar la Cuenta de Google con la que desea vincularse. La cuarta captura de pantalla muestra la confirmación para vincular su Cuenta de Google con tu app. En la quinta captura de pantalla, se muestra una cuenta de usuario vinculada correctamente en la app de Google.](https://developers-dot-devsite-v2-prod.appspot.com/static/identity/account-linking/images/streamlined-linking-flow.png?authuser=4&hl=es)
Figura 1. Vinculación de cuentas en el teléfono de un usuario con la vinculación optimizada
Requisitos para una vinculación optimizada
- Implementa el flujo de vinculación web básica de OAuth. Tu servicio debe ser compatible con OAuth 2.0 extremos de autorización e intercambio de token.
- El extremo de intercambio de tokens debe admitir aserciones de token web JSON (JWT) y, además, implementar los intents
check
,create
yget
.
Implementa tu servidor de OAuth
El 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 cuentas y se indica cuándo se llama a los diferentes intents:
- ¿El usuario tiene una cuenta en tu sistema de autenticación? (El usuario decide si selecciona SÍ o NO)
- SÍ: ¿El usuario usa el correo electrónico asociado a su Cuenta de Google para acceder a tu plataforma? (El usuario decide si selecciona SÍ o NO)
- SÍ: ¿El usuario tiene una cuenta que coincida en tu sistema de autenticación? (Se llama a
check intent
para confirmar).- SÍ : Se llama a
get intent
y se vincula la cuenta si se muestra correctamente el intent GET. - NO, ¿crear una cuenta nueva? (El usuario decide si selecciona SÍ o NO)
- SÍ : Si se muestra correctamente el intent de creación, se llama a
create intent
y se vincula la cuenta. - NO : Se activa el flujo de OAuth web, se dirige al usuario a su navegador y el usuario tiene la opción de vincularse con un correo electrónico diferente.
- SÍ : Si se muestra correctamente el intent de creación, se llama a
- SÍ : Se llama a
- NO : Se activa el flujo de OAuth web, se dirige al usuario a su navegador y se le ofrece la opción de vincular con un correo electrónico diferente.
- SÍ: ¿El usuario tiene una cuenta que coincida en tu sistema de autenticación? (Se llama a
- NO: ¿El usuario tiene una cuenta que coincida en tu sistema de autenticación? (Se llama a
check intent
para confirmar).- SÍ : Se llama a
get intent
y se vincula la cuenta si se muestra correctamente el intent GET. - NO : Se llama a
create intent
y se vincula la cuenta si se muestra correctamente el intent de creación.
- SÍ : Se llama a
- SÍ: ¿El usuario usa el correo electrónico asociado a su Cuenta de Google para acceder a tu plataforma? (El usuario decide si selecciona SÍ o NO)
Cómo comprobar si hay una cuenta de usuario existente (verificar intención)
Una vez que el usuario da su consentimiento para acceder a su perfil de Google, Google envía un solicitud que incluya una aserción firmada de la identidad del usuario de Google. El contiene información que incluye el ID de la Cuenta de Google del usuario, y tu dirección de correo electrónico. El extremo de intercambio de tokens configurado para tu el proyecto se encargará de esa solicitud.
Si la Cuenta de Google correspondiente ya está presente en tu autenticación
de intercambio de tokens, tu extremo de intercambio de tokens responde con account_found=true
. Si el botón
La Cuenta de Google no coincide con un usuario existente, tu extremo de intercambio de token
muestra un error HTTP 404 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 de intercambio de tokens debe ser capaz de controlar los siguientes parámetros:
Parámetros de 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
tiene el valor urn:ietf:params:oauth:grant-type:jwt-bearer . |
assertion |
Un token web JSON (JWT) que proporciona una aserción firmada del token de Google la identidad del usuario. El JWT contiene información que incluye los datos ID, nombre y dirección de correo electrónico de la Cuenta de Google. |
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 tu sistema de autenticación.
Validate and decode the JWT assertion
You can validate and decode the JWT assertion by using a JWT-decoding library for your language. Use Google's public keys, available in JWK or PEM formats, to verify the token's signature.
When decoded, the JWT assertion looks like the following example:
{ "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 }
In addition to verifying the token's signature, verify that the assertion's
issuer (iss
field) is https://accounts.google.com
, that the audience
(aud
field) is your assigned client ID, and that the token has not expired
(exp
field).
Using the email
, email_verified
and hd
fields you can determine if
Google hosts and is authoritative for an email address. In cases where Google is
authoritative the user is currently known to be the legitimate account owner
and you may skip password or other challenges methods. Otherwise, these methods
can be used to verify the account prior to linking.
Cases where Google is authoritative:
email
has a@gmail.com
suffix, this is a Gmail account.email_verified
is true andhd
is set, this is a G Suite account.
Users may register for Google Accounts without using Gmail or G Suite. When
email
does not contain a @gmail.com
suffix and hd
is absent Google is not
authoritative and password or other challenge methods are recommended to verify
the user. email_verified
can also be true as Google initially verified the
user when the Google account was created, however ownership of the third party
email account may have since changed.
Verifica si la Cuenta de Google ya está presente en tu 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, está en tu usuario en la base de datos. - La dirección de correo electrónico en la aserción coincide con un usuario de tu base de datos de usuarios.
Si se cumple alguna de estas condiciones, el usuario ya se registró. En ese caso, devolver una respuesta como la siguiente:
HTTP/1.1 200 Success Content-Type: application/json;charset=UTF-8 { "account_found":"true", }
Si no se especifica el ID de la Cuenta de Google ni la dirección de correo electrónico
coincide con un usuario de tu base de datos, el usuario aún no se registró. En
en este caso, el extremo de 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 la vinculación automática (obtener intent)
Una vez que el usuario da su consentimiento para acceder a su perfil de Google, Google envía un solicitud que incluya una aserción firmada de la identidad del usuario de Google. El contiene información que incluye el ID de la Cuenta de Google del usuario, y tu dirección de correo electrónico. El extremo de intercambio de tokens configurado para tu el proyecto se encargará de esa solicitud.
Si la Cuenta de Google correspondiente ya está presente en tu autenticación
tu extremo de intercambio de tokens devuelve un token al usuario. Si el botón
La Cuenta de Google no coincide con un usuario existente, tu extremo de intercambio de token
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 de intercambio de tokens debe ser capaz de controlar los siguientes parámetros:
Parámetros de 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
tiene el valor urn:ietf:params:oauth:grant-type:jwt-bearer . |
assertion |
Un token web JSON (JWT) que proporciona una aserción firmada del token de Google la identidad del usuario. El JWT contiene información que incluye los datos ID, nombre y dirección de correo electrónico de la Cuenta de Google. |
scope |
Opcional: Cualquier alcance que hayas configurado Google para que solicite solicitudes 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 tu sistema de autenticación.
Validate and decode the JWT assertion
You can validate and decode the JWT assertion by using a JWT-decoding library for your language. Use Google's public keys, available in JWK or PEM formats, to verify the token's signature.
When decoded, the JWT assertion looks like the following example:
{ "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 }
In addition to verifying the token's signature, verify that the assertion's
issuer (iss
field) is https://accounts.google.com
, that the audience
(aud
field) is your assigned client ID, and that the token has not expired
(exp
field).
Using the email
, email_verified
and hd
fields you can determine if
Google hosts and is authoritative for an email address. In cases where Google is
authoritative the user is currently known to be the legitimate account owner
and you may skip password or other challenges methods. Otherwise, these methods
can be used to verify the account prior to linking.
Cases where Google is authoritative:
email
has a@gmail.com
suffix, this is a Gmail account.email_verified
is true andhd
is set, this is a G Suite account.
Users may register for Google Accounts without using Gmail or G Suite. When
email
does not contain a @gmail.com
suffix and hd
is absent Google is not
authoritative and password or other challenge methods are recommended to verify
the user. email_verified
can also be true as Google initially verified the
user when the Google account was created, however ownership of the third party
email account may have since changed.
Verifica si la Cuenta de Google ya está presente en tu 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, está en tu usuario en la base de datos. - La dirección de correo electrónico en la aserción coincide con un usuario de tu 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 la respuesta HTTPS, como en el siguiente ejemplo:
{ "token_type": "Bearer", "access_token": "ACCESS_TOKEN", "expires_in": SECONDS_TO_EXPIRATION }
En algunos casos, la vinculación de cuentas basada en un token de ID podría fallar para el usuario. Si
lo hace por alguna razón, tu extremo de intercambio de token debe responder con un
401 que especifica 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
, Google envía
al usuario al extremo de autorización con login_hint
como parámetro. El
El usuario completa la vinculación de la cuenta con el flujo de vinculación de OAuth en su navegador.
Controla la creación de cuentas mediante el Acceso con Google (crea un intent)
Cuando un usuario necesita crear una cuenta en tu servicio, Google realiza una solicitud.
al extremo de intercambio de tokens que especifique 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
El extremo de intercambio de tokens debe poder controlar los siguientes parámetros:
Parámetros de 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
tiene el valor urn:ietf:params:oauth:grant-type:jwt-bearer . |
assertion |
Un token web JSON (JWT) que proporciona una aserción firmada del token de Google la identidad del usuario. El JWT contiene información que incluye los datos ID, nombre y dirección de correo electrónico de la Cuenta de Google. |
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 de la Cuenta de Google del usuario.
y tu dirección de correo electrónico, que podrás 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.
- Valida la información del usuario y crea una cuenta nueva.
Validate and decode the JWT assertion
You can validate and decode the JWT assertion by using a JWT-decoding library for your language. Use Google's public keys, available in JWK or PEM formats, to verify the token's signature.
When decoded, the JWT assertion looks like the following example:
{ "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 }
In addition to verifying the token's signature, verify that the assertion's
issuer (iss
field) is https://accounts.google.com
, that the audience
(aud
field) is your assigned client ID, and that the token has not expired
(exp
field).
Using the email
, email_verified
and hd
fields you can determine if
Google hosts and is authoritative for an email address. In cases where Google is
authoritative the user is currently known to be the legitimate account owner
and you may skip password or other challenges methods. Otherwise, these methods
can be used to verify the account prior to linking.
Cases where Google is authoritative:
email
has a@gmail.com
suffix, this is a Gmail account.email_verified
is true andhd
is set, this is a G Suite account.
Users may register for Google Accounts without using Gmail or G Suite. When
email
does not contain a @gmail.com
suffix and hd
is absent Google is not
authoritative and password or other challenge methods are recommended to verify
the user. email_verified
can also be true as Google initially verified the
user when the Google account was created, however ownership of the third party
email account may have since changed.
Validar la información del usuario y crear 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, está en tu usuario en la base de datos. - La dirección de correo electrónico en la aserción coincide con un usuario de tu base de datos de usuarios.
Si se cumple alguna de estas condiciones, solicita al usuario que vincule su cuenta existente.
con su Cuenta de Google. Para ello, responde la solicitud con un error HTTP 401
que especifique error=linking_error
y proporcione la dirección de correo electrónico del usuario como el
login_hint
A continuación, se muestra una respuesta de 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
, Google envía
al usuario al extremo de autorización con login_hint
como parámetro. El
El usuario completa la vinculación de la cuenta con el flujo de vinculación de OAuth en su navegador.
Si ninguna condición es verdadera, crea una nueva cuenta de usuario con la información. proporcionadas en el JWT. Las cuentas nuevas no suelen tener una contraseña establecida. Es se recomendó agregar Acceso con Google a otras plataformas para permitir que los usuarios acceda con Google en todas las plataformas de su aplicación. Como alternativa, puedes enviarle al usuario un vínculo que inicie el flujo de recuperación de la contraseña para configurar una contraseña para acceder en otras plataformas.
Cuando se complete la creación, emite un token de acceso y se mostrarán los valores de un objeto JSON en el cuerpo de la respuesta HTTPS, como en el siguiente ejemplo:
{ "token_type": "Bearer", "access_token": "ACCESS_TOKEN", "expires_in": SECONDS_TO_EXPIRATION }
Obtén tu ID de cliente de la API de Google
Tendrá que 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 API con el proyecto que creaste mientras completaste los pasos de la Vinculación con OAuth. Para ello, completa los siguientes pasos:
- Abre la página Credenciales de la Consola de APIs de Google.
Crea o selecciona un proyecto de las APIs 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 para pruebas o desarrollo locales, debes agregar
http://localhost
yhttp://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:
- 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.