OpenID Connect

Las API 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 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 manera 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

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 para obtener credenciales de OAuth 2.0, establecer un URI de redireccionamiento y (opcionalmente) personalizar la información de marca que tus usuarios ven en la pantalla de consentimiento del usuario. También puedes usar API Console para crear una cuenta de servicio, habilitar la facturación, configurar filtros 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 de cliente y un secreto del 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 :

  1. Go to the Credentials page.
  2. Haga clic en el nombre de su credencial o en el ícono de lápiz ( ). Su ID de cliente y secreto están en la parte superior de la página.

Cómo configurar un URI de redireccionamiento

El URI de redireccionamiento que estableces en API Console determina el lugar en el que Google envía 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:

  1. Go to the Credentials page.
  2. In the OAuth 2.0 client IDs section of the page, click a credential.
  3. 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 está divulgando y las condiciones que se aplican. Por ejemplo, cuando el usuario accede, es posible que se le solicite que le otorgue a tu app acceso a su dirección de correo electrónico y a la información básica de la cuenta. Solicita acceso a esta información mediante 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 de tu producto, el logotipo y la URL de la página principal. Puedes controlar la información de desarrollo de la marca en API Console.

Para habilitar la pantalla de consentimiento de su proyecto:

  1. Abra el Consent Screen page en el Google API Console .
  2. If prompted, select a project, or create a new one.
  3. 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 si estuviera presente 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 información de marca que se establecería en API Console).

Captura de pantalla de la página de consentimiento

Accede al servicio

Google y los terceros proporcionan bibliotecas que puedes usar para ocuparte de muchos de los detalles de implementación relacionados con la autenticación de usuarios y 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.

Si decides no usar una biblioteca, sigue las instrucciones que se indican en el resto de este documento, que describe los flujos de solicitudes HTTP subyacentes 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 utilizados 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 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 en el manejo y uso de tokens del lado del cliente. Si necesitas implementar un flujo implícito, te recomendamos que uses los Servicios de identidad de Google.

Flujo del servidor

Asegúrate de configurar la app en API Console para habilitarla y 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 el token de acceso y el token de ID
  5. Obtén información del usuario a partir del token de ID
  6. Cómo autenticar 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 conserve el estado entre tu app y el cliente del usuario. Más adelante, haces 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. Por lo general, estos tokens se denominan 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 construidos con un generador de números al azar de alta calidad. Otro es el hash que se genera cuando se firman algunas de las variables de estado de la sesión con una clave secreta 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 API de Google para PHP si quieres 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 si deseas usar esta muestra.

// 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 API de Google para Python a fin de 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 formar una solicitud GET HTTPS 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 mediante el valor de metadatos authorization_endpoint. En el siguiente debate, se da por sentado 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 Console Credentials page.
  • response_type, que en una solicitud de flujo de código de autorización básica debe ser code. (Obtén más información en response_type).
  • scope, que en una solicitud básica debe ser openid email. (Obtén más información en scope).
  • 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 Console Credentials page. Si este valor no coincide con un URI autorizado, la solicitud fallará y mostrará el 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 vuelve 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 la 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 string sub, que equivale al ID de Google del usuario. Si no proporcionas un login_hint y el usuario ya accedió, la pantalla de consentimiento incluirá una solicitud de aprobación para lanzar 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 a fin de optimizar el flujo de OpenID Connect para los usuarios de un dominio en particular asociado con una organización de Google Workspace o Cloud (obtén más información en hd).

A continuación, se muestra un ejemplo de un URI de autenticación completo de OpenID Connect, 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 la cuenta que no hayan aprobado anteriormente.

3. Confirma el token de estado contra la falsificació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 puede verse 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, y no una secuencia de comandos maliciosa, realice la solicitud.

En el siguiente código, se muestra la confirmación de los tokens de sesión que creaste en el paso 1:

PHP

Debes descargar la biblioteca cliente de las API de Google para PHP si quieres 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 si deseas 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.queryParams("state").equals(
    request.session().attribute("state"))) {
  response.status(401);
  return GSON.toJson("Invalid state parameter.");
}

Python

Debes descargar la biblioteca cliente de las API de Google para Python a fin de 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 el token de acceso y el 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. Tu servidor envía una solicitud POST HTTPS para realizar este intercambio. 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 el siguiente debate, se supone que el extremo es https://oauth2.googleapis.com/token. La solicitud debe incluir los siguientes parámetros en el cuerpo 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 Cómo obtener credenciales de OAuth 2.0.
client_secret El secreto de cliente que obtienes de API Console Credentials page, como se describe en Cómo obtener 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 Cómo configurar 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 Un token que se puede enviar a una API de Google.
expires_in La vida útil restante del token de acceso, expresada en segundos.
id_token Un JWT que contiene información de identidad sobre el usuario con la firma digital de Google.
scope Los alcances de acceso que otorga el access_token, expresados como una lista de strings delimitadas 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 access_type se estableció en offline en la solicitud de autenticación. Para obtener más detalles, consulta Tokens de actualización.

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. 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 intermediario libre y usas el secreto del cliente para autenticarte ante Google, puedes tener la certeza de que el token que recibes proviene de Google y es válido. Si el servidor pasa el token de ID a otros componentes de la app, es extremadamente importante que los otros componentes validen el token antes de usarlo.

Debido a 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 de él, es probable que valides el token de todas formas 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": "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 claims):

Claim Proporcionado 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 de la cual no se debe aceptar el token de ID. Se representa en tiempo Unix (números enteros en segundos).
iat always La hora en que se emitió el token de ID. Se representa en tiempo Unix (segundos de número entero).
iss always El identificador de la entidad emisora de la respuesta. Siempre usa 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 que nunca se reutilizó. Una Cuenta de Google puede tener varias direcciones de correo electrónico en diferentes momentos, pero el valor de sub nunca se cambia. Usa sub en tu aplicación como la clave de identificador único para el usuario. La longitud máxima debe ser de 255 caracteres ASCII que distinguen mayúsculas de 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, siempre se incluye esta reclamación. Esta reclamación se puede usar como un mecanismo alternativo de protección 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 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 comparten el mismo proyecto de las APIs de Google.
email La dirección de correo electrónico del usuario. Solo se proporciona si incluiste el alcance email en tu solicitud. Es posible que el valor de esta declaración no sea exclusivo de esta cuenta y podría cambiar con el tiempo. Por lo tanto, 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 organizaciones de Google Workspace o de Cloud. En su lugar, usa la reclamación 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 o apellidos del usuario. Se puede proporcionar cuando hay una reclamación name presente.
given_name Los nombres o los nombres del usuario. Se puede proporcionar cuando hay una reclamación name presente.
hd Indica el dominio asociado con la organización de Google Workspace o Cloud del usuario. Solo se proporciona 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 miembros de ciertos dominios. La ausencia de este reclamo 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 una reclamación name presente.
name El nombre completo del usuario, en un formato visible. Se puede proporcionar en los siguientes casos:
  • El alcance de la solicitud incluyó la string "profile"
  • El token de ID se muestra cuando se actualiza un token

Cuando existen reclamaciones de name, puedes usarlas para actualizar los registros de los usuarios de tu app. Ten en cuenta que nunca se garantiza que este reclamo esté presente.

nonce El valor del nonce que proporciona tu app en la solicitud de autenticación. Debes aplicar la protección contra los ataques de repetición, para lo cual debes asegurarte de que se presente solo una vez.
picture La URL de la foto de perfil del usuario. Se puede proporcionar en los siguientes casos:
  • El alcance de la solicitud incluyó la string "profile"
  • El token de ID se muestra cuando se actualiza un token

Cuando existen reclamaciones de picture, puedes usarlas para actualizar los registros de los usuarios de tu app. Ten en cuenta que nunca se garantiza que este reclamo esté presente.

profile La URL de la página de perfil del usuario. Se puede proporcionar en los siguientes casos:
  • El alcance de la solicitud incluyó la string "profile"
  • El token de ID se muestra cuando se actualiza un token

Cuando existen reclamaciones de profile, puedes usarlas para actualizar los registros de los usuarios de tu app. Ten en cuenta que nunca se garantiza que este reclamo esté presente.

6. Autentica al usuario

Después de obtener 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 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 usuario nuevo. Puedes registrar al usuario de forma automática según la información que recibas de Google o, al menos, completar previamente muchos de los campos que debes incluir en el formulario de registro. Además de la información en el token de ID, puedes obtener información de perfil del 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 mayor detalle. Esta información está dirigida a los desarrolladores con requisitos avanzados relacionados con la autenticación y la 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) y al mismo tiempo que se autentica 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 la edad 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 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 se te 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 APIs de Google mientras el usuario no está presente en ella. 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 uno la primera vez que realizas el flujo de intercambio de código.
  • Existen límites para 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, puede llegar a estos límites, en cuyo caso los tokens de actualización más antiguos dejan de funcionar.

Para obtener más información, consulta Cómo actualizar un token de acceso (acceso sin conexión).

Puedes pedirle al usuario que vuelva a autorizar tu app si configuras 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 autorización de alcances de acceso, incluso si todos los permisos se otorgaron previamente a tu proyecto de 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 Obligatorias Descripción
client_id (Obligatorio) Es la string del ID de cliente que se obtiene de Credentials pagede API Console, como se describe en Cómo obtener credenciales de OAuth 2.0.
nonce (Obligatorio) Un valor aleatorio que genera la app y que habilita la protección contra la repetición.
response_type (Obligatorio) Si el valor es code, inicia un flujo de código de autorización básica que requiere un POST en el 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 desde el 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 API Console Credentials page (incluidos el esquema HTTP o HTTPS, el caso y la “/” final, si corresponde).
scope (Obligatorio)

El parámetro del alcance debe comenzar con el valor openid y, luego, incluir el valor profile, el email o ambos.

Si el valor del permiso profile está presente, el token de ID puede (aunque no se garantiza que lo haga) las reclamaciones 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, 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 deseas tener acceso por archivo a la cuenta 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 alcances disponibles, consulta Alcances 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)

Es una string opaca que se hace un recorrido de 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 #fragment de URI en el flujo implícito.

state puede ser útil para relacionar solicitudes y respuestas. Como tu redirect_uri puede adivinarse, usar un valor state puede aumentar tu seguridad de que una conexión entrante es el resultado de una solicitud de autenticación que inicia tu app. Si generas una string aleatoria o codificas el hash de algún estado del cliente (p.ej., una cookie) en esta variable state, puedes validar la respuesta para garantizar, además, que la solicitud y la respuesta se originen 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.
display (opcional) Valor de string 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 estos no influyen en su comportamiento: page, popup, touch y wap.
hd (opcional)

Optimizar 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 debe optimizarse para las cuentas en ese dominio. Si deseas realizar optimizaciones para las cuentas de organización de Google Cloud en general, en lugar de solo un dominio de la organización de Google Cloud, establece un valor de un 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 validate que el token de ID que se muestra 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 del token de ID hd se encuentra dentro de un token de seguridad de Google, por lo que el valor es confiable.

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á todas las autorizaciones previas otorgadas a esta combinación de usuario y 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 está intentando autenticar, puede proporcionar este parámetro como una sugerencia para el 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 utiliza el acceso múltiple), lo que puede ayudarte a evitar problemas 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) Una lista delimitada por espacios de valores de string que especifica si el servidor de autorización solicita al usuario volver a autenticarse y dar su consentimiento. Los valores posibles son los siguientes:
  • none

    El servidor de autorización no muestra ninguna pantalla de autenticación ni de consentimiento del usuario. Por lo tanto, mostrará un error si el usuario aún no se autenticó y no tiene el consentimiento preconfigurado 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 mostrarle información al cliente.

  • select_account

    El servidor de autorización 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 en las que puede tener sesiones actuales.

Si no se especifica ningún valor y el usuario no autorizó el acceso con anterioridad, se le mostrará una pantalla de consentimiento.

Cómo validar 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 todos los 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:

  • Envío de tokens de ID con solicitudes que se deban autenticar. Los tokens de ID 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 la solicitud. Si almacenas tokens de ID en tu servidor, también debes almacenarlos de forma segura.

Un aspecto útil de los tokens de ID es el hecho de que puedes pasarlos por diferentes componentes de la app. Estos componentes pueden usar un token de ID como mecanismo de autenticación ligero que autentica la app y al usuario. Pero antes de poder usar la información en el 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 mediante 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 se haya pasado la hora de vencimiento (reclamo de 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 con una organización de Google Cloud.

Los pasos del 2 al 5 solo incluyen comparaciones entre strings 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 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, deberías anular la referencia del 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 forma de objeto JSON decodificado.

El extremo tokeninfo es útil para depurar, pero para fines de producción, debes recuperar las claves públicas de Google desde el extremo de claves y realizar la validación de manera local. Debes recuperar el URI de las 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 solo con poca frecuencia, puedes almacenarlas en caché mediante las directivas de caché de la respuesta HTTP y, en la gran mayoría de los casos, realizar una validación local 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. Por suerte, existen bibliotecas bien depuradas disponibles en una amplia variedad de lenguajes para lograr esto (consulta jwt.io).

Obtén 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:

  1. Para cumplir con OpenID, debes incluir los valores de alcance 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 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 mediante el valor de metadatos userinfo_endpoint. La respuesta 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 recibas información de cada uno de ellos para los permisos de acceso autorizados.

El documento de descubrimiento

El protocolo OpenID Connect requiere el uso de varios extremos para autenticar usuarios y solicitar recursos, como 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 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, userinfo y claves públicas. El documento de descubrimiento para el servicio OpenID Connect de Google se puede recuperar desde:

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

Para usar los servicios de OpenID Connect de Google, debes codificar 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 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 ejemplo a continuación) como el URI 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 ese documento para conocer sus significados). Los valores son meramente 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"
  ]
}

Para evitar un recorrido de ida y vuelta HTTP, almacena en caché los valores del documento de descubrimiento. Se usan y deben respetar los encabezados de almacenamiento en caché HTTP estándar.

Bibliotecas cliente

Las siguientes bibliotecas cliente facilitan la implementación de OAuth 2.0, ya que se integran en frameworks populares:

Cumplimiento de OpenID Connect

El sistema de autenticación 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 debe interoperar con este servicio (a excepción del objeto de solicitud de OpenID).