Usar modelo de código

La biblioteca de Google Identity Services permite a los usuarios solicitar un código de autorización a Google mediante un flujo de UX de ventana emergente o redireccionamiento basado en el navegador. Esto inicia un flujo seguro de OAuth 2.0 y genera un token de acceso que se usa para llamar a las APIs de Google en nombre de un usuario.

Resumen del flujo de código de autorización de OAuth 2.0:

• Desde un navegador, con un gesto como hacer clic en un botón, el propietario de la Cuenta de Google solicita un código de autorización a Google.
• Google responde y envía un código de autorización único a una devolución de llamada en tu app web de JavaScript que se ejecuta en el navegador del usuario o invoca directamente tu extremo de código de autorización con un redireccionamiento del navegador.
• Tu plataforma de backend aloja un extremo de código de autorización y recibe el código. Después de la validación, este código se intercambia por tokens de acceso y actualización por usuario mediante una solicitud al extremo de tokens de Google.
• Google valida el código de autorización, confirma que la solicitud se originó en tu plataforma segura, emite tokens de acceso y actualización, y muestra los tokens llamando al extremo de acceso alojado en tu plataforma.
• Tu extremo de acceso recibe los tokens de acceso y actualización, y almacena de forma segura el token de actualización para usarlo más adelante.

Punto clave: En tu servidor de backend, intercambias un código de autorización por tokens de actualización y de acceso mediante una llamada al extremo de tokens de Google.

Requisitos previos

Sigue los pasos que se describen en Configuración para configurar la pantalla de consentimiento de OAuth, obtener un ID de cliente y cargar la biblioteca cliente.

Cómo inicializar un cliente de código

El método google.accounts.oauth2.initCodeClient() inicializa un cliente de código.

Modo de ventana emergente o redireccionamiento

Puedes compartir un código de autorización con el flujo de usuarios del modo Redireccionamiento o Ventana emergente. Con el modo de redireccionamiento, alojas un extremo de autorización de OAuth2 en tu servidor y Google redirecciona el usuario-agente a este extremo, y comparte el código de autenticación como un parámetro de URL. Para el modo Popup, defines un controlador de devolución de llamada de JavaScript, que envía el código de autorización a tu servidor. El modo emergente se puede usar para brindar una experiencia del usuario fluida sin que los visitantes tengan que abandonar tu sitio.

Para inicializar un cliente para lo siguiente:

• Redirecciona el flujo de UX, establece ux_mode en redirect y el valor de redirect_uri en el extremo del código de autorización de tu plataforma. El valor debe coincidir exactamente con uno de los URIs de redireccionamiento autorizados para el cliente de OAuth 2.0 que configuraste en la Consola de la API. También debe cumplir con nuestras reglas de validación de URI de redireccionamiento.

• Flujo de UX emergente, establece ux_mode en popup y el valor de callback en el nombre de la función que usarás para enviar códigos de autorización a tu plataforma.

Punto clave: Para lograr el mejor equilibrio entre usabilidad y seguridad, se recomienda usar el flujo de UX del modo de ventana emergente con el modelo de código de autorización.

Protégete contra los ataques CSRF

Para ayudar a evitar ataques de falsificación de solicitudes entre sitios (CSRF), se emplean técnicas ligeramente diferentes para los flujos de UX de los modos de redireccionamiento y ventana emergente. Para el modo de redireccionamiento, se usa el parámetro state de OAuth 2.0. Consulta RFC6749, sección 10.12, falsificación de solicitudes entre sitios para obtener más información sobre cómo generar y validar el parámetro state. Con el modo Popup, agregas un encabezado HTTP personalizado a tus solicitudes y, luego, en tu servidor, confirmas que coincida con el valor y el origen esperados.

Elige un modo de UX para ver un fragmento de código que muestre el código de autenticación y el manejo de CSRF:

Modo de redireccionamiento

Inicializa un cliente en el que Google redirecciona el navegador del usuario a tu extremo de autenticación y comparte el código de autenticación como un parámetro de URL.

const client = google.accounts.oauth2.initCodeClient({
  client_id: 'YOUR_GOOGLE_CLIENT_ID',
  scope: 'https://www.googleapis.com/auth/calendar.readonly',
  ux_mode: 'redirect',
  redirect_uri: "https://your.domain/code_callback_endpoint",
  state: "YOUR_BINDING_VALUE"
});

Modo de ventana emergente

Inicializa un cliente en el que el navegador del usuario reciba un código de autenticación de Google y lo envíe a tu servidor.

const client = google.accounts.oauth2.initCodeClient({
  client_id: 'YOUR_GOOGLE_CLIENT_ID',
  scope: 'https://www.googleapis.com/auth/calendar.readonly',
  ux_mode: 'popup',
  callback: (response) => {
    const xhr = new XMLHttpRequest();
    xhr.open('POST', code_receiver_uri, true);
    xhr.setRequestHeader('Content-Type', 'application/x-www-form-urlencoded');
    // Set custom header for CRSF
    xhr.setRequestHeader('X-Requested-With', 'XmlHttpRequest');
    xhr.onload = function() {
      console.log('Auth code response: ' + xhr.responseText);
    };
    xhr.send('code=' + response.code);
  },
});

Activa el flujo de código de OAuth 2.0

Llama al método requestCode() del cliente de código para activar el flujo de usuarios:

<button onclick="client.requestCode();">Authorize with Google</button>

Esto requerirá que el usuario acceda a una Cuenta de Google y otorgue su consentimiento para compartir permisos individuales antes de que se devuelva un código de autorización a tu extremo de redireccionamiento o a tu controlador de devolución de llamada.

Manejo del código de autenticación

Google genera un código de autorización único por usuario que recibes y verificas en tu servidor de backend.

En el modo Popup, el controlador que especifica callback, que se ejecuta en el navegador del usuario, retransmite el código de autorización a un extremo alojado por tu plataforma.

En el modo de redireccionamiento, se envía una solicitud GET al extremo que especifica redirect_url, que comparte el código de autorización en el parámetro code de la URL. Para recibir el código de autorización, haz lo siguiente:

• Crea un nuevo extremo de autorización si no tienes una implementación existente.

• Actualiza tu extremo existente para aceptar solicitudes GET y parámetros de URL. Anteriormente, se usaba una solicitud PUT con el valor del código de autorización en la carga útil.

Extremo de autorización

Tu extremo de código de autorización debe controlar las solicitudes de GET con estos parámetros de cadena de consulta de URL:

Nombre	Valor
authuser	Solicitud de autenticación de acceso del usuario
código	Un código de autorización de OAuth2 generado por Google
hd	El dominio alojado de la cuenta de usuario
mensaje	Diálogo de consentimiento del usuario
alcance	Es una lista separada por espacios de uno o más permisos de OAuth2 que se autorizarán.
state	Variable de estado de CRSF

Ejemplo de solicitud GET con parámetros de URL a un extremo llamado auth-code y alojado por example.com:

Request URL: https://www.example.com/auth-code?state=42a7bd822fe32cc56&code=4/0AX4XfWiAvnXLqxlckFUVao8j0zvZUJ06AMgr-n0vSPotHWcn9p-zHCjqwr47KHS_vDvu8w&scope=email%20profile%20https://www.googleapis.com/auth/calendar.readonly%20https://www.googleapis.com/auth/photoslibrary.readonly%20https://www.googleapis.com/auth/contacts.readonly%20openid%20https://www.googleapis.com/auth/userinfo.email%20https://www.googleapis.com/auth/userinfo.profile&authuser=0&hd=example.com&prompt=consent

Cuando el flujo de código de autorización se inicia con bibliotecas de JavaScript anteriores o con llamadas directas a extremos de Google OAuth 2.0, se usa una solicitud POST.

Ejemplo de solicitud POST que contiene el código de autorización como carga útil en el cuerpo de la solicitud HTTP:

Request URL: https://www.example.com/auth-code
Request Payload: 4/0AX4XfWhll-BMV82wi4YwbrSaTPaRpUGpKqJ4zBxQldU\_70cnIdh-GJOBZlyHU3MNcz4qaw

Importante: Anteriormente, se usaba POST para las solicitudes. Actualiza tu controlador para que acepte solicitudes de GET y POST, o bien considera alojar dos extremos diferentes si planeas seguir usando bibliotecas de JS anteriores o llamar directamente a los extremos de OAuth 2.0 de Google mientras usas la biblioteca de Google Identity Services.

Validar la solicitud

En tu servidor, haz lo siguiente para evitar ataques CSRF.

Verifica el valor del parámetro state para el modo de redireccionamiento.

Confirma que el encabezado X-Requested-With: XmlHttpRequest esté configurado para el modo de ventana emergente.

Luego, debes continuar con la obtención de tokens de actualización y acceso de Google solo si primero verificaste correctamente la solicitud de código de autenticación.

Obtén tokens de acceso y actualización

Después de que tu plataforma de backend reciba un código de autorización de Google y verifique la solicitud, usa el código de autorización para obtener tokens de acceso y actualización de Google para realizar llamadas a la API.

Sigue las instrucciones que comienzan en el Paso 5: Intercambia el código de autorización por tokens de actualización y acceso de la guía Usa OAuth 2.0 para aplicaciones de servidor web.

Administrar tokens

Tu plataforma almacena tokens de actualización de forma segura. Borra los tokens de actualización almacenados cuando se quitan las cuentas de usuario o cuando google.accounts.oauth2.revoke revoca el consentimiento del usuario, o bien directamente desde https://myaccount.google.com/permissions.

De manera opcional, puedes considerar la RISC para proteger las cuentas de usuario con la Protección integral de la cuenta.

Por lo general, tu plataforma de backend llamará a las APIs de Google con un token de acceso. Si tu app web también llamará directamente a las APIs de Google desde el navegador del usuario, debes implementar una forma de compartir el token de acceso con tu aplicación web. Hacerlo está fuera del alcance de esta guía. Cuando sigas este enfoque y uses la biblioteca cliente de la API de Google para JavaScript, usa gapi.client.SetToken() para almacenar temporalmente el token de acceso en la memoria del navegador y habilita la biblioteca para que llame a las APIs de Google.