Las APIs de OAuth 2.0 de Google se pueden usar para la autenticación y la autorización. En este documento, se describe nuestra implementación de OAuth 2.0 para la autenticación, que cumple con la especificación de OpenID Connect y cuenta con la certificación de OpenID. La documentación que se encuentra en Usa OAuth 2.0 para acceder a las APIs de Google también se aplica a este servicio. Si deseas explorar este protocolo de forma interactiva, te recomendamos Google OAuth 2.0 Playground. Para obtener ayuda en Stack Overflow, etiqueta tus preguntas con "google-oauth".
Cómo configurar OAuth 2.0
Para que tu aplicación pueda usar el sistema de autenticación de OAuth 2.0 de Google para el acceso de los usuarios, debes configurar un proyecto en Google API Console para obtener credenciales de OAuth 2.0, establecer un URI de redireccionamiento y, de manera opcional, personalizar la información de desarrollo de la marca que ven los usuarios en la pantalla de consentimiento. También puedes usar API Console para crear una cuenta de servicio, habilitar la facturación, configurar el filtrado y realizar otras tareas. Para obtener más detalles, consulta la ayuda deGoogle API Console.
Obtén credenciales de OAuth 2.0
Necesitas credenciales de OAuth 2.0, incluido un ID de cliente y un secreto del cliente, para autenticar a los usuarios y obtener acceso a las APIs de Google.
Para ver la ID del cliente y el secreto del cliente para una credencial OAuth 2.0 dada, haga clic en el siguiente texto: Seleccionar credencial . En la ventana que se abre, elija su proyecto y la credencial que desea, luego haga clic en Ver .
O vea su ID de cliente y el secreto del cliente desde la página de Credenciales en API Console :
- Go to the Credentials page.
- Haga clic en el nombre de su credencial o en el ícono de lápiz ( create ). Su ID de cliente y secreto están en la parte superior de la página.
Configura un URI de redireccionamiento
El URI de redireccionamiento que configuraste en API Console determina adónde envía Google las respuestas a tus solicitudes de autenticación.
To create, view, or edit the redirect URIs for a given OAuth 2.0 credential, do the following:
- Go to the Credentials page.
- In the OAuth 2.0 client IDs section of the page, click a credential.
- View or edit the redirect URIs.
If there is no OAuth 2.0 client IDs section on the Credentials page, then your project has no OAuth credentials. To create one, click Create credentials.
Cómo personalizar la pantalla de consentimiento del usuario
Para los usuarios, la experiencia de autenticación de OAuth 2.0 incluye una pantalla de consentimiento que describe la información que el usuario publica y los términos que se aplican. Por ejemplo, cuando el usuario accede, es posible que se le solicite que permita que tu app acceda a su dirección de correo electrónico y a la información básica de la cuenta. Solicitas acceso a esta información con el parámetro scope
, que tu app incluye en su solicitud de autenticación. También puedes usar alcances para solicitar acceso a otras APIs de Google.
La pantalla de consentimiento del usuario también presenta información de desarrollo de la marca, como el nombre y el logotipo de tu producto, y una URL de página principal. Tú controlas la información de desarrollo de la marca en API Console.
Para habilitar la pantalla de consentimiento de su proyecto:
- Abra el Consent Screen page en el Google API Console .
- If prompted, select a project, or create a new one.
- Rellene el formulario y haga clic en Guardar .
En el siguiente diálogo de consentimiento, se muestra lo que un usuario vería cuando hay una combinación de permisos de OAuth 2.0 y Google Drive en la solicitud. (Este diálogo genérico se generó con Google OAuth 2.0 Playground, por lo que no incluye la información de desarrollo de la marca que se establecería en API Console).
Accede al servicio
Google y terceros proporcionan bibliotecas que puedes usar para encargarte de muchos de los detalles de la implementación de la autenticación de usuarios y el acceso a las APIs de Google. Entre los ejemplos, se incluyen los Servicios de identidad de Google y las bibliotecas cliente de Google, que están disponibles para una variedad de plataformas.
Si decides no usar una biblioteca, sigue las instrucciones del resto de este documento, en el que se describen los flujos de solicitudes HTTP que subyacen a las bibliotecas disponibles.
Autenticación del usuario
La autenticación del usuario implica obtener un token de ID y validarlo. Los tokens de ID son una función estandarizada de OpenID Connect diseñada para usarse en el uso compartido de aserciones de identidad en Internet.
Los enfoques más utilizados para autenticar a un usuario y obtener un token de ID se llaman flujo “del servidor” y flujo “implícito”. El flujo de servidores permite que el servidor de backend de una aplicación verifique la identidad de la persona que usa un navegador o un dispositivo móvil. El flujo implícito se usa cuando una aplicación del cliente (por lo general, una app de JavaScript que se ejecuta en el navegador) necesita acceder a las APIs directamente en lugar de hacerlo a través de su servidor de backend.
En este documento, se describe cómo realizar el flujo del servidor para autenticar al usuario. El flujo implícito es mucho más complicado debido a los riesgos de seguridad que implica el manejo y el uso de tokens en el lado del cliente. Si necesitas implementar un flujo implícito, te recomendamos que uses Google Identity Services.
Flujo del servidor
Asegúrate de configurar tu app en API Console para que pueda usar estos protocolos y autentique a tus usuarios. Cuando un usuario intenta acceder con Google, debes hacer lo siguiente:
- Cómo crear un token de estado contra la falsificación
- Envía una solicitud de autenticación a Google
- Confirma el token de estado contra falsificaciones
- Intercambia
code
por un token de acceso y un token de ID - Obtén información del usuario a partir del token de ID
- Autentica al usuario
1. Crea un token de estado contra la falsificación
Debes proteger la seguridad de tus usuarios evitando los ataques de falsificación de solicitudes. El primer paso es crear un token de sesión único que mantenga el estado entre tu app y el cliente del usuario. Más adelante, debes hacer coincidir este token de sesión único con la respuesta de autenticación que muestra el servicio de acceso de OAuth de Google para verificar que el usuario realice la solicitud y no un atacante malicioso. Estos tokens suelen denominarse tokens de falsificación de solicitudes entre sitios (CSRF).
Una buena opción para un token de estado es una cadena de unos 30 caracteres creada con un generador de números aleatorios de alta calidad. Otro es un hash que se genera cuando se firman algunas de tus variables de estado de sesión con una clave que se mantiene en secreto en tu backend.
En el siguiente código, se muestra cómo generar tokens de sesión únicos.
PHP
Debes descargar la biblioteca cliente de las APIs de Google para PHP para usar esta muestra.
// Create a state token to prevent request forgery. // Store it in the session for later validation. $state = bin2hex(random_bytes(128/8)); $app['session']->set('state', $state); // Set the client ID, token state, and application name in the HTML while // serving it. return $app['twig']->render('index.html', array( 'CLIENT_ID' => CLIENT_ID, 'STATE' => $state, 'APPLICATION_NAME' => APPLICATION_NAME ));
Java
Para usar esta muestra, debes descargar la biblioteca cliente de las APIs de Google para Java.
// Create a state token to prevent request forgery. // Store it in the session for later validation. String state = new BigInteger(130, new SecureRandom()).toString(32); request.session().attribute("state", state); // Read index.html into memory, and set the client ID, // token state, and application name in the HTML before serving it. return new Scanner(new File("index.html"), "UTF-8") .useDelimiter("\\A").next() .replaceAll("[{]{2}\\s*CLIENT_ID\\s*[}]{2}", CLIENT_ID) .replaceAll("[{]{2}\\s*STATE\\s*[}]{2}", state) .replaceAll("[{]{2}\\s*APPLICATION_NAME\\s*[}]{2}", APPLICATION_NAME);
Python
Debes descargar la biblioteca cliente de las APIs de Google para Python para usar esta muestra.
# Create a state token to prevent request forgery. # Store it in the session for later validation. state = hashlib.sha256(os.urandom(1024)).hexdigest() session['state'] = state # Set the client ID, token state, and application name in the HTML while # serving it. response = make_response( render_template('index.html', CLIENT_ID=CLIENT_ID, STATE=state, APPLICATION_NAME=APPLICATION_NAME))
2. Envía una solicitud de autenticación a Google
El siguiente paso es crear una solicitud GET
HTTPS con los parámetros de URI adecuados.
Ten en cuenta que se usa HTTPS en lugar de HTTP en todos los pasos de este proceso. Se rechazan las conexiones HTTP. Debes recuperar el URI base del documento de descubrimiento con el valor de metadatos authorization_endpoint
. En el siguiente análisis, se supone que el URI base es https://accounts.google.com/o/oauth2/v2/auth
.
Para una solicitud básica, especifica los siguientes parámetros:
client_id
, que obtienes de API Console Credentials page.response_type
, que en una solicitud de flujo de código de autorización básica debe sercode
. (Obtén más información enresponse_type
).scope
, que en una solicitud básica debe seropenid email
. (Obtén más información enscope
).redirect_uri
debe ser el extremo HTTP de tu servidor que recibirá la respuesta de Google. El valor debe coincidir exactamente con uno de los URIs de redireccionamiento autorizados para el cliente de OAuth 2.0 que configuraste en API Console Credentials page. Si este valor no coincide con un URI autorizado, la solicitud fallará con un errorredirect_uri_mismatch
.state
debe incluir el valor del token de sesión único contra falsificaciones, así como cualquier otra información necesaria para recuperar el contexto cuando el usuario regresa a tu aplicación, p.ej., la URL de inicio. (Obtén más información enstate
).nonce
es un valor aleatorio que genera tu app y que habilita la protección contra la repetición cuando está presente.login_hint
puede ser la dirección de correo electrónico del usuario o la cadenasub
, que equivale al ID de Google del usuario. Si no proporcionas unlogin_hint
y el usuario accedió a su cuenta, la pantalla de consentimiento incluye una solicitud de aprobación para enviar la dirección de correo electrónico del usuario a tu app. (Obtén más información enlogin_hint
).- Usa el parámetro
hd
para optimizar el flujo de OpenID Connect para los usuarios de un dominio particular asociado con una organización de Google Workspace o Cloud (obtén más información enhd
).
Este es un ejemplo de un URI de autenticación de OpenID Connect completo, con saltos de línea y espacios para facilitar la lectura:
https://accounts.google.com/o/oauth2/v2/auth? response_type=code& client_id=424911365001.apps.googleusercontent.com& scope=openid%20email& redirect_uri=https%3A//oauth2.example.com/code& state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2-login-demo.example.com%2FmyHome& login_hint=jsmith@example.com& nonce=0394852-3190485-2490358& hd=example.com
Los usuarios deben dar su consentimiento si tu app solicita información nueva sobre ellos o si solicita acceso a una cuenta que no aprobaron anteriormente.
3. Confirma el token de estado contra falsificaciones
La respuesta se envía al redirect_uri
que especificaste en la solicitud. Todas las respuestas se muestran en la cadena de consulta, como se muestra a continuación:
https://oauth2.example.com/code?state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foa2cb.example.com%2FmyHome&code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7&scope=openid%20email%20https://www.googleapis.com/auth/userinfo.email
En el servidor, debes confirmar que el state
que recibiste de Google coincida con el token de sesión que creaste en el Paso 1. Esta verificación de ida y vuelta ayuda a garantizar que el usuario, y no una secuencia de comandos maliciosa, realice la solicitud.
En el siguiente código, se muestra cómo confirmar los tokens de sesión que creaste en el paso 1:
PHP
Debes descargar la biblioteca cliente de las APIs de Google para PHP para usar esta muestra.
// Ensure that there is no request forgery going on, and that the user // sending us this connect request is the user that was supposed to. if ($request->get('state') != ($app['session']->get('state'))) { return new Response('Invalid state parameter', 401); }
Java
Para usar esta muestra, debes descargar la biblioteca cliente de las APIs de Google para Java.
// Ensure that there is no request forgery going on, and that the user // sending us this connect request is the user that was supposed to. if (!request.queryParams("state").equals( request.session().attribute("state"))) { response.status(401); return GSON.toJson("Invalid state parameter."); }
Python
Debes descargar la biblioteca cliente de las APIs de Google para Python para usar esta muestra.
# Ensure that the request is not a forgery and that the user sending # this connect request is the expected user. if request.args.get('state', '') != session['state']: response = make_response(json.dumps('Invalid state parameter.'), 401) response.headers['Content-Type'] = 'application/json' return response
4. Intercambia code
por un token de acceso y un token de ID
La respuesta incluye un parámetro code
, un código de autorización único que tu servidor puede intercambiar por un token de acceso y un token de ID. Para realizar este intercambio, tu servidor envía una solicitud POST
HTTPS. La solicitud POST
se envía al extremo de token, que debes recuperar del documento de descubrimiento con el valor de metadatos token_endpoint
. En el siguiente análisis, se supone que el extremo es https://oauth2.googleapis.com/token
. La solicitud debe incluir los siguientes parámetros en el cuerpo de POST
:
Campos | |
---|---|
code |
El código de autorización que se muestra en la solicitud inicial |
client_id |
El ID de cliente que obtienes de API Console Credentials page, como se describe en Obtén credenciales de OAuth 2.0. |
client_secret |
El secreto del cliente que obtienes de API Console Credentials page, como se describe en Obtén credenciales de OAuth 2.0. |
redirect_uri |
Un URI de redireccionamiento autorizado para el client_id determinado que se especifica en el Credentials pagede API Console, como se describe en Establece un URI de redireccionamiento. |
grant_type |
Este campo debe contener un valor de authorization_code ,
como se define en la especificación de OAuth 2.0. |
La solicitud real podría verse como el siguiente ejemplo:
POST /token HTTP/1.1 Host: oauth2.googleapis.com Content-Type: application/x-www-form-urlencoded code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7& client_id=your-client-id& client_secret=your-client-secret& redirect_uri=https%3A//oauth2.example.com/code& grant_type=authorization_code
Una respuesta correcta a esta solicitud contiene los siguientes campos en un array JSON:
Campos | |
---|---|
access_token |
Es un token que se puede enviar a una API de Google. |
expires_in |
Es la vida útil restante del token de acceso en segundos. |
id_token |
Un JWT que contiene información de identidad sobre el usuario firmada digitalmente por Google |
scope |
Los permisos de acceso que otorga access_token expresados como una lista de cadenas separadas por espacios y que distinguen mayúsculas de minúsculas. |
token_type |
Identifica el tipo de token que se muestra. En este momento, este campo siempre tiene el valor Bearer .
|
refresh_token |
(opcional)
Este campo solo está presente si el parámetro |
5. Cómo obtener información del usuario a partir del token de ID
Un token de ID es un JWT (token web JSON), es decir, un objeto JSON firmado criptográficamente y codificado en base64. Por lo general, es fundamental que valides un token de ID antes de usarlo, pero como te comunicas directamente con Google a través de un canal HTTPS sin intermediarios y usas tu secreto de cliente para autenticarte en Google, puedes confiar en que el token que recibes realmente proviene de Google y es válido. Si tu servidor pasa el token de ID a otros componentes de tu app, es muy importante que los otros componentes validen el token antes de usarlo.
Dado que la mayoría de las bibliotecas de API combinan la validación con el trabajo de decodificar los valores codificados en base64url y analizar el JSON dentro, es probable que termines validando el token de todos modos a medida que accedes a los reclamos en el token de ID.
Carga útil de un token de ID
Un token de ID es un objeto JSON que contiene un conjunto de pares nombre-valor. Este es un ejemplo con formato para mejorar la legibilidad:
{ "iss": "https://accounts.google.com", "azp": "1234987819200.apps.googleusercontent.com", "aud": "1234987819200.apps.googleusercontent.com", "sub": "10769150350006150715113082367", "at_hash": "HK6E_P6Dh8Y93mRNtsDB1Q", "hd": "example.com", "email": "jsmith@example.com", "email_verified": "true", "iat": 1353601026, "exp": 1353604926, "nonce": "0394852-3190485-2490358" }
Los tokens de ID de Google pueden contener los siguientes campos (conocidos como declaraciones):
Reclamar | Proporcionado | Descripción |
---|---|---|
aud |
siempre | Es el público al que está destinado este token de ID. Debe ser uno de los IDs de cliente de OAuth 2.0 de tu aplicación. |
exp |
siempre | Es la hora de vencimiento a partir de la cual no se debe aceptar el token de ID. Se representa en el tiempo de Unix (segundos enteros). |
iat |
siempre | Es la hora en la que se emitió el token de ID. Se representa en tiempo Unix (segundos enteros). |
iss |
siempre | Es el identificador del emisor de la respuesta. Siempre usa https://accounts.google.com o accounts.google.com para los tokens de ID de Google. |
sub |
siempre | Es un identificador para el usuario, único entre todas las Cuentas de Google y que nunca se reutiliza. Una cuenta de Google puede tener varias direcciones de correo electrónico en diferentes momentos, pero el valor de sub nunca cambia. Usa sub dentro de tu aplicación
como la clave de identificador único del usuario. Tiene una longitud máxima de 255 caracteres ASCII
en mayúsculas y minúsculas. |
at_hash |
Hash del token de acceso Proporciona la validación de que el token de acceso está vinculado al token de identidad. Si el token de ID se emite con un valor access_token en el flujo del servidor, esta declaración siempre se incluye. Esta declaración se puede usar como un mecanismo alternativo para protegerse contra los ataques de falsificación de solicitudes entre sitios, pero si sigues el Paso 1 y el Paso 3, no es necesario verificar el token de acceso. |
|
azp |
El client_id del presentador autorizado Este reclamo solo es necesario cuando la parte que solicita el token de ID no es la misma que el público del token de ID. Este puede ser el caso de Google para apps híbridas en las que una aplicación web y una app para Android tienen un client_id de OAuth 2.0 diferente, pero comparten el mismo proyecto de APIs de Google. |
|
email |
La dirección de correo electrónico del usuario. Se proporciona solo si incluiste el permiso email en
tu solicitud. Es posible que el valor de esta declaración no sea único para esta cuenta y que cambie con el tiempo, por lo que no debes usar este valor como identificador principal para vincularlo a tu registro de usuario. Tampoco puedes usar el dominio del reclamo email para identificar a los usuarios de Google Workspace o de organizaciones de Cloud. En su lugar, usa el reclamo hd . |
|
email_verified |
Es verdadero si se verificó la dirección de correo electrónico del usuario; de lo contrario, es falso. | |
family_name |
Los apellidos del usuario. Se puede proporcionar cuando hay un reclamo de name . |
|
given_name |
Los nombres o nombres de pila del usuario. Se puede proporcionar cuando hay un reclamo de name . |
|
hd |
Es el dominio asociado con la organización de Google Workspace o Cloud del usuario. Se proporciona solo si el usuario pertenece a una organización de Google Cloud. Debes marcar esta declaración cuando restrinjas el acceso a un recurso solo a los miembros de ciertos dominios. La ausencia de esta declaración indica que la cuenta no pertenece a un dominio alojado por Google. | |
locale |
La configuración regional del usuario, representada por una etiqueta de idioma BCP 47
Se puede proporcionar cuando hay un reclamo name . |
|
name |
El nombre completo del usuario, en un formato visible. Se puede proporcionar en los siguientes casos:
Cuando hay reclamos |
|
nonce |
Es el valor de nonce que proporciona tu app en la solicitud de autenticación.
Debes aplicar la protección contra ataques de repetición asegurándote de que se presente solo
una vez. |
|
picture |
Es la URL de la foto de perfil del usuario. Se puede proporcionar en los siguientes casos:
Cuando hay reclamos |
|
profile |
La URL de la página de perfil del usuario. Se puede proporcionar en los siguientes casos:
Cuando hay reclamos |
6. Autentica al usuario
Después de obtener la información del usuario del token de ID, debes consultar la base de datos de usuarios de tu app. Si el usuario ya existe en tu base de datos, debes iniciar una sesión de la aplicación para ese usuario si la respuesta de la API de Google cumple con todos los requisitos de acceso.
Si el usuario no existe en tu base de datos de usuarios, debes redireccionarlo a tu flujo de registro de usuarios nuevos. Es posible que puedas registrar automáticamente al usuario según la información que recibas de Google o, al menos, que puedas propagar previamente muchos de los campos que requieres en tu formulario de registro. Además de la información del token de ID, puedes obtener información adicional del perfil de usuario en nuestros extremos de perfil de usuario.
Temas avanzados
En las siguientes secciones, se describe la API de Google OAuth 2.0 con mayor detalle. Esta información está dirigida a desarrolladores con requisitos avanzados de autenticación y autorización.
Acceso a otras APIs de Google
Una de las ventajas de usar OAuth 2.0 para la autenticación es que tu aplicación puede obtener permiso para usar otras APIs de Google en nombre del usuario (como YouTube, Google Drive, Calendario o Contactos) al mismo tiempo que lo autenticas. Para ello, incluye los demás permisos que necesites en la solicitud de autenticación que envíes a Google. Por ejemplo, para agregar el grupo etario del usuario a tu solicitud de autenticación, pasa un parámetro de alcance de openid email https://www.googleapis.com/auth/profile.agerange.read
. Se le solicita al usuario de forma adecuada en la pantalla de consentimiento. El token de acceso que recibes de Google te permite acceder a todas las APIs relacionadas con los permisos de acceso que solicitaste y que se te otorgaron.
Tokens de actualización
En tu solicitud de acceso a la API, puedes solicitar que se devuelva un token de actualización durante el intercambio de code
. Un token de actualización le proporciona a tu app acceso continuo a las APIs de Google mientras el usuario no está presente en tu aplicación. Para solicitar un token de actualización, agrega el parámetro access_type
a offline
en tu solicitud de autenticación.
Consideraciones:
- Asegúrate de almacenar el token de actualización de forma segura y permanente, ya que solo puedes obtener un token de actualización la primera vez que realizas el flujo de intercambio de códigos.
- Existen límites en la cantidad de tokens de actualización que se emiten: un límite por combinación de cliente/usuario y otro por usuario en todos los clientes. Si tu aplicación solicita demasiados tokens de actualización, es posible que se encuentre con estos límites, en cuyo caso los tokens de actualización más antiguos dejarán de funcionar.
Para obtener más información, consulta Actualiza un token de acceso (acceso sin conexión).
Solicitud de nuevo consentimiento
Para solicitarle al usuario que vuelva a autorizar tu app, configura el parámetro prompt
en consent
en tu solicitud de autenticación. Cuando se incluye prompt=consent
, la pantalla de consentimiento se muestra cada vez que tu app solicita la autorización de los permisos de acceso, incluso si todos los permisos se otorgaron anteriormente a tu proyecto de APIs de Google. Por este motivo, incluye prompt=consent
solo cuando sea necesario.
Para obtener más información sobre el parámetro prompt
, consulta prompt
en la tabla Parámetros de URI de autenticación.
Parámetros de URI de autenticación
En la siguiente tabla, se proporcionan descripciones más completas de los parámetros que acepta la API de autenticación de OAuth 2.0 de Google.
Parámetro | Obligatorio | Descripción |
---|---|---|
client_id |
(Obligatorio) | La cadena de ID de cliente que obtienes de API Console Credentials page, como se describe en Obtén credenciales de OAuth 2.0 |
nonce |
(Obligatorio) | Es un valor aleatorio que genera tu app y que habilita la protección contra la repetición. |
response_type |
(Obligatorio) | Si el valor es code , se inicia un flujo de código de autorización básico, que requiere un POST al extremo de token para obtener los tokens. Si el valor es token id_token o id_token token , se inicia un flujo implícito, que requiere el uso de JavaScript en el URI de redireccionamiento para recuperar tokens del identificador #fragment del URI. |
redirect_uri |
(Obligatorio) | Determina a dónde se envía la respuesta. El valor de este parámetro debe coincidir exactamente con uno de los valores de redireccionamiento autorizados que estableciste en el API Console Credentials page (incluidos el esquema HTTP o HTTPS, la mayúscula y la barra final "/", si corresponde). |
scope |
(Obligatorio) | El parámetro de alcance debe comenzar con el valor Si el valor de alcance Si el valor del permiso Además de estos permisos específicos de OpenID, tu argumento de permiso también puede incluir otros valores de permiso. Todos los valores de alcance deben estar separados por espacios. Por ejemplo, si deseas
acceder a Google Drive de un usuario por archivo, tu parámetro de alcance podría ser
Para obtener información sobre los permisos disponibles, consulta Alcances de OAuth 2.0 para las APIs de Google o la documentación de la API de Google que deseas usar. |
state |
(Opcional, pero muy recomendable) | Es una cadena opaca que se realiza en el protocolo, es decir, se muestra como un parámetro de URI en el flujo básico y en el identificador
|
access_type |
(Opcional) | Los valores permitidos son offline y online . El efecto se documenta en Acceso sin conexión. Si se solicita un token de acceso, el cliente no recibe un token de actualización, a menos que se especifique un valor de offline . |
display |
(Opcional) | Es un valor de cadena ASCII para especificar cómo el servidor de autorización muestra las páginas de la interfaz de usuario de autenticación y consentimiento. Los servidores de Google especifican y aceptan los siguientes valores, pero no tienen ningún efecto en su comportamiento: page , popup , touch y wap . |
hd |
(Opcional) | Agiliza el proceso de acceso de las cuentas que pertenecen a una organización de Google Cloud. Si
incluyes el dominio de la organización de Google Cloud (por ejemplo, mycollege.edu),
puedes indicar que la IU de selección de cuentas debe optimizarse para las cuentas de ese
dominio. Para realizar optimizaciones para las cuentas de organización de Google Cloud en general, en lugar de solo un
dominio de organización de Google Cloud, establece un valor de asterisco ( No dependas de esta optimización de la IU para controlar quién puede acceder a tu app, ya que se pueden modificar las solicitudes del cliente. Asegúrate de validar que el token de ID que se muestra tenga un valor de reclamo |
include_granted_scopes |
(Opcional) | Si se proporciona este parámetro con el valor true y se otorga la solicitud de autorización, la autorización incluirá cualquier autorización anterior otorgada a esta combinación de usuario o aplicación para otros alcances. Consulta Autorización incremental.
Ten en cuenta que no puedes realizar autorizaciones incrementales con el flujo de apps instaladas. |
login_hint |
(Opcional) | Cuando tu app sabe qué usuario intenta autenticar, puede proporcionar este parámetro como una sugerencia al servidor de autenticación. Si pasas esta sugerencia, se suprime el selector de cuenta y se completa previamente el cuadro de correo electrónico en el formulario de acceso o se selecciona la sesión correcta (si el usuario usa accesos múltiples), lo que puede ayudarte a evitar problemas que se producen si tu app accede a la cuenta de usuario incorrecta.
El valor puede ser una dirección de correo electrónico o la cadena sub , que equivale al ID de Google del usuario. |
prompt |
(Opcional) | Es una lista de valores de cadena delimitados por espacios que especifica si el servidor de autorización le solicita al usuario que vuelva a autenticarse y que otorgue su consentimiento. Los valores posibles son los siguientes:
Si no se especifica ningún valor y el usuario no autorizó el acceso anteriormente, se le mostrará una pantalla de consentimiento. |
Valida un token de ID
Debes validar todos los tokens de ID en tu servidor, a menos que sepas que provienen directamente de Google. Por ejemplo, tu servidor debe verificar como auténticos los tokens de ID que recibe de tus apps cliente.
Las siguientes son situaciones comunes en las que podrías enviar tokens de ID a tu servidor:
- Envía tokens de ID con solicitudes que deben autenticarse. Los tokens de ID te indican el usuario en particular que realiza la solicitud y para qué cliente se otorgó ese token de ID.
Los tokens de ID son sensibles y se pueden usar de forma inadecuada si se interceptan. Debes asegurarte de que estos tokens se manejen de forma segura transmitiéndolos solo a través de HTTPS y solo a través de datos POST o dentro de los encabezados de solicitud. Si almacenas tokens de ID en tu servidor, también debes almacenarlos de forma segura.
Una de las características que hacen que los tokens de ID sean útiles es que puedes pasarlos a diferentes componentes de tu app. Estos componentes pueden usar un token de ID como un mecanismo de autenticación ligero que autentica la app y el usuario. Sin embargo, antes de poder usar la información del token de ID o confiar en ella como una afirmación de que el usuario se autenticó, debes validarla.
La validación de un token de ID requiere varios pasos:
- Verifica que el emisor haya firmado correctamente el token de ID. Los tokens emitidos por Google se firman con uno de los certificados que se encuentran en el URI especificado en el valor de metadatos
jwks_uri
del documento de descubrimiento. - Verifica que el valor de la declaración
iss
en el token de ID sea igual ahttps://accounts.google.com
oaccounts.google.com
. - Verifica que el valor de la declaración
aud
en el token de ID sea igual al ID de cliente de tu app. - Verifica que no haya pasado la hora de vencimiento (reclamación
exp
) del token de ID. - Si especificaste un valor de parámetro hd en la solicitud, verifica que el token de ID tenga una declaración
hd
que coincida con un dominio aceptado asociado con una organización de Google Cloud.
Los pasos del 2 al 5 solo involucran comparaciones de cadenas y fechas que son bastante sencillas, por lo que no las detallaremos aquí.
El primer paso es más complejo y abarca la verificación de la firma criptográfica. Para la depuración, puedes usar el extremo tokeninfo
de Google para compararlo con el procesamiento local implementado en tu servidor o dispositivo. Supongamos que el valor de tu token de ID es XYZ123
. Luego, desreferenciarías el URI https://oauth2.googleapis.com/tokeninfo?id_token=XYZ123
. Si la firma del token es válida, la respuesta será la carga útil de JWT en su forma de objeto JSON decodificado.
El extremo tokeninfo
es útil para depurar, pero para fines de producción, recupera las claves públicas de Google desde el extremo de claves y realiza la validación de forma local. Debes recuperar el URI de las claves del documento de descubrimiento con el valor de metadatos jwks_uri
. Es posible que las solicitudes al extremo de depuración se limiten o estén sujetas a errores intermitentes.
Dado que Google cambia sus claves públicas con poca frecuencia, puedes almacenarlas en caché con las directivas de caché de la respuesta HTTP y, en la gran mayoría de los casos, realizar la validación local de manera mucho más eficiente que con el extremo tokeninfo
. Esta validación requiere recuperar y analizar certificados, y realizar las llamadas criptográficamente correctas para verificar la firma. Afortunadamente, hay bibliotecas bien depuradas disponibles en una amplia variedad de lenguajes para lograr esto (consulta jwt.io).
Cómo obtener información del perfil del usuario
Para obtener información adicional del perfil del usuario, puedes usar el token de acceso (que tu aplicación recibe durante el flujo de autenticación) y el estándar OpenID Connect:
Para cumplir con OpenID, debes incluir los valores de alcance de
openid profile
en tu solicitud de autenticación.Si deseas que se incluya la dirección de correo electrónico del usuario, puedes especificar un valor de alcance adicional de
email
. Para especificarprofile
yemail
, puedes incluir el siguiente parámetro en el URI de tu solicitud de autenticación:scope=openid%20profile%20email
- Agrega tu token de acceso al encabezado de autorización y realiza una solicitud
GET
HTTPS al extremo userinfo, que debes recuperar del documento de descubrimiento con el valor de metadatosuserinfo_endpoint
. La respuesta de userinfo incluye información sobre el usuario, como se describe enOpenID Connect Standard Claims
y el valor de metadatosclaims_supported
del documento de descubrimiento. Los usuarios o sus organizaciones pueden optar por proporcionar o retener ciertos campos, por lo que es posible que no obtengas información para todos los campos de tus permisos de acceso autorizados.
El documento de descubrimiento
El protocolo OpenID Connect requiere el uso de varios extremos para autenticar a los usuarios y solicitar recursos, incluidos tokens, información del usuario y claves públicas.
Para simplificar las implementaciones y aumentar la flexibilidad, OpenID Connect permite el uso de un “documento de descubrimiento”, un documento JSON que se encuentra en una ubicación conocida y contiene pares clave-valor que proporcionan detalles sobre la configuración del proveedor de OpenID Connect, incluidos los URIs de los extremos de autorización, token, revocación, información del usuario y claves públicas. El documento de descubrimiento del servicio de OpenID Connect de Google se puede recuperar desde los siguientes lugares:
https://accounts.google.com/.well-known/openid-configuration
Para usar los servicios de OpenID Connect de Google, debes codificar de forma fija el URI del documento de descubrimiento (https://accounts.google.com/.well-known/openid-configuration
) en tu aplicación.
Tu aplicación recupera el documento, aplica reglas de almacenamiento en caché en la respuesta y, luego, recupera los URIs de extremo según sea necesario. Por ejemplo, para autenticar a un usuario, tu código recuperaría el valor de metadatos authorization_endpoint
(https://accounts.google.com/o/oauth2/v2/auth
en el siguiente ejemplo) como el URI base para las solicitudes de autenticación que se envían a Google.
Este es un ejemplo de un documento de este tipo. Los nombres de los campos son los especificados en OpenID Connect Discovery 1.0 (consulta ese documento para conocer sus significados). Los valores son solo ilustrativos y pueden cambiar, aunque se copiaron de una versión reciente del documento de Google Discovery:
{ "issuer": "https://accounts.google.com", "authorization_endpoint": "https://accounts.google.com/o/oauth2/v2/auth", "device_authorization_endpoint": "https://oauth2.googleapis.com/device/code", "token_endpoint": "https://oauth2.googleapis.com/token", "userinfo_endpoint": "https://openidconnect.googleapis.com/v1/userinfo", "revocation_endpoint": "https://oauth2.googleapis.com/revoke", "jwks_uri": "https://www.googleapis.com/oauth2/v3/certs", "response_types_supported": [ "code", "token", "id_token", "code token", "code id_token", "token id_token", "code token id_token", "none" ], "subject_types_supported": [ "public" ], "id_token_signing_alg_values_supported": [ "RS256" ], "scopes_supported": [ "openid", "email", "profile" ], "token_endpoint_auth_methods_supported": [ "client_secret_post", "client_secret_basic" ], "claims_supported": [ "aud", "email", "email_verified", "exp", "family_name", "given_name", "iat", "iss", "locale", "name", "picture", "sub" ], "code_challenge_methods_supported": [ "plain", "S256" ] }
Es posible que puedas evitar un recorrido de ida y vuelta de HTTP si almacenas en caché los valores del documento de descubrimiento. Se usan encabezados de almacenamiento en caché HTTP estándar y se deben respetar.
Bibliotecas cliente
Las siguientes bibliotecas cliente facilitan la implementación de OAuth 2.0 mediante la integración con frameworks populares:
- Biblioteca cliente de las APIs de Google para Java
- Biblioteca cliente de las APIs de Google para Python
- Biblioteca cliente de las APIs de Google para .NET
- Biblioteca cliente de las APIs de Google para Ruby
- Biblioteca cliente de las APIs de Google para PHP
- Biblioteca de OAuth 2.0 para Google Web Toolkit
- Controladores de OAuth 2.0 de Google Toolbox for Mac
Cumplimiento de OpenID Connect
El sistema de autenticación de OAuth 2.0 de Google admite las funciones requeridas de la especificación OpenID Connect Core. Cualquier cliente diseñado para funcionar con OpenID Connect debería interoperar con este servicio (con la excepción del objeto de solicitud de OpenID).