Las API de OAuth 2.0 de Google se pueden usar para la autenticación y autorización. En este documento, se describe nuestra implementación de OAuth 2.0 para la autenticación, que cumple con la especificación 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 API de Google también se aplica a este servicio. Si deseas explorar este protocolo de forma interactiva, te recomendamos que uses Google OAuth 2.0 Playground. Para obtener ayuda sobre Stack Overflow, etiqueta tus preguntas con 'google-oauth'
Configuración de OAuth 2.0
Antes de que tu aplicación pueda usar el sistema de autenticación OAuth 2.0 de Google para el acceso de los usuarios, debes configurar un proyecto en Google API Console a fin de obtener credenciales de OAuth 2.0, establecer un URI de redireccionamiento y personalizar (opcionalmente) la información de desarrollo de la marca que tus usuarios verán en la pantalla de consentimiento del usuario. También puedes usar el API Console para crear una cuenta de servicio, habilitar la facturación, configurar el filtrado y realizar otras tareas. Para obtener más información, consulta la ayuda deGoogle API Console.
Obtén credenciales de OAuth 2.0
Necesitas credenciales de OAuth 2.0, incluidos un ID y un secreto de cliente, para autenticar a los usuarios y obtener acceso a las API 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 estableces en API Console determina dónde Google envía las respuestas a tus solicitudes de autenticación.
Para crear, ver o editar los URI de redireccionamiento para una credencial de OAuth 2.0 dada, haga lo siguiente:
- Go to the Credentials page.
- En la sección de ID de cliente OAuth 2.0 de la página, haga clic en una credencial.
- Ver o editar los URI de redireccionamiento.
Si no hay una sección de ID de cliente OAuth 2.0 en la página Credenciales, entonces su proyecto no tiene credenciales OAuth. Para crear uno, haga clic en Crear credenciales .
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 lanza el usuario y las condiciones que se aplican. Por ejemplo, cuando el usuario acceda, es posible que se le pida que otorgue a tu app acceso a su dirección de correo electrónico y a la información básica de la cuenta. Puedes solicitar acceso a esta información con el parámetro scope
, que la app incluye en su solicitud de autenticación. También puedes usar permisos para solicitar acceso a otras API de Google.
La pantalla de consentimiento del usuario también presenta información de desarrollo de la marca, como el nombre del producto, el logotipo y la URL de la página principal. Tú controlas la información de marca en el 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 cuadro de diálogo de consentimiento, se muestra lo que vería un usuario cuando en la solicitud hubiera una combinación de permisos de OAuth 2.0 y Google Drive. (Este diálogo genérico se generaba mediante Google OAuth 2.0 Playground, por lo que no incluye información de desarrollo de la marca que se establecería en API Console).

Accede al servicio
Google y los terceros proporcionan bibliotecas que puedes usar para encargarte de muchos de los detalles de implementación de la autenticación de usuarios y la obtención de acceso a las API de Google. Entre los ejemplos, se incluyen el Acceso con 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 que se incluyen en el resto de este documento, en el que se describen los flujos de solicitudes HTTP que dependen de 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 usados para autenticar a un usuario y obtener un token de ID se denominan flujo de servidor y de flujo implícito. El flujo del servidor permite al servidor de backend de una aplicación verificar 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 API directamente en lugar de hacerlo mediante 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 relacionados con la administración y el uso de tokens en el cliente. Si necesitas implementar un flujo implícito, te recomendamos que uses el Acceso con Google.
Flujo del servidor
Asegúrate de configurar tu app en el API Console para habilitarla a fin de usar estos protocolos y autenticar a tus usuarios. Cuando un usuario intenta acceder con Google, tienes que hacer lo siguiente:
- Cómo crear un token de estado antifalsificación
- Envía una solicitud de autenticación a Google
- Confirme el token de estado antifalsificación
- Intercambio
code
por token de acceso e ID de acceso - Obtén información del usuario a partir del token de ID
- Autentica al usuario
1. Crea un token de estado antifalsificación
Para proteger la seguridad de sus usuarios, debe evitar 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. Más adelante, harás coincidir este token de sesión único con la respuesta de autenticación que muestra el servicio de acceso de Google OAuth para verificar que el usuario esté realizando la solicitud y no un atacante malicioso. A menudo, estos tokens se conocen como tokens de falsificación de solicitudes entre sitios (CSRF).
Una buena opción para un token de estado es una string de aproximadamente 30 caracteres construida con un generador de números al azar de alta calidad. Otro es un hash que se genera mediante la firma de algunas de las variables de estado de la sesión con una clave que se mantiene en el backend.
En el siguiente código, se muestra cómo generar tokens de sesión únicos.
PHP
Si deseas usar esta muestra, debes descargar la biblioteca cliente de las API de Google para PHP.
// 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
Si deseas usar esta muestra, debes descargar la biblioteca cliente de las API 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
Si deseas usar esta muestra, debes descargar la biblioteca cliente de las API de Google para Python.
# 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 formar una solicitud GET
HTTPS con los parámetros de URI correspondientes.
Ten en cuenta el uso de 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 la siguiente discusión, 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 se obtiene de API ConsoleCredentials pageresponse_type
, que en una solicitud básica de flujo de código de autorización debe sercode
. (Obtén más información enresponse_type
).scope
, que en una solicitud básica debe seropenid email
(Obtenga más información enscope
).redirect_uri
debe ser el extremo HTTP en tu servidor que recibirá la respuesta de Google. El valor debe coincidir exactamente con uno de los URI de redireccionamiento autorizados para el cliente de OAuth 2.0, que configuraste en API ConsoleCredentials page. Si este valor no coincide con un URI autorizado, la solicitud fallará y se mostrará un errorredirect_uri_mismatch
.state
debe incluir el valor del token de sesión único antifalsificación, así como cualquier otra información necesaria para recuperar el contexto cuando el usuario vuelve a tu aplicación, p.ej., la URL de inicio. (Obtenga más información enstate
).nonce
es un valor aleatorio generado por tu app que habilita la protección de repetición cuando está presente.login_hint
puede ser la dirección de correo electrónico del usuario o la stringsub
, que equivale al ID de Google del usuario. Si no proporcionas unlogin_hint
y el usuario ya accedió, la pantalla de consentimiento incluirá una solicitud de aprobación para liberar la dirección de correo electrónico del usuario en la 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 Cloud. (Obtén más información enhd
).
A continuación, se muestra 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 otorgar su consentimiento si tu app solicita información nueva sobre ellos o si tu app solicita acceso a la cuenta y no lo aprobaron anteriormente.
3. Confirmar token de estado antifalsificación
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
recibido 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, no una secuencia de comandos malintencionada, 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
Si deseas usar esta muestra, debes descargar la biblioteca cliente de las API de Google para PHP.
// 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
Si deseas usar esta muestra, debes descargar la biblioteca cliente de las API 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
Si deseas usar esta muestra, debes descargar la biblioteca cliente de las API de Google para Python.
# 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. Intercambio code
para el token de acceso y el token de ID
La respuesta incluye un parámetro code
, un código de autorización única que tu servidor puede intercambiar por un token de acceso y un token de ID. Tu servidor realiza este intercambio mediante el envío de una solicitud POST
HTTPS. La solicitud POST
se envía al extremo del token,
que debes recuperar del documento de descubrimiento mediante el
valor de metadatos token_endpoint
. En la siguiente discusión, se da por sentado 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 desde la solicitud inicial |
client_id |
El ID de cliente que obtienes de Credentials pagede la API Console, como se describe en Obtén credenciales de OAuth 2.0 |
client_secret |
El secreto de cliente que obtienes de API ConsoleCredentials page, como se describe en Obtén credenciales de OAuth 2.0 |
redirect_uri |
Un URI de redireccionamiento autorizado para el client_id especificado en el Credentials pagede API Console, como se describe en Cómo configurar un URI de redireccionamiento. |
grant_type |
Este campo debe contener un valor de authorization_code ,
según se define en la especificación de OAuth 2.0. |
La solicitud real puede ser similar al 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 |
Un token que se puede enviar a una API de Google. |
expires_in |
El ciclo de vida restante del token de acceso en segundos. |
id_token |
Un JWT que contiene información de identidad del usuario con la firma digital de Google |
scope |
Los permisos de acceso otorgados por access_token , expresados como una lista de strings delimitadas por espacios y 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. Obtén 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 codificado en Base64 con firma criptográfica. 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 el secreto de tu cliente para autenticarte en Google, puedes estar seguro de que el token que recibes realmente proviene de Google y es válido. Si el servidor pasa el token de ID a otros componentes de la app, es de suma importancia 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 decodificación de los valores codificados en base64url y el análisis del JSON dentro de ella, es probable que termines de validar el token de todas formas a medida que accedas a las reclamaciones en el token de ID.
Carga útil de token de ID
Un token de ID es un objeto JSON que contiene un conjunto de pares nombre/valor. A continuación, se muestra un ejemplo con formato:
{ "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 reclamos):
Claim | Proporcionada | Descripción |
---|---|---|
aud |
always | El público al que está destinado este token de ID. Debe ser uno de los ID de cliente de OAuth 2.0 de tu aplicación. |
exp |
always | Hora de vencimiento a partir del cual no se debe aceptar el token de ID. Se representa en tiempo Unix (segundos enteros). |
iat |
always | La hora a la que se emitió el token de ID. Representado en tiempo Unix (segundos enteros). |
iss |
always | Es el identificador de la entidad emisora de la respuesta. Siempre se debe utilizar https://accounts.google.com o accounts.google.com para los tokens de ID de Google. |
sub |
always | Es un identificador para el usuario, único entre todas las Cuentas de Google y nunca se reutiliza. Una Cuenta de Google puede tener varias direcciones de correo electrónico en diferentes momentos, pero el valor sub nunca cambia. Usa sub en tu aplicación como la clave de identificador único del usuario. Longitud máxima de 255 caracteres ASCII que distinguen entre mayúsculas y minúsculas. |
at_hash |
Hash del token de acceso Proporciona 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 reclamación siempre se incluye. Esta reclamación se puede usar como mecanismo alternativo para brindar protección contra ataques de falsificación de solicitudes entre sitios, pero si sigues los pasos 1 y 3, no es necesario verificar el token de acceso. |
|
azp |
El client_id del presentador autorizado. Esta reclamación solo es necesaria cuando la parte que solicita el token de ID no es la misma que su público. Este podría ser el caso en Google en el caso de las 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 que comparten el mismo proyecto de las API de Google. |
|
email |
La dirección de correo electrónico del usuario. Es posible que este valor no sea exclusivo de este usuario y no sea adecuado para usarse como clave primaria. Se proporciona solo si el alcance incluye el valor de alcance email . |
|
email_verified |
Se asigna el valor true si se verificó la dirección de correo electrónico del usuario. De lo contrario, se asigna el valor false. | |
family_name |
Apellido(s) o apellido(s) del usuario Se puede proporcionar cuando hay un reclamo de name presente. |
|
given_name |
Nombre o nombres del usuario. Se puede proporcionar cuando hay un reclamo de name presente. |
|
hd |
Es el dominio asociado con la organización del usuario en Google Cloud. Se proporciona solo si el usuario pertenece a una organización de Google Cloud. | |
locale |
Indica la configuración regional del usuario, representada por una etiqueta de idioma BCP 47.
Se puede proporcionar cuando hay una reclamación de name presente. |
|
name |
El nombre completo del usuario, en formato visible Se puede proporcionar en los siguientes casos:
Cuando hay reclamaciones |
|
nonce |
El valor de nonce que proporciona tu app en la solicitud de autenticación.
Debes aplicar la protección contra los ataques de repetición garantizando que se presente solo una vez. |
|
picture |
URL de la foto de perfil del usuario. Se puede proporcionar en los siguientes casos:
Cuando hay reclamaciones |
|
profile |
La URL de la página de perfil del usuario. Se puede proporcionar en los siguientes casos:
Cuando hay reclamaciones |
6. Autentica al usuario
Después de obtener información del usuario a partir 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 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 al flujo de registro de usuarios nuevos. Es posible que puedas registrar automáticamente al usuario en función de la información que recibes de Google o, al menos, puedes prepropagar muchos de los campos que necesitas en tu formulario de registro. Además de la información en el token de ID, puedes obtener información de perfil de usuario adicional en nuestros extremos de perfil de usuario.
Temas avanzados
En las siguientes secciones, se describe la API de Google OAuth 2.0 con más detalle. Esta información está dirigida a desarrolladores con requisitos avanzados relacionados con la autenticación y autorización.
Acceso a otras API 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 API de Google en nombre del usuario (como YouTube, Google Drive, Calendario o Contactos) al mismo tiempo que autenticas al usuario. Para ello, incluye los otros permisos que necesitas en la solicitud de autenticación que envías a Google. Por ejemplo, para agregar el grupo etario de un usuario a tu solicitud de autenticación, pasa un parámetro de permiso de openid email https://www.googleapis.com/auth/profile.agerange.read
. Se solicita al usuario que aparezca de manera apropiada en la pantalla de consentimiento. El token de acceso que recibes de Google te permite acceder a todas las API relacionadas con los permisos de acceso que solicitaste y que se otorgaron.
Tokens de actualización
En tu solicitud de acceso a la API, puedes solicitar que se muestre un token de actualización durante el intercambio code
. Un token de actualización le proporciona a tu app acceso continuo a las API de Google cuando el usuario no está presente en la aplicación. Para solicitar un token de actualización, agrega el parámetro access_type
como 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 podrás obtener un token de actualización la primera vez que realices el flujo de intercambio de código.
- Existen límites en la cantidad de tokens de actualización que se emiten: un límite por combinación cliente/usuario y otro por usuario para todos los clientes. Si tu aplicación solicita demasiados tokens de actualización, es posible que se alcance a estos límites, en cuyo caso los tokens de actualización anteriores dejarán de funcionar.
Para obtener más información, consulta Cómo actualizar un token de acceso (acceso sin conexión).
Solicitar nuevamente consentimiento
Puedes pedirle al usuario que vuelva a autorizar tu app si configuras el parámetro prompt
como consent
en tu solicitud de autenticación. Si se incluye prompt=consent
, se mostrará la pantalla de consentimiento cada vez que tu app solicite autorización de permisos de acceso, incluso si antes todos los permisos se otorgaron a tu proyecto de las API 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 string de ID de cliente que obtienes de Credentials pagede API Console, como se describe en Obtén credenciales de OAuth 2.0 |
nonce |
(Obligatorio) | Es un valor aleatorio generado por tu app que habilita la protección de repetición. |
response_type |
(Obligatorio) | Si el valor es code , inicia un flujo de código de autorización básico, que requiere una POST al extremo del token para obtener los tokens. Si el valor es token id_token o id_token token , inicia un flujo implícito que requiere el uso de JavaScript en el URI de redireccionamiento para recuperar tokens del identificador #fragment de 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 la Credentials page de API Console(incluidos el esquema HTTP o HTTPS, el caso y el final [/#39;, si corresponde). |
scope |
(Obligatorio) | El parámetro de alcance debe comenzar con el valor Si el valor del alcance Si el valor del alcance Además de estos permisos específicos de OpenID, tu argumento de alcance también puede incluir otros valores de alcance. Todos los valores de alcance deben estar separados por espacios. Por ejemplo, si quieres acceso a Google Drive de un usuario por archivo, el parámetro de alcance podría ser Para obtener información sobre los alcances disponibles, consulta los permisos de OAuth 2.0 para las API de Google o la documentación de la API de Google que deseas usar. |
state |
(Opcional, pero muy recomendable) | Una string opaca ida y vuelta 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) | Un valor de string ASCII para especificar cómo el servidor de autorización muestra las páginas de interfaz de usuario de autenticación y consentimiento. Los servidores de Google especifican y aceptan los siguientes valores, pero no afectan su comportamiento: page , popup , touch y wap . |
hd |
(Opcional) | Optimiza el proceso de acceso para 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 cuenta debe optimizarse para las cuentas de ese dominio. A fin de realizar optimizaciones para cuentas de organización de Google Cloud en general en lugar de solo un dominio de organización de Google Cloud, configura 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 reclamación |
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 y aplicación para otros permisos. Consulta Autorización incremental.
Ten en cuenta que no puedes realizar una autorización incremental con el flujo de apps instaladas. |
login_hint |
(Opcional) | Cuando la app sabe qué usuario está intentando autenticar, puede proporcionar este parámetro como una sugerencia al servidor de autenticación. Al pasar esta sugerencia, se suprime el selector de cuentas y se completa previamente el cuadro de correo electrónico en el formulario de acceso o se selecciona la sesión adecuada (si el usuario usa el acceso múltiple), que puede ayudarte a evitar problemas que ocurren si tu app accede a la cuenta de usuario incorrecta.
El valor puede ser una dirección de correo electrónico o la string sub , que equivale al ID de Google del usuario. |
prompt |
(Opcional) | Una lista de valores de string delimitado por espacios que especifica si el servidor de autorización solicita al usuario la reautenticación y el consentimiento. Los posibles valores son los siguientes:
Si no se especifica ningún valor y el usuario no tiene autorización previa, se 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 tokens de ID que reciba de tus apps cliente.
Las siguientes son situaciones comunes en las que puedes enviar tokens de ID a tu servidor:
- Enviando tokens de ID con solicitudes que se deben autenticar. Los tokens de ID te indican cuál es el usuario específico 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 mediante la transmisión solo a través de HTTPS y solo a través de datos de POST o encabezados de solicitud. Si almacena tokens de ID en su servidor, también debe almacenarlos de forma segura.
Algo que hace que los tokens de ID sea útil es que puedes pasarlos por diferentes componentes de tu app. Estos componentes pueden usar un token de ID como un mecanismo de autenticación liviano que autentica la app y el usuario. Sin embargo, antes de que puedas usar la información del token de ID o confiar en él como una aserción de que el usuario se autenticó, debes validarlo.
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 encontrados en el URI especificado en el valor de metadatos
jwks_uri
del documento de descubrimiento. - Verifica que el valor de la reclamación
iss
en el token de ID sea igual ahttps://accounts.google.com
oaccounts.google.com
. - Verifica que el valor de la reclamación
aud
en el token de ID sea igual al ID de cliente de tu app. - Verifica que no haya transcurrido el tiempo 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 reclamación
hd
que coincida con un dominio aceptado asociado a una organización de Google Cloud.
Los pasos 2 al 5 implican solo comparaciones de strings y fechas que son bastante sencillas, por lo que no las mostraremos aquí.
El primer paso es más complejo y requiere la verificación de las firmas criptográficas. Para fines de depuración, puedes usar el extremo tokeninfo
de Google para realizar una comparación con el procesamiento local implementado en tu servidor o dispositivo. Supongamos que el valor de tu token de ID es XYZ123
. Luego, debes hacer referencia al URI https://oauth2.googleapis.com/tokeninfo?id_token=XYZ123
. Si la firma del token es válida, la respuesta sería la carga útil de JWT en su formulario de objeto JSON decodificado.
El extremo tokeninfo
es útil para la depuración, pero para fines de producción, recuperar claves públicas de Google del extremo de claves y realizar la validación de manera local. Debes recuperar el URI de claves del documento de descubrimiento
mediante el valor de metadatos jwks_uri
. Las solicitudes al extremo de depuración pueden limitarse o estar 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 con mucha más eficiencia que con el extremo tokeninfo
. Esta validación requiere recuperar y analizar certificados, y realizar las llamadas criptográficas adecuadas para verificar la firma. Por fortuna, hay bibliotecas bien depuradas disponibles en una gran variedad de lenguajes para lograr esto (consulta jwt.io).
Cómo obtener información del perfil del usuario
Para obtener información de perfil adicional sobre el 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 que cumpla con OpenID, debes incluir los valores de alcance
openid profile
en tu solicitud de autenticación.Si quieres 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 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 de información del usuario, que debes recuperar del documento de descubrimiento mediante el valor de metadatosuserinfo_endpoint
. La respuesta de información del usuario 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 sobre todos los campos de tus permisos de acceso autorizados.
El documento de descubrimiento
El protocolo de OpenID Connect requiere el uso de varios extremos para autenticar 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 de un archivo JSON en una ubicación conocida que contenga pares clave-valor que proporcionen detalles sobre la configuración del proveedor de OpenID Connect, incluidos los URI de los extremos de autorización, token, revocación, información del usuario y claves públicas. El documento de descubrimiento para el servicio de OpenID Connect de Google se puede recuperar de:
https://accounts.google.com/.well-known/openid-configuration
Para usar los servicios de OpenID Connect de Google, debes codificar el URI de 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 URI del extremo según sea necesario. Por ejemplo, a fin de autenticar a un usuario, tu código recuperará el valor de metadatos authorization_endpoint
(https://accounts.google.com/o/oauth2/v2/auth
en el siguiente ejemplo) como el URI de base para las solicitudes de autenticación que se envían a Google.
A continuación, se muestra un ejemplo de un documento de este tipo; los nombres de los campos son los que se especifican en OpenID Connect Discovery 1.0 (consulta los significados de esos documentos). Los valores son solo ilustrativos y pueden cambiar, aunque se copian de una versión reciente del documento real 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" ] }
Para evitar una ida y vuelta HTTP, almacena en caché los valores del documento de descubrimiento. Los encabezados de almacenamiento en caché HTTP estándar se usan y se deben respetar.
Bibliotecas cliente
Las siguientes bibliotecas cliente facilitan la implementación de OAuth 2.0 mediante la integración en frameworks populares:
- Biblioteca cliente de las API de Google para Java
- Biblioteca cliente de las API de Google para Python
- Biblioteca cliente de las API de Google para .NET
- Biblioteca cliente de las API de Google para Ruby
- Biblioteca cliente de las API de Google para PHP
- Biblioteca OAuth 2.0 para el kit de herramientas web de Google
- Cajas de herramientas de Google para controladores OAuth 2.0 para Mac
Cumplimiento de OpenID Connect
El sistema de autenticación OAuth 2.0 de Google admite las funciones necesarias de la especificación OpenID Connect Core. Cualquier cliente que esté diseñado para funcionar con OpenID Connect debe interoperar con este servicio (excepto el objeto de solicitud de OpenID).