Usar modelo de código

La biblioteca de Google Identity Services permite que los usuarios soliciten un código de autorización a Google con un flujo de UX de ventana emergente o de 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 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 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, tu plataforma intercambia este código por usuario por tokens de acceso y actualización con una solicitud al extremo de token 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 los muestra 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.

Importante: 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 código

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

Modo de redireccionamiento o de ventana emergente

Puedes elegir compartir un código de autenticación con el flujo de usuario 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 autenticación como un parámetro de URL. Para el modo de ventana emergente, defines un controlador de devolución de llamada de JavaScript, que envía el código de autorización a tu servidor. Puedes usar el modo de ventana emergente para proporcionar una experiencia de 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 de 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 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 predeterminado de redirect_uri es el origen de la página que llama a initCodeClient. El flujo usa este valor más adelante cuando intercambias el código de autenticación 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.

Importante: Para obtener el mejor equilibrio entre usabilidad y seguridad, te recomendamos que uses el flujo de UX en modo de ventana emergente con el modelo de código de autorización.

Protégete contra ataques de CSRF

Los flujos de UX en modo de redireccionamiento y de ventana emergente usan técnicas ligeramente diferentes para ayudar a prevenir ataques de falsificación de solicitudes entre sitios (CSRF). Para el modo de redireccionamiento, usa el parámetro state de OAuth 2.0. Consulta la sección RFC6749 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 de ventana emergente, 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, compartiendo el código de autenticació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'
});

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

Modo de ventanas emergentes

Inicializa un cliente en el que el usuario inicia el flujo de autorización en un cuadro de diálogo emergente. Después del consentimiento, Google muestra el código de autorización al navegador del usuario con 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 autenticación a un extremo en el servidor de backend, donde primero lo verificas y, luego, completas 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);
  },
});

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

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 usuario:

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

Esto requerirá que el usuario acceda a una Cuenta de Google y acepte compartir permisos individuales antes de mostrar 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.

Para el modo de ventana 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 en tu plataforma.

Para el modo de redireccionamiento, Google envía una solicitud GET al extremo especificado por redirect_uri, compartiendo 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 extremo de autorización nuevo si no tienes una implementación existente.

• Actualiza tu extremo existente para aceptar solicitudes GET y parámetros de URL. Anteriormente, Google enviaba 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	Un código de autorización de OAuth2 generado por Google
hd	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 de CRSF

Según RFC 6749, los clientes DEBEN ignorar los parámetros de respuesta no reconocidos, independientemente de si aparecen en la tabla anterior.

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 inicias el flujo de código de autorización con bibliotecas de JavaScript anteriores o realizando llamadas directas a los extremos de Google OAuth 2.0, Google envía una solicitud POST.

Ejemplo de solicitud POST que contiene el código de autorización como una 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 aceptar solicitudes GET y POST, o considera alojar dos extremos diferentes si planeas seguir usando bibliotecas JS más antiguas o llamar directamente a los extremos de Google OAuth 2.0 mientras usas la biblioteca de Servicios de identidad de Google.

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é presente 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 autenticació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.

Nota: Cuando usas el modo de ventana emergente, el valor redirect_uri que usas en el paso 5 y versiones posteriores es el origen de la página que llama. 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 quitas cuentas de usuario o cuando un usuario revoca el consentimiento con google.accounts.oauth2.revoke o directamente desde https://myaccount.google.com/permissions.

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

Por lo general, tu plataforma de backend llamará a las APIs de Google con un token de acceso. Si tu app web también llama 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 no está dentro del alcance de esta guía. Cuando sigues este enfoque y usas 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.