Conexión OpenID

Las API de OAuth 2.0 de Google se pueden utilizar tanto para la autenticación como para la autorización. Este documento describe nuestra implementación de OAuth 2.0 para la autenticación, que cumple con la especificación OpenID Connect y tiene certificación OpenID . La documentación que se encuentra en Uso de OAuth 2.0 para acceder a las API de Google también se aplica a este servicio. Si desea explorar este protocolo de forma interactiva, le recomendamos Google OAuth 2.0 Playground . Para obtener ayuda sobre Stack Overflow , etiquete sus preguntas con 'google-oauth'.

Nota: Si desea proporcionar un botón "Iniciar sesión con Google" para su sitio web o aplicación, le recomendamos que utilice Inicio de sesión de Google , nuestra biblioteca de cliente de inicio de sesión que se basa en el protocolo OpenID Connect y proporciona un ID con formato OpenID Connect. Fichas.

Configuración de OAuth 2.0

Antes de que su aplicación pueda utilizar el sistema de autenticación OAuth 2.0 de Google para el inicio de sesión del usuario, debe configurar un proyecto en el Google API Console para obtener las credenciales OAuth 2.0, establecer un URI de redireccionamiento y (opcionalmente) personalizar la información de marca que sus usuarios ven en el usuario. pantalla de consentimiento. También puede 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 detalles, consulte la Ayuda de Google API Console .

Obtenga las credenciales de OAuth 2.0

Necesita credenciales de OAuth 2.0, incluido un ID de cliente 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 :

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.

Establecer un URI de redireccionamiento

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

1. Go to the Credentials page.
2. En la sección de ID de cliente OAuth 2.0 de la página, haga clic en una credencial.
3. 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 .

Personalizar la pantalla de consentimiento del usuario

Para sus usuarios, la experiencia de autenticación OAuth 2.0 incluye una pantalla de consentimiento que describe la información que el usuario está publicando y los términos que se aplican. Por ejemplo, cuando el usuario inicia sesión, es posible que se le solicite que le dé acceso a su aplicación 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 de scope , que su aplicación incluye en su solicitud de autenticación . También puede utilizar ámbitos para solicitar acceso a otras API de Google.

La pantalla de consentimiento del usuario también presenta información de marca, como el nombre de su producto, el logotipo y la URL de una página de inicio. Tú controlas la información de marca en el 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 .

El siguiente cuadro de diálogo de consentimiento muestra lo que vería un usuario cuando una combinación de los alcances de OAuth 2.0 y Google Drive están presentes en la solicitud. (Este cuadro de diálogo genérico se generó utilizando Google OAuth 2.0 Playground , por lo que no incluye información de marca que se establecería en API Console).

Accediendo al servicio

Google y terceros proporcionan bibliotecas que puede utilizar para ocuparse de muchos de los detalles de implementación para autenticar usuarios y obtener acceso a las API de Google. Los ejemplos incluyen el inicio de sesión de Google y las bibliotecas cliente de Google , que están disponibles para una variedad de plataformas.

Nota: Dadas las implicaciones de seguridad de lograr la implementación correcta, le recomendamos encarecidamente que aproveche una biblioteca o servicio preescrito. La autenticación adecuada de los usuarios es importante para ellos y para su seguridad y protección, y el uso de código bien depurado escrito por otros es generalmente una buena práctica. Para obtener más información, consulte Bibliotecas cliente .

Si elige no utilizar una biblioteca, siga las instrucciones en el resto de este documento, que describe los flujos de solicitud HTTP que subyacen a las bibliotecas disponibles.

Autenticar al usuario

La autenticación del usuario implica obtener un token de identificación y validarlo. Los tokens de identificación son una función estandarizada de OpenID Connect diseñada para compartir afirmaciones de identidad en Internet.

Los métodos más utilizados para autenticar a un usuario y obtener un token de identificación se denominan flujo "servidor" y flujo "implícito". El flujo del servidor permite que el servidor back-end de una aplicación verifique la identidad de la persona usando un navegador o dispositivo móvil. El flujo implícito se utiliza cuando una aplicación del lado del cliente (normalmente una aplicación de JavaScript que se ejecuta en el navegador) necesita acceder a las API directamente en lugar de a través de su servidor back-end.

Este documento describe cómo realizar el flujo del servidor para autenticar al usuario. El flujo implícito es significativamente más complicado debido a los riesgos de seguridad en el manejo y uso de tokens en el lado del cliente. Si necesita implementar un flujo implícito, le recomendamos que utilice el inicio de sesión de Google .

Flujo del servidor

Asegúrese de configurar su aplicación en el API Console para permitirle usar estos protocolos y autenticar a sus usuarios. Cuando un usuario intenta iniciar sesión con Google, debe:

1. Crea un token de estado anti-falsificación
2. Envía una solicitud de autenticación a Google
3. Confirmar el token de estado anti-falsificación
4. code intercambio para token de acceso y token de identificación
5. Obtener información de usuario del token de identificación
6. Autenticar al usuario

1. Crea un token de estado anti-falsificación

Debe proteger la seguridad de sus usuarios evitando ataques de falsificación de solicitudes. El primer paso es crear un token de sesión único que mantenga el estado entre su aplicación y el cliente del usuario. Luego, hace coincidir este token de sesión único con la respuesta de autenticación que devuelve el servicio de inicio de sesión de Google OAuth para verificar que el usuario está realizando la solicitud y no un atacante malintencionado. Estos tokens a menudo se denominan tokens de falsificación de solicitud entre sitios ( CSRF ).

Una buena opción para un token de estado es una cadena de aproximadamente 30 caracteres construida con un generador de números aleatorios de alta calidad. Otro es un hash generado al firmar algunas de las variables de estado de su sesión con una clave que se mantiene en secreto en su back-end.

El siguiente código demuestra la generación de tokens de sesión únicos.

PHP

Debe descargar la biblioteca cliente de las API de Google para PHP para usar esta muestra.

// Create a state token to prevent request forgery.
// Store it in the session for later validation.
$state = bin2hex(random_bytes(128/8));
$app['session']->set('state', $state);
// Set the client ID, token state, and application name in the HTML while
// serving it.
return $app['twig']->render('index.html', array(
    'CLIENT_ID' => CLIENT_ID,
    'STATE' => $state,
    'APPLICATION_NAME' => APPLICATION_NAME
));

Java

Debe descargar la biblioteca cliente de las API de Google para Java para 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);

Pitón

Debe descargar la biblioteca cliente de las API de Google para que Python use 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 HTTPS GET con los parámetros de URI adecuados. Tenga en cuenta el uso de HTTPS en lugar de HTTP en todos los pasos de este proceso; Se rechazan las conexiones HTTP. Debe recuperar el URI base del documento de descubrimiento mediante el valor de metadatos de punto de finalización de authorization_endpoint . La siguiente discusión asume que el URI base es https://accounts.google.com/o/oauth2/v2/auth .

Para una solicitud básica, especifique los siguientes parámetros:

• client_id , que se obtiene del API Console Credentials page.
• response_type , que en una solicitud de flujo de código de autorización básico debe ser code . (Lea más en response_type .)
• scope , que en una solicitud básica debe ser openid email . (Lea más en el scope ).
• redirect_uri debe ser el punto final HTTP en su servidor que recibirá la respuesta de Google. El valor debe coincidir exactamente con uno de los URI de redireccionamiento autorizados para el cliente OAuth 2.0, que configuró en API Console Credentials page. 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 anti-falsificación, así como cualquier otra información necesaria para recuperar el contexto cuando el usuario regresa a su aplicación, por ejemplo, la URL de inicio. (Lea más en el state ).
• nonce es un valor aleatorio generado por su aplicación que habilita la protección de reproducción cuando está presente.
• login_hint puede ser la dirección de correo electrónico del usuario o el sub cadena, que es equivalente a la del usuario ID de Google. Si no proporciona un login_hint y el usuario está conectado actualmente, la pantalla de consentimiento incluye una solicitud de aprobación para liberar la dirección de correo electrónico del usuario a su aplicación. (Lea más en login_hint .)
• Utilice el parámetro hd para optimizar el flujo de OpenID Connect para los usuarios de un dominio de G Suite en particular. (Lea más en hd .)

Nota: arriba solo se enumeran los parámetros más utilizados. Para obtener una lista completa, además de más detalles sobre todos los parámetros, consulte Parámetros URI de autenticación .

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=[e-mail]&
 nonce=0394852-3190485-2490358&
 hd=example.com

Los usuarios deben dar su consentimiento si su aplicación solicita información nueva sobre ellos o si su aplicación solicita acceso a la cuenta que no han aprobado previamente.

3. Confirmar el token de estado anti-falsificación

La respuesta se envía al redirect_uri que especificó en la solicitud . Todas las respuestas se devuelven 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, debe confirmar que el state recibido de Google coincide con el token de sesión que creó en el Paso 1 . Esta verificación de ida y vuelta ayuda a garantizar que el usuario, no un script malicioso, esté realizando la solicitud.

El siguiente código demuestra la confirmación de los tokens de sesión que creó en el Paso 1:

PHP

Debe descargar la biblioteca cliente de las API de Google para PHP para usar esta muestra.

// Ensure that there is no request forgery going on, and that the user
// sending us this connect request is the user that was supposed to.
if ($request->get('state') != ($app['session']->get('state'))) {
  return new Response('Invalid state parameter', 401);
}

Java

Debe descargar la biblioteca cliente de las API de Google para Java para usar esta muestra.

// Ensure that there is no request forgery going on, and that the user
// sending us this connect request is the user that was supposed to.
if (!request.queryParams("state").equals(
    request.session().attribute("state"))) {
  response.status(401);
  return GSON.toJson("Invalid state parameter.");
}

Pitón

Debe descargar la biblioteca cliente de las API de Google para que Python use 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. code intercambio para token de acceso y token de identificación

La respuesta incluye un parámetro de code , un código de autorización único que su servidor puede intercambiar por un token de acceso y un token de identificación. Su servidor realiza este intercambio enviando una POST HTTPS POST . La solicitud POST se envía al punto final del token, que debe recuperar del documento de descubrimiento utilizando el valor de metadatos token_endpoint . La siguiente discusión asume que el punto final es https://oauth2.googleapis.com/token . La solicitud debe incluir los siguientes parámetros en el cuerpo de la POST :

Campos
code	El código de autorización que se devuelve de la solicitud inicial .
client_id	El ID de cliente que obtiene del API Console Credentials page, como se describe en Obtener credenciales de OAuth 2.0 .
client_secret	El secreto de cliente que obtiene del API Console Credentials page, como se describe en Obtener credenciales de OAuth 2.0 .
redirect_uri	Un URI de redireccionamiento autorizado para el client_id especificado en API Console Credentials page, como se describe en Establecer un URI de redireccionamiento .
grant_type	Este campo debe contener un valor de authorization_code , como se define en la especificación 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 exitosa a esta solicitud contiene los siguientes campos en una matriz 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 en segundos.
id_token	Un JWT que contiene información de identidad sobre el usuario firmado digitalmente por Google.
scope	Los alcances de acceso otorgados por el access_token expresados ​​como una lista de cadenas que access_token mayúsculas y minúsculas y delimitadas por espacios.
token_type	Identifica el tipo de token devuelto. 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ó como offline de offline en la solicitud de autenticación . Para obtener más información, consulte Actualizar tokens .

Nota: Existe un límite en la cantidad de tokens por cuenta de usuario de Google, y cualquier solicitud de autenticación por encima de este límite podría invalidar silenciosamente un token de actualización pendiente. Para obtener más información, consulte Caducidad del token .

5. Obtenga información de usuario del token de identificación

Un ID Token es un JWT (JSON Web Token), es decir, un objeto JSON codificado en Base64 firmado criptográficamente. Normalmente, es fundamental que valide un token de identificación antes de usarlo, pero dado que se está comunicando directamente con Google a través de un canal HTTPS sin intermediarios y utiliza su secreto de cliente para autenticarse en Google, puede estar seguro de que el token recibir realmente proviene de Google y es válido. Si su servidor pasa el token de ID a otros componentes de su aplicación, es extremadamente importante que los otros componentes validen el token antes de usarlo.

Dado que la mayoría de las bibliotecas de API combinan la validación con el trabajo de decodificar los valores codificados en base64url y analizar el JSON interno, probablemente terminará validando el token de todos modos a medida que acceda a los reclamos en el token de ID.

Carga útil de un token de identificación

Un token de ID es un objeto JSON que contiene un conjunto de pares de nombre / valor. Aquí hay un ejemplo, formateado 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"
}

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

Afirmar	Previsto	Descripción
aud	siempre	La audiencia a la que está destinado este token de ID. Debe ser uno de los ID de cliente de OAuth 2.0 de su aplicación.
exp	siempre	Tiempo de caducidad a partir del cual no se debe aceptar el token de identificación. Representado en tiempo Unix (segundos enteros).
iat	siempre	La hora en que se emitió el token de identificación. Representado en tiempo Unix (segundos enteros).
iss	siempre	Identificador de emisor del emisor de la respuesta. Siempre https://accounts.google.com o accounts.google.com para los tokens de ID de Google.
sub	siempre	Un identificador para el usuario, único entre todas las cuentas de Google y nunca reutilizado. Una cuenta de Google puede tener varias direcciones de correo electrónico en diferentes momentos, pero el valor sub nunca se cambia. Utilice sub dentro de su aplicación como clave de identificación única para el 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 de access_token en el flujo del servidor, esta reclamación siempre se incluye. Este reclamo se puede utilizar como un mecanismo alternativo para protegerse contra ataques de falsificación de solicitudes entre sitios, pero si sigue el Paso 1 y el Paso 3, no es necesario verificar el token de acceso.
azp		El client_id del presentador autorizado. Este reclamo solo es necesario cuando la parte que solicita el token de ID no es la misma que la audiencia del token de ID. Este puede ser el caso en Google para aplicaciones híbridas donde una aplicación web y una aplicación de Android tienen un client_id OAuth 2.0 diferente pero comparten el mismo proyecto de 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 su uso como clave principal. Se proporciona solo si su alcance incluía el valor del alcance del email .
email_verified		Verdadero si se ha verificado la dirección de correo electrónico del usuario; de lo contrario falso.
family_name		El (los) apellido (s) o apellido (s) del usuario. Puede proporcionarse cuando haya una reclamación de name .
given_name		El (los) nombre (s) de pila o el nombre (s) del usuario. Puede proporcionarse cuando haya una reclamación de name .
hd		El dominio de G Suite alojado del usuario. Se proporciona solo si el usuario pertenece a un dominio alojado.
locale		La configuración regional del usuario, representada por una etiqueta de idioma BCP 47 . Puede proporcionarse cuando haya una reclamación de name .
name		El nombre completo del usuario, en forma visualizable. Puede proporcionarse cuando: El alcance de la solicitud incluía la cadena "perfil" El token de ID se devuelve desde una actualización de token Cuando hay reclamos de name , puede usarlos para actualizar los registros de usuario de su aplicación. Tenga en cuenta que nunca se garantiza que este reclamo esté presente.
nonce		El valor del nonce proporcionado por su aplicación en la solicitud de autenticación. Debe aplicar la protección contra los ataques de reproducción asegurándose de que se presente solo una vez.
picture		La URL de la foto de perfil del usuario. Puede proporcionarse cuando: El alcance de la solicitud incluía la cadena "perfil" El token de ID se devuelve desde una actualización de token Cuando hay reclamos de picture , puede usarlos para actualizar los registros de usuario de su aplicación. Tenga en cuenta que nunca se garantiza que este reclamo esté presente.
profile		La URL de la página de perfil del usuario. Puede proporcionarse cuando: El alcance de la solicitud incluía la cadena "perfil" El token de ID se devuelve desde una actualización de token Cuando hay reclamos de profile , puede usarlos para actualizar los registros de usuario de su aplicación. Tenga en cuenta que nunca se garantiza que este reclamo esté presente.

6. Autenticar al usuario

Después de obtener la información del usuario del token de ID, debe consultar la base de datos de usuarios de su aplicación. Si el usuario ya existe en su base de datos, debe iniciar una sesión de aplicación para ese usuario si la respuesta de la API de Google cumple con todos los requisitos de inicio de sesión.

Si el usuario no existe en su base de datos de usuarios, debe redirigir al usuario a su flujo de registro de nuevos usuarios. Es posible que pueda registrar automáticamente al usuario en función de la información que reciba de Google o, como mínimo, podrá completar muchos de los campos que necesita en su formulario de registro. Además de la información en el token de ID, puede obtener información adicional sobre el perfil de usuario en nuestros puntos finales de perfil de usuario.

Temas avanzados

Las siguientes secciones describen la API de Google OAuth 2.0 con mayor detalle. Esta información está destinada a desarrolladores con requisitos avanzados en materia de 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 su aplicación puede obtener permiso para usar otras API de Google en nombre del usuario (como YouTube, Google Drive, Calendar o Contactos) al mismo tiempo que autentica al usuario. Para hacer esto, incluya los otros alcances que necesita en la solicitud de autenticación que envía a Google. Por ejemplo, para agregar el grupo de edad del usuario a su solicitud de autenticación, pase un parámetro de alcance de openid email https://www.googleapis.com/auth/profile.agerange.read de openid email https://www.googleapis.com/auth/profile.agerange.read . Se solicita al usuario de forma adecuada en la pantalla de consentimiento . El token de acceso que recibe de Google le permite acceder a todas las API relacionadas con los alcances de acceso que solicitó y se le otorgaron.

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

Actualizar tokens

En su solicitud de acceso a la API, puede solicitar que se devuelva un token de actualización durante el intercambio de code . Un token de actualización proporciona a su aplicación acceso continuo a las API de Google mientras el usuario no está presente en su aplicación. Para solicitar un token de actualización, agregue el parámetro access_type a offline en su solicitud de autenticación .

Consideraciones:

• Asegúrese de almacenar el token de actualización de forma segura y permanente, porque solo puede obtener un token de actualización la primera vez que realiza el flujo de intercambio de código.
• Hay límites en la cantidad de tokens de actualización que se emiten: un límite por combinación de cliente / usuario y otro por usuario en todos los clientes. Si su aplicación solicita demasiados tokens de actualización, puede encontrarse con estos límites, en cuyo caso los tokens de actualización más antiguos dejan de funcionar.

Para obtener más información, consulte Actualización de un token de acceso (acceso sin conexión) .

Solicitar un nuevo consentimiento

Puede solicitar al usuario que vuelva a autorizar su aplicación configurando el parámetro de prompt para dar su consent en su solicitud de autenticación . Cuando se incluye prompt=consent , la pantalla de consentimiento se muestra cada vez que su aplicación solicita autorización de alcances de acceso, incluso si todos los alcances se otorgaron previamente a su proyecto de API de Google. Por esta razón, incluya prompt=consent solo cuando sea necesario.

Para obtener más información sobre el parámetro de prompt , consulte la prompt en la tabla de parámetros de URI de autenticación .

Parámetros de URI de autenticación

La siguiente tabla ofrece descripciones más completas de los parámetros aceptados por la API de autenticación OAuth 2.0 de Google.

Parámetro	Requerido	Descripción
client_id	(Requerido)	La cadena de ID de cliente que obtiene del API Console Credentials page, como se describe en Obtener credenciales de OAuth 2.0 .
nonce	(Requerido)	Un valor aleatorio generado por su aplicación que habilita la protección de reproducción.
response_type	(Requerido)	Si el valor es code , inicia un flujo de código de autorización básico , que requiere una POST en el punto final 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 los tokens del identificador de #fragment URI .
redirect_uri	(Requerido)	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 establezca en API Console Credentials page (incluido el esquema HTTP o HTTPS, el caso y el '/' final, si corresponde).
scope	(Requerido)	El parámetro de alcance debe comenzar con el valor openid y luego incluir el valor del profile , el valor del email o ambos. Si el valor del alcance del profile está presente, el token de ID podría incluir (pero no se garantiza que lo haga) las notificaciones del profile predeterminado del usuario. Si el valor del alcance del email está presente, el token de ID incluye email_verified email y email_verified . Además de estos ámbitos específicos de OpenID, su argumento de ámbito también puede incluir otros valores de ámbito. Todos los valores de alcance deben estar separados por espacios. Por ejemplo, si deseaba acceso por archivo a Google Drive de un usuario, su parámetro de alcance podría ser el openid profile email https://www.googleapis.com/auth/drive.file . Para obtener información sobre los alcances disponibles, consulte OAuth 2.0 Scopes para las API de Google o la documentación de la API de Google que le gustaría utilizar.
state	(Opcional, pero muy recomendable)	Una cadena opaca que es de ida y vuelta en el protocolo; es decir, se devuelve como parámetro URI en el flujo básico y en el identificador de #fragment URI en el flujo implícito. El state puede resultar útil para correlacionar solicitudes y respuestas. Debido a que se puede adivinar su redirect_uri , el uso de un valor de state puede aumentar su seguridad de que una conexión entrante es el resultado de una solicitud de autenticación iniciada por su aplicación. Si genera una cadena aleatoria o codifica el hash de algún estado de cliente (por ejemplo, una cookie) en esta variable de state , puede validar la respuesta para asegurarse adicionalmente de 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 están offline online y en online . El efecto está documentado en Offline Access ; 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 de offline .
display	(Opcional)	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 están especificados y aceptados por los servidores de Google, pero no tienen ningún efecto en su comportamiento: page , popup , touch y wap .
hd	(Opcional)	El parámetro hd (dominio alojado) agiliza el proceso de inicio de sesión para las cuentas alojadas en G Suite. Al incluir el dominio del usuario de G Suite (por ejemplo, mycollege.edu ), puede indicar que la IU de selección de cuenta debe optimizarse para las cuentas de ese dominio. Para optimizar las cuentas de G Suite generalmente en lugar de solo un dominio, establezca el valor de un asterisco ( * ): hd=* . No confíe en esta optimización de la interfaz de usuario para controlar quién puede acceder a su aplicación, ya que se pueden modificar las solicitudes del lado del cliente. Asegúrese de validar que el token de ID devuelto tenga un valor de reclamo hd que coincida con lo que espera (por ejemplo, mycolledge.edu ). A diferencia del parámetro de solicitud, el reclamo hd token de ID está contenido en un token de seguridad de Google, por lo que se puede confiar en el valor.
include_granted_scopes	(Opcional)	Si este parámetro se proporciona con el valor true y se otorga la solicitud de autorización, la autorización incluirá cualquier autorización previa otorgada a esta combinación de usuario / aplicación para otros ámbitos; consulte Autorización incremental . Tenga en cuenta que no puede realizar una autorización incremental con el flujo de la aplicación instalada.
login_hint	(Opcional)	Cuando su aplicación sabe qué usuario está intentando autenticar, puede proporcionar este parámetro como una pista para el servidor de autenticación. Pasar esta sugerencia suprime el selector de cuenta y rellena previamente el cuadro de correo electrónico en el formulario de inicio de sesión o selecciona la sesión adecuada (si el usuario está utilizando el inicio de sesión múltiple ), lo que puede ayudarlo a evitar problemas que ocurren si su aplicación inicia sesión en la cuenta de usuario incorrecta. El valor puede ser una dirección de correo electrónico o el sub cadena, que es equivalente a la del usuario ID de Google.
prompt	(Opcional)	Una lista delimitada por espacios de valores de cadena que especifica si el servidor de autorización solicita al usuario la reautenticación y el consentimiento. Los posibles valores son: none El servidor de autorización no muestra ninguna pantalla de autenticación o consentimiento del usuario; devolverá un error si el usuario aún no está autenticado y no ha preconfigurado el consentimiento para los ámbitos solicitados. Puede usar none para verificar la autenticación y / o consentimiento existentes. consent El servidor de autorización solicita al usuario su consentimiento antes de devolver la información al cliente. select_account El servidor de autorización solicita al usuario que seleccione una cuenta de usuario. Esto permite a un usuario que tiene varias cuentas en el servidor de autorización seleccionar entre las múltiples cuentas para las que puede tener sesiones actuales. Si no se especifica ningún valor y el usuario no ha autorizado previamente el acceso, se muestra al usuario una pantalla de consentimiento.

Validación de un token de identificación

Debe validar todos los tokens de identificación en su servidor a menos que sepa que provienen directamente de Google. Por ejemplo, su servidor debe verificar la autenticidad de cualquier token de identificación que reciba de sus aplicaciones cliente.

Las siguientes son situaciones comunes en las que puede enviar tokens de identificación a su servidor:

• Envío de tokens de identificación con solicitudes que deben autenticarse. Los tokens de identificación le indican el usuario en particular que realiza la solicitud y para qué cliente se otorgó ese token de identificación.

Los tokens de identificación son confidenciales y pueden utilizarse incorrectamente si se interceptan. Debe asegurarse de que estos tokens se manejen de forma segura transmitiéndolos solo a través de HTTPS y solo a través de datos POST o dentro de los encabezados de solicitud. Si almacena tokens de identificación en su servidor, también debe almacenarlos de forma segura.

Una cosa que hace que los tokens de identificación sean útiles es el hecho de que puede pasarlos por diferentes componentes de su aplicación. Estos componentes pueden usar un token de identificación como un mecanismo de autenticación ligero que autentica la aplicación y el usuario. Pero antes de que pueda usar la información en el token de ID o confiar en ella como una afirmación de que el usuario se ha autenticado, debe validarla.

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

1. Verifique que el token de identificación esté debidamente firmado por el emisor. 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 Discovery .
2. Verifique que el valor de la reclamación de iss en el token de identificación sea igual a https://accounts.google.com o accounts.google.com .
3. Verifique que el valor del reclamo aud en el token de ID sea igual al ID de cliente de su aplicación.
4. Compruebe que el tiempo de caducidad ( exp reclamación) del token de ID no ha pasado.
5. Si especificaste un valor de parámetro hd en la solicitud, verifica que el token de ID tenga un reclamo hd que coincida con un dominio alojado en G Suite aceptado.

Los pasos 2 a 5 implican solo comparaciones de cadenas y fechas que son bastante sencillas, por lo que no las detallaremos aquí.

El primer paso es más complejo e implica la verificación de firmas criptográficas. Para fines de depuración , puede utilizar el tokeninfo final de tokeninfo de Google para compararlo con el procesamiento local implementado en su servidor o dispositivo. Suponga que el valor de su token de ID es XYZ123 . Luego, eliminaría 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 JWT en su forma de objeto JSON decodificado.

El tokeninfo final de tokeninfo es útil para la depuración, pero para fines de producción, recupere las claves públicas de Google desde el punto final de las claves y realice la validación localmente. Debe recuperar el URI de claves del documento de descubrimiento utilizando el valor de metadatos jwks_uri . Las solicitudes al punto final de depuración pueden ser limitadas o estar sujetas a errores intermitentes.

Dado que Google cambia sus claves públicas con poca frecuencia, puede almacenarlas en caché usando las directivas de caché de la respuesta HTTP y, en la gran mayoría de los casos, realizar la validación local de manera mucho más eficiente que usando el tokeninfo final de tokeninfo . Esta validación requiere recuperar y analizar certificados y realizar las llamadas criptográficas apropiadas para verificar la firma. Afortunadamente, existen bibliotecas bien depuradas disponibles en una amplia variedad de lenguajes para lograr esto (ver jwt.io ).

Obtención de información de perfil de usuario

Para obtener información de perfil adicional sobre el usuario, puede utilizar el token de acceso (que su aplicación recibe durante el flujo de autenticación ) y el estándar OpenID Connect :

1. Para ser compatible con OpenID, debe incluir los valores del alcance del openid profile en su solicitud de autenticación .

   Si desea que se incluya la dirección de correo electrónico del usuario, puede especificar un valor de alcance adicional de email . Para especificar tanto el profile como el email , puede incluir el siguiente parámetro en el URI de su solicitud de autenticación:

   scope=openid%20profile%20email

2. Agregue su token de acceso al encabezado de autorización y realice una solicitud HTTPS GET al punto final de userinfo, que debe recuperar del documento de descubrimiento utilizando 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 Discovery. Los usuarios o sus organizaciones pueden optar por proporcionar o retener ciertos campos, por lo que es posible que no obtenga información para cada campo para sus ámbitos de acceso autorizados.

El documento Discovery

El protocolo OpenID Connect requiere el uso de varios puntos finales para autenticar usuarios y para solicitar recursos, incluidos tokens, información de 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 brindan detalles sobre la configuración del proveedor de OpenID Connect, incluidos los URI de la autorización. , token, revocación, información de usuario y puntos finales de claves públicas. El documento de descubrimiento para el servicio OpenID Connect de Google se puede recuperar en:

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

Para utilizar los servicios OpenID Connect de Google, debe codificar el URI del documento de descubrimiento ( https://accounts.google.com/.well-known/openid-configuration ) en su aplicación. Su aplicación obtiene el documento, aplica reglas de almacenamiento en caché en la respuesta y luego recupera los URI de punto final según sea necesario. Por ejemplo, para autenticar a un usuario, su código recuperaría el valor de metadatos de punto final de authorization_endpoint ( https://accounts.google.com/o/oauth2/v2/auth en el ejemplo siguiente) como el URI base para las solicitudes de autenticación que se envían a Google.

A continuación se muestra un ejemplo de dicho documento; los nombres de los campos son los especificados en OpenID Connect Discovery 1.0 (consulte ese documento para conocer sus significados). Los valores son puramente ilustrativos y pueden cambiar, aunque se han copiado 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"
  ]
}

Es posible que pueda evitar un viaje de ida y vuelta HTTP almacenando en caché los valores del documento de descubrimiento. Se utilizan encabezados de almacenamiento en caché HTTP estándar y deben respetarse.

Bibliotecas cliente

Las siguientes bibliotecas cliente simplifican la implementación de OAuth 2.0 al integrarse con marcos 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 de OAuth 2.0 para Google Web Toolkit
• Controladores de Google Toolbox para Mac OAuth 2.0

Cumplimiento de OpenID Connect

El sistema de autenticación OAuth 2.0 de Google admite las funciones requeridas de la especificación OpenID Connect Core . Cualquier cliente que esté diseñado para trabajar con OpenID Connect debería interoperar con este servicio (con la excepción del objeto de solicitud de OpenID ).