Usar modelo de código

La biblioteca de Google Identity Services permite a los usuarios solicitar un código de autorización de Google con un flujo de UX de redireccionamiento o ventana emergente 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 un 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 bien 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 a través de 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 devuelve 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 su uso posterior.

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

Requisitos previos

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

Inicializa un cliente de Code

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 en 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, compartiendo el código de autorización como un parámetro de URL. En el modo emergente, defines un controlador de devolución de llamada de JavaScript, que envía el código de autorización a tu servidor. El modo de ventana 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:

• Flujo de UX de redireccionamiento, 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 Google Cloud Console. También debe cumplir con las reglas de validación de URI de redireccionamiento.

• Flujo de UX de la ventana 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. El valor de redirect_uri se establece de forma predeterminada en el origen de la página que llama a initCodeClient. Este valor se usa más adelante en el flujo cuando el código de autorización se intercambia por un token de acceso o de actualización. Por ejemplo, https://www.example.com/index.html llama a initCodeClient y el origen https://www.example.com es el valor de redirect_url.

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

Protección contra ataques CSRF

Para ayudar a prevenir 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. En el modo de redireccionamiento, se usa el parámetro state de OAuth 2.0. Consulta la sección 10.12 de RFC6749, Cross-Site Request Forgery, para obtener más información sobre cómo generar y validar el parámetro state. Con el modo emergente, agregas un encabezado HTTP personalizado a tus solicitudes y, luego, confirmas en tu servidor 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 autorización y el control 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 autorización como un parámetro de URL.

const client = google.accounts.oauth2.initCodeClient({
  client_id: 'YOUR_CLIENT_ID',
  scope: 'https://www.googleapis.com/auth/calendar.readonly',
  ux_mode: 'redirect',
  redirect_uri: 'https://oauth2.example.com/code',
  state: 'YOUR_BINDING_VALUE'
});

Punto clave: Un extremo en tu servidor de backend recibe y valida el código de autorización, y lo intercambia por tokens de acceso y actualización.

Modo de ventanas emergentes

Inicializa un cliente en el que el usuario comienza el flujo de autorización en un diálogo emergente. Después de que se otorga el consentimiento, Google devuelve el código de autorización al navegador del usuario a través de una función de devolución de llamada. Una solicitud POST del controlador de devolución de llamada de JS entrega el código de autorización a un extremo en el servidor de backend, donde primero se verifica y, luego, se completa el resto del flujo de OAuth.

const client = google.accounts.oauth2.initCodeClient({
  client_id: 'YOUR_CLIENT_ID',
  scope: 'https://www.googleapis.com/auth/calendar.readonly',
  ux_mode: 'popup',
  callback: (response) => {
    const xhr = new XMLHttpRequest();
    xhr.open('POST', "https://oauth2.example.com/code", 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);
  },
});

Punto clave: Un extremo en tu servidor de backend recibe y valida el código de autorización, y lo intercambia por tokens de acceso y actualización.

Cómo activar 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 dé 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 autorización

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

En el modo emergente, el controlador especificado por 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 especificado por redirect_uri, y se 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 que acepte 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 GET con estos parámetros de cadena de consulta de URL:

Nombre	Valor
authuser	Solicitud de autenticación de acceso del usuario
código	Es un código de autorización de OAuth2 generado por Google.
hd	Es el dominio alojado de la cuenta de usuario.
instrucción	Cuadro de diálogo de consentimiento del usuario
alcance	Lista separada por espacios de uno o más permisos de OAuth2 que se autorizarán
state	Variable de estado del CRSF

Ejemplo de solicitud GET con parámetros de URL a un extremo llamado auth-code y alojado en 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 las bibliotecas de JavaScript anteriores o las llamadas directas a los extremos de Google OAuth 2.0 inician el flujo de código de autorización, 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 más antiguas o llamar directamente a los extremos de Google OAuth 2.0 mientras usas la biblioteca de Google Identity Services.

Validar la solicitud

En tu servidor, haz lo siguiente para evitar ataques de 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 obtener tokens de actualización y acceso de Google solo si primero verificaste correctamente la solicitud de código de autorizació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 a partir del 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.

Nota: Cuando se usa el modo de ventana emergente, el valor de redirect_uri que se usa en el paso 5 y en los posteriores es el origen de la página de llamada. Por ejemplo, https://www.example.com/index.html llama a initCodeClient y el origen https://www.example.com es el valor de redirect_url.

Administrar tokens

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

De manera opcional, puedes considerar el uso de 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. Esto queda 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 permitir que la biblioteca llame a las APIs de Google.