OpenID Connect

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 quieres explorar este protocolo de forma interactiva, te recomendamos que uses Google OAuth 2.0 Playground. Para obtener ayuda en Stack Overflow, etiqueta tus preguntas con "google-oauth".

Nota: Para proporcionar un botón "Acceder con Google" en tu sitio web, usa Google Identity Services, nuestra biblioteca cliente de acceso compilada en el protocolo OpenID Connect. Esta biblioteca proporciona tokens de ID con formato de OpenID Connect. Las apps para Android deben usar la API de Credential Manager para implementar el flujo de Acceder con Google.

Configura OAuth 2.0

Antes de 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 la consola de Google Cloud 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 del usuario. También puedes usar la consola de Cloud 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 de la consola de Google Cloud.

Obtén credenciales de OAuth 2.0

Necesitas credenciales de OAuth 2.0, incluidos un ID de cliente y un secreto del cliente, para autenticar a los usuarios y obtener acceso a las APIs de Google.

Para ver el ID de cliente y el secreto del cliente de una credencial de OAuth 2.0 determinada, haz clic en el siguiente texto: Seleccionar credencial. En la ventana que se abre, elige tu proyecto y la credencial que quieras y, luego, haz clic en Ver.

También puedes ver tu ID de cliente y el secreto de cliente en la página Clientes de la consola de Cloud:

1. Ve a la página Clientes.
2. Haz clic en el nombre de tu cliente o en el ícono de edición (). El ID de cliente y el secreto se encuentran en la parte superior de la página.

Establece un URI de redireccionamiento

El URI de redireccionamiento que configuras en la consola de Cloud determina dónde envía Google las respuestas a tus solicitudes de autenticación.

Para crear, ver o editar los URIs de redireccionamiento de una credencial de OAuth 2.0 determinada, haz lo siguiente:

1. Ve a la página Clientes.
2. Haz clic en el cliente.
3. Consulta o edita los URIs de redireccionamiento.

Si no hay ningún cliente en la página Clientes, tu proyecto no tiene credenciales de OAuth. Para crear uno, haz clic en Crear cliente.

Personaliza la pantalla de consentimiento del usuario

Para tus usuarios, la experiencia de autenticación de OAuth 2.0 incluye una pantalla de consentimiento en la que se describe la información que el usuario divulga y las condiciones que se aplican. Por ejemplo, cuando el usuario accede, es posible que se le solicite que otorgue a tu app acceso 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 permisos 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 del producto, el logotipo y una URL de la página principal. Tú controlas la información de desarrollo de la marca en la consola de Cloud.

Para habilitar la pantalla de consentimiento de tu proyecto, sigue estos pasos:

1. Abre la página de desarrollo de la marca en la consola de Google Cloud.
2. Si se te solicita, selecciona un proyecto o crea uno nuevo.
3. Completa el formulario y haz clic en Guardar.

En el siguiente cuadro de diálogo de consentimiento, se muestra lo que vería un usuario cuando se incluye 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 configuraría en la consola de Cloud).

Figura 1: Captura de pantalla de la página de consentimiento

Accede al servicio

Google y terceros proporcionan bibliotecas que puedes usar para encargarte de muchos de los detalles de implementación de la autenticación de usuarios y de la obtención de acceso a las APIs de Google. Algunos ejemplos son los Servicios de identidad de Google y las bibliotecas cliente de Google, que están disponibles para una variedad de plataformas.

Nota: Dadas las implicaciones de seguridad de obtener la implementación correcta, te recomendamos que aproveches una biblioteca o un servicio escritos previamente. Autenticar a los usuarios de forma correcta es importante para su seguridad y la tuya, y usar código bien depurado escrito por otros suele ser una práctica recomendada. Para obtener más información, consulta Bibliotecas cliente.

Si decides no usar una biblioteca, sigue las instrucciones que se indican en el resto de este documento, en el que se describen los flujos de solicitudes HTTP que subyacen a las bibliotecas disponibles.

Autenticación del usuario

Para autenticar al usuario, se debe 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 de uso frecuente para autenticar a un usuario y obtener un token de ID se denominan flujo de "servidor" y flujo "implícito". El flujo del servidor 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 usar 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 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 la consola de Cloud para que pueda usar estos protocolos y autenticar a tus usuarios. Cuando un usuario intenta acceder con Google, debes hacer lo siguiente:

1. Crea un token de estado antifalsificación
2. Envía una solicitud de autenticación a Google
3. Confirma el token de estado antifalsificación
4. Intercambia code por un token de acceso y un token de ID
5. Obtén información del usuario a partir del token de ID
6. Autentica al usuario

1. Crea un token de estado antifalsificació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. Luego, debes hacer coincidir este token de sesión único con la respuesta de autenticación que devuelve 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 alrededor de 30 caracteres construida con un generador de números aleatorios de alta calidad. Otra opción es un hash que se genera firmando algunas de las variables de estado de la sesión con una clave que se mantiene en secreto en el 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 este ejemplo.

// 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

Debes descargar la biblioteca cliente de las APIs de Google para Java para usar este ejemplo.

// 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 este ejemplo.

# 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 HTTPS GET con los parámetros de URI adecuados. 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 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 la página Clientes de la consola de Cloud
• response_type, que en una solicitud de flujo de código de autorización básico debe ser code. (Obtén más información en response_type).
• scope, que en una solicitud básica debería ser openid email. (Obtén más información en scope).
• 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 URI de redireccionamiento autorizados para el cliente de OAuth 2.0, que configuraste en la página Credenciales de la consola de Cloud. Si este valor no coincide con un URI autorizado, la solicitud fallará con un error redirect_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 regrese a tu aplicación, p.ej., la URL de inicio. (Obtén más información en state).
• nonce es un valor aleatorio que genera tu app y que habilita la protección contra repeticiones cuando está presente.
• login_hint puede ser la dirección de correo electrónico del usuario o la cadena sub, que equivale al ID de Google del usuario. Si no proporcionas un login_hint y el usuario accedió, la pantalla de consentimiento incluye una solicitud de aprobación para divulgar la dirección de correo electrónico del usuario a tu app. (Obtén más información en login_hint).
• Usa el parámetro hd para optimizar el flujo de OpenID Connect para los usuarios de un dominio específico asociado con una organización de Google Workspace o Cloud (obtén más información en hd).

Nota: Estos son algunos de los parámetros de uso frecuente. Para obtener una lista completa y más detalles sobre todos los parámetros, consulta Parámetros de URI de autenticación.

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//developers.google.com/oauthplayground&
 state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2-login-demo.example.com%2FmyHome&
 login_hint=[e-mail]&
 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 la cuenta que no hayan aprobado anteriormente.

3. Confirma el token de estado antifalsificación

La respuesta se envía al redirect_uri que especificaste en la solicitud. Todas las respuestas se devuelven en la cadena de consulta:

https://developers.google.com/oauthplayground?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

Según el RFC 6749, los clientes DEBEN ignorar los parámetros de respuesta no reconocidos. 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 comprobar que el usuario, y no una secuencia de comandos maliciosa, realiza 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 este ejemplo.

// 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

Debes descargar la biblioteca cliente de las APIs de Google para Java para usar este ejemplo.

// 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 este ejemplo.

# 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 de un solo uso que tu servidor puede intercambiar por un token de acceso y un token de ID. Tu servidor realiza este intercambio enviando una solicitud HTTPS POST. La solicitud POST se envía al extremo del 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	Es el código de autorización que se devuelve de la solicitud inicial.
client_id	Es el ID de cliente que obtienes de la página Clientes de la consola de Cloud, como se describe en Obtén credenciales de OAuth 2.0.
client_secret	Es el secreto del cliente que obtienes de la página Clientes de la consola de Cloud, 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 la página Clientes de la consola de Cloud, 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//developers.google.com/oauthplayground&
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 que Google firma digitalmente.
scope	Son los permisos de acceso que otorga el access_token expresados como una lista de cadenas que distinguen mayúsculas de minúsculas y están delimitadas por espacios.
token_type	Identifica el tipo de token que se devuelve. En este momento, este campo siempre tiene el valor Bearer.
refresh_token	(opcional) Este campo solo está presente si el parámetro access_type se estableció en offline en la solicitud de autenticación. Para obtener más información, consulta Tokens de actualización.

Nota: Existe un límite para la cantidad de tokens por cuenta de usuario de Google, y cualquier solicitud de autenticación que supere este límite podría invalidar de forma silenciosa un token de actualización pendiente. Para obtener más información, consulta Vencimiento de tokens.

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 con codificación Base64 firmado de forma criptográfica. Normalmente, 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 ante Google, puedes tener la certeza de 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 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 decodificar los valores codificados en base64url y analizar el JSON que contienen, es probable que termines validando el token de todos modos cuando accedas a las reclamaciones en el token de ID.

La 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 facilitar la lectura:

{
  "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": "[e-mail]",
  "email_verified": "true",
  "iat": 1353601026,
  "exp": 1353604926,
  "nonce": "0394852-3190485-2490358"
}

Advertencia: Cuando implementes tu sistema de administración de cuentas, no debes usar el campo email en el token de ID como identificador único para un usuario. Usa siempre el campo sub, ya que es único para cada Cuenta de Google, incluso si el usuario cambia su dirección de correo electrónico.

Los tokens de ID de Google pueden contener los siguientes campos (conocidos como reclamaciones):

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 en la que no se debe aceptar el token de ID o después de la cual no se debe aceptar. Se representa en tiempo Unix (segundos enteros).
iat	siempre	Es la hora en que se emitió el token de ID. Se representa en tiempo Unix (segundos enteros).
iss	siempre	Es el identificador de la entidad emisora de la respuesta. Siempre 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 en tu aplicación como la clave de identificador único para el usuario. Longitud máxima de 255 caracteres ASCII que distinguen mayúsculas de minúsculas.
amr		Es un array de strings JSON que identifican los métodos de autenticación que se usan para acceder a una Cuenta de Google. Si está presente, incluye uno o más de estos posibles valores de [IANA.AMR]: hwk se usó una llave de hardware mfa Se completó la autenticación de varios factores pwd Se usó una contraseña sms Se usó un mensaje SMS para la verificación swk Se usó una clave de software, como una llave de acceso tel se usó una llamada telefónica para la verificación Solo está presente cuando la reclamación amr se incluye en la solicitud de autenticación y se habilita en la configuración.
auth_time		Es la hora en que se realizó la autenticación del usuario, un número JSON que representa la cantidad de segundos que transcurrieron desde el tiempo Unix (1 de enero de 1970, 00:00:00 UTC). Se proporciona cuando la reclamación auth_time se incluye en la solicitud de autenticación y se habilita en Configuración.
at_hash		Es el 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, siempre se incluye esta reclamación. Esta reclamación se puede usar como un mecanismo alternativo para protegerse contra 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 Esta reclamación solo es necesaria 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 en Google para 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 comparten el mismo proyecto de las 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 reclamación no sea único para esta cuenta y que cambie con el tiempo, por lo que no debes usarlo como el identificador principal para vincularlo a tu registro de usuario. Tampoco puedes confiar en el dominio de la reclamación email para identificar a los usuarios de las organizaciones de Google Workspace o Cloud. En su lugar, usa la reclamación hd. Advertencia: No uses el campo email como identificador único de un usuario. Usa siempre el campo sub.
email_verified		Es verdadero si se verificó la dirección de correo electrónico del usuario; de lo contrario, es falso.
family_name		Son los apellidos del usuario. Se puede proporcionar cuando hay una reclamación de name.
given_name		Son los nombres de pila o primeros nombres del usuario. Se puede proporcionar cuando hay una reclamación 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 verificar esta reclamación cuando restrinjas el acceso a un recurso solo a los miembros de ciertos dominios. La ausencia de esta reclamación indica que la cuenta no pertenece a un dominio alojado en Google.
locale		Es la configuración regional del usuario, representada por una etiqueta de idioma BCP 47. Se puede proporcionar cuando hay un reclamo de name.
name		Es el nombre completo del usuario, en un formato visible. Se puede proporcionar en los siguientes casos: El permiso de la solicitud incluía la cadena "profile". El token de ID se devuelve desde una actualización de token Cuando hay reclamaciones de name, puedes usarlas para actualizar los registros de usuarios de tu app. Ten en cuenta que no se garantiza que esta reclamación esté presente.
nonce		Es el valor de nonce que proporciona tu app en la solicitud de autenticación. Para protegerte contra los ataques de reinyección, presenta este valor solo una vez.
picture		Es la URL de la foto de perfil del usuario. Se puede proporcionar en los siguientes casos: El permiso de la solicitud incluía la cadena "profile". El token de ID se devuelve desde una actualización de token Cuando hay reclamaciones de picture, puedes usarlas para actualizar los registros de usuarios de tu app. Ten en cuenta que no se garantiza que esta reclamación esté presente.
profile		Es la URL de la página de perfil del usuario. Se puede proporcionar en los siguientes casos: El permiso de la solicitud incluía la cadena "profile". El token de ID se devuelve desde una actualización de token Cuando hay reclamaciones de profile, puedes usarlas para actualizar los registros de usuarios de tu app. Ten en cuenta que no se garantiza que esta reclamación esté presente.

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 al 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 completar previamente muchos de los campos que necesitas 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 más 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 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 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 recibas de Google permitirá que tu aplicación acceda a todas las APIs relacionadas con los permisos de acceso que solicitaste y que se te otorgaron.

Nota: Si tu aplicación solicita muchos permisos, la pantalla de consentimiento contendrá muchas líneas de texto. Cuantos más permisos solicite tu aplicación, menos probable será que el usuario dé su consentimiento, por lo que tu aplicación solo debe solicitar los permisos que necesita.

Tokens de actualización

En tu solicitud de acceso a la API, puedes pedir que se devuelva un token de actualización durante el intercambio de code. Un token de actualización 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ódigo.
• Existen límites en la cantidad de tokens de actualización que se emiten: un límite por combinación de cliente y usuario, y otro por usuario en todos los clientes. Si tu aplicación solicita demasiados tokens de actualización, es posible que alcance 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).

Cómo solicitar que se vuelva a dar el consentimiento

Puedes pedirle al usuario que vuelva a autorizar tu app configurando el parámetro prompt como 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 las 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)	Es la cadena de ID de cliente que obtienes de la página Clientes de la consola de Cloud, 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 ataques de 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 para el extremo del 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 de URI #fragment.
redirect_uri	(Obligatorio)	Determina 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 página Clientes de la consola de Cloud (incluidos el esquema HTTP o HTTPS, las mayúsculas y minúsculas, y la barra diagonal final, si la hay).
scope	(Obligatorio)	El parámetro de alcance debe comenzar con el valor openid y, luego, incluir el valor profile, el valor email o ambos. Si el valor del permiso profile está presente, el token de ID podría incluir (pero no se garantiza que lo haga) las reclamaciones de profile predeterminadas del usuario. Si el valor del permiso email está presente, el token de ID incluye las reclamaciones email y email_verified. Además de estos permisos específicos de OpenID, el argumento de permiso también puede incluir otros valores de permiso. Todos los valores de permiso deben estar separados por espacios. Por ejemplo, si quisieras acceso por archivo a la unidad de Google Drive de un usuario, el parámetro de alcance podría ser openid profile email https://www.googleapis.com/auth/drive.file. Para obtener información sobre los permisos disponibles, consulta Permisos de OAuth 2.0 para las APIs de Google o la documentación de la API de Google que quieras usar.
state	(Opcional, pero muy recomendado)	Es una cadena opaca que se envía y se devuelve en el protocolo, es decir, se devuelve como un parámetro de URI en el flujo básico y en el identificador de URI #fragment en el flujo implícito. El state puede ser útil para correlacionar solicitudes y respuestas. Como se puede adivinar tu redirect_uri, usar un valor state puede aumentar tu seguridad de que una conexión entrante es el resultado de una solicitud de autenticación iniciada por tu app. Si generas una cadena aleatoria o codificas el hash de algún estado del cliente (p.ej., una cookie) en esta variable state, puedes validar la respuesta para verificar que la solicitud y la respuesta se originaron en el mismo navegador. Esto proporciona protección contra ataques, como la falsificación de solicitudes entre sitios.
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.
claims	(Opcional)	El parámetro de reclamaciones se usa para especificar uno o más campos opcionales que se incluirán en el extremo de userinfo o en los tipos de respuesta de token de ID de solicitud de autenticación. El valor es un objeto JSON que contiene el tipo de respuesta y las reclamaciones solicitadas. Los servidores de Google aceptan las siguientes solicitudes de reclamo: Solicitudes de reclamo amr Solicita el método que se usó cuando el usuario se autenticó por última vez. Para devolver amr como un campo en la respuesta del token de ID, incluye el parámetro de solicitud claims: claims={"id_token":{"amr":{"essential":true}}} Debe estar habilitado en la configuración. auth_time Solicita la hora en que se autenticó el usuario por última vez. Para devolver auth_time como un campo en la respuesta del token de ID, incluye el parámetro de solicitud claims: claims={"id_token":{"auth_time":{"essential":true}}} Debe estar habilitado en la configuración.
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 siguientes valores se especifican y los servidores de Google los aceptan, pero no tienen ningún efecto en el comportamiento del flujo del protocolo: 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 cuentas se debe optimizar para las cuentas de ese dominio. Para optimizar 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 (*): hd=*. No confíes en esta optimización de la IU para controlar quién puede acceder a tu app, ya que las solicitudes del cliente se pueden modificar. Asegúrate de validar que el token de ID devuelto tenga un valor de reclamación hd que coincida con lo que esperas (p.ej., mycolledge.edu). A diferencia del parámetro de solicitud, la reclamación hd del token de ID se incluye en un token de seguridad de Google, por lo que se puede confiar en el valor.
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 la app instalada.
login_hint	(Opcional)	Cuando tu app sabe qué usuario intenta autenticar, puede proporcionar este parámetro como sugerencia al servidor de autenticación. Pasar esta sugerencia suprime el selector de cuentas y precompleta el cuadro de correo electrónico en el formulario de acceso o selecciona la sesión adecuada (si el usuario usa el acceso múltiple), 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 solicita al usuario que vuelva a autenticarse y otorgue su consentimiento. Los siguientes son los valores posibles: none El servidor de autorización no muestra ninguna pantalla de autenticación ni de consentimiento del usuario; devolverá un error si el usuario aún no se autenticó y no configuró previamente el consentimiento para los permisos solicitados. Puedes usar none para verificar la autenticación o el consentimiento existentes. consent El servidor de autorización solicita el consentimiento del usuario antes de devolver información al cliente. select_account El servidor de autorización le solicita al usuario que seleccione una cuenta de usuario. Esto permite que un usuario que tiene varias cuentas en el servidor de autorización seleccione entre las múltiples cuentas para las que puede tener sesiones actuales. Si no se especifica ningún valor y el usuario no autorizó el acceso anteriormente, se le mostrará una pantalla de consentimiento.
hl	(Opcional)	Es una etiqueta de idioma BCP 47 que se usa para especificar el idioma de visualización de las pantallas de acceso, de selección de cuenta y de consentimiento. Si no se proporciona este parámetro, el idioma se establece de forma predeterminada según la configuración de la Cuenta de Google o del navegador del usuario. Por ejemplo, para solicitar la IU en inglés británico, establece el parámetro en en-GB.

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.

A continuación, se indican situaciones comunes en las que puedes enviar tokens de ID a tu servidor:

• Envía tokens de ID con solicitudes que se deben autenticar. Los tokens de ID te indican 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 transmitiéndolos solo a través de HTTPS y solo con datos de POST o dentro de los encabezados de la solicitud. Si almacenas tokens de ID en tu servidor, también debes hacerlo de forma segura.

Un aspecto que hace que los tokens de ID sean útiles es que puedes pasarlos por 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 al usuario. Sin embargo, antes de poder usar la información del token de ID o confiar en ella como una aserción de que el usuario se autenticó, debes validarla.

La validación de un token de ID requiere varios pasos:

1. Verifica que la entidad emisora 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.
2. Verifica que el valor de la reclamación iss en el token de ID sea igual a https://accounts.google.com o accounts.google.com.
3. Verifica que el valor de la reclamación aud en el token de ID sea igual al ID de cliente de tu app.
4. Verifica que no haya pasado el tiempo de vencimiento (reclamación exp) del token de ID.
5. 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 del 2 al 5 solo implican comparaciones de cadenas y fechas, que son bastante sencillas, por lo que no las detallaremos aquí.

El primer paso es más complejo y, además, implica la verificación de la firma criptográfica. Para fines de 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 del JWT en su forma de objeto JSON decodificado.

El extremo tokeninfo es útil para la depuración, pero, con fines de producción, recupera las claves públicas de Google del 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. Las solicitudes al extremo de depuración pueden limitarse o estar sujetas a errores intermitentes.

Como Google cambia sus claves públicas con poca frecuencia, puedes almacenarlas en caché con las directivas de almacenamiento en 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áficas adecuadas para verificar la firma. Afortunadamente, hay bibliotecas bien depuradas disponibles en una amplia variedad de lenguajes para lograrlo (consulta jwt.io).

Obtén información del perfil de 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:

1. Para cumplir con OpenID, debes incluir los valores del permiso 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 permiso adicional de email. Para especificar profile y email, puedes incluir el siguiente parámetro en el URI de la solicitud de autenticación:

   scope=openid%20profile%20email
   

2. 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 metadatos userinfo_endpoint. La respuesta de userinfo incluye información sobre el usuario, como se describe en OpenID Connect Standard Claims y el valor de metadatos claims_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 cada campo de tus permisos de acceso autorizados.

El documento de descubrimiento

El protocolo 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", un documento JSON que se encuentra en una ubicación conocida y que contiene pares clave-valor que proporcionan 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 del servicio de OpenID Connect de Google se puede recuperar de la siguiente ubicación:

https://accounts.google.com/.well-known/openid-configuration

Para usar los servicios de OpenID Connect de Google, debes codificar de forma rígida 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 URI de extremos de él 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 ese documento; los nombres de los campos son los que se especifican en OpenID Connect Discovery 1.0 (consulta ese documento para conocer sus significados). Los valores son meramente ilustrativos y pueden cambiar, aunque se copian de una versión reciente del documento de descubrimiento de Google Descubre real:

{
  "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 un viaje de ida y vuelta de HTTP, puedes almacenar 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 simplifican la implementación de OAuth 2.0, ya que se integran en 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 para Mac

Cumplimiento de OpenID Connect

El sistema de autenticación de OAuth 2.0 de Google admite las funciones requeridas de la especificación de 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).