Codelab de App Check para la Web

1. Introducción

Última actualización: 23/02/2023

¿Cómo puedes evitar el acceso no autorizado a tus recursos de Firebase?

Puedes usar la Verificación de aplicaciones de Firebase para evitar que los clientes no autorizados accedan a los recursos de tu backend. Para ello, exige que las solicitudes entrantes incluyan una certificación que demuestre que provienen de tu app genuina y bloquea el tráfico que no tenga una certificación adecuada. La Verificación de aplicaciones de Firebase se basa en proveedores de certificación específicos de la plataforma para verificar la autenticidad del cliente. En el caso de las apps web, la Verificación de aplicaciones admite reCAPTCHA v3 y reCAPTCHA Enterprise como proveedores de certificación.

La Verificación de aplicaciones se puede usar para proteger las solicitudes a Cloud Firestore, Realtime Database, Cloud Functions, Firebase Authentication con Identity Platform y en los backends que alojas por tu cuenta.

Qué compilarás

En este codelab, protegerás una aplicación de chat. Para ello, primero agregarás y, luego, aplicarás App Check.

Qué aprenderás

• Cómo supervisar tu backend para detectar accesos no autorizados
• Cómo agregar la aplicación forzosa a Firestore y Cloud Storage
• Cómo ejecutar tu aplicación con un token de depuración para el desarrollo local

Requisitos

• El IDE o editor de texto que prefieras
• El administrador de paquetes npm, que, por lo general, se incluye con Node.js
• Firebase CLI instalada y configurada para trabajar con tu cuenta
• Una terminal o consola
• Un navegador de tu elección, como Chrome
• El código de muestra del codelab (consulta el siguiente paso del codelab para obtener el código)

2. Obtén el código de muestra

Clona el repositorio de GitHub del codelab desde la línea de comandos:

git clone https://github.com/firebase/codelab-friendlychat-web

También tienes la opción de descargar el repositorio como archivo ZIP si no tienes Git instalado.

Cómo importar la app de inicio

Con tu IDE, abre o importa el directorio 📁 appcheck-start del repositorio clonado. Este directorio 📁 appcheck-start contiene el código inicial para el codelab, que será una app web de chat completamente funcional. El directorio 📁 appcheck tendrá el código completo para el codelab.

3. Crea y configura un proyecto de Firebase

Crea un proyecto de Firebase

1. Accede a la consola de Firebase con tu Cuenta de Google.
2. Haz clic en el botón para crear un proyecto nuevo y, luego, ingresa un nombre (por ejemplo, FriendlyChat).
   
3. Haz clic en Continuar.
4. Si se te solicita, revisa y acepta las Condiciones de Firebase y, luego, haz clic en Continuar.
5. (Opcional) Habilita la asistencia de IA en Firebase console (llamada "Gemini en Firebase").
6. Para este codelab, no necesitas Google Analytics, por lo que debes desactivar la opción de Google Analytics.
7. Haz clic en Crear proyecto, espera a que se aprovisione y, luego, haz clic en Continuar.

Actualiza tu plan de precios de Firebase

Para usar Cloud Storage para Firebase, tu proyecto de Firebase debe tener el plan de precios de pago por uso (Blaze), lo que significa que está vinculado a una cuenta de Facturación de Cloud.

• Una cuenta de facturación de Cloud requiere una forma de pago, como una tarjeta de crédito.
• Si es la primera vez que usas Firebase y Google Cloud, verifica si cumples con los requisitos para obtener un crédito de USD 300 y una cuenta de Facturación de Cloud de prueba gratuita.
• Si realizas este codelab como parte de un evento, pregúntale al organizador si hay créditos de Cloud disponibles.

Para actualizar tu proyecto al plan Blaze, sigue estos pasos:

1. En Firebase console, selecciona la opción para actualizar tu plan.
2. Selecciona el plan Blaze. Sigue las instrucciones en pantalla para vincular una cuenta de Facturación de Cloud a tu proyecto.
   Si necesitas crear una cuenta de Facturación de Cloud como parte de esta actualización, es posible que debas volver al flujo de actualización en Firebase console para completar la actualización.

Agrega una app web de Firebase al proyecto

1. Haz clic en el ícono de Web para crear una nueva app web de Firebase.
2. Registra la app con el sobrenombre Friendly Chat y, luego, marca la casilla junto a Also set up Firebase Hosting for this app. Haz clic en Register app.
3. En el siguiente paso, verás un comando para instalar Firebase con npm y un objeto de configuración. Copiarás este objeto más adelante en el codelab, así que, por ahora, presiona Siguiente.

4. Luego, verás una opción para instalar Firebase CLI. Si aún no lo has instalado, hazlo ahora con el comando npm install -g firebase-tools. Luego, haga clic en Next.
5. Luego, verás una opción para acceder a Firebase y realizar la implementación en Firebase Hosting. Accede a Firebase con el comando firebase login y, luego, haz clic en Ir a la consola. Realizarás la implementación en Firebase Hosting en un paso posterior.

Configura los productos de Firebase

La aplicación que compilaremos usa productos de Firebase que están disponibles para aplicaciones web:

• Firebase Authentication para permitir que los usuarios accedan a tu app con facilidad
• Cloud Firestore para guardar datos estructurados en la nube y recibir notificaciones al instante cuando se modifiquen los datos
• Cloud Storage para Firebase para guardar archivos en la nube
• Firebase Hosting para alojar y entregar tus recursos
• Firebase Cloud Messaging para enviar notificaciones push y mostrar notificaciones emergentes del navegador
• Firebase Performance Monitoring para recopilar datos de rendimiento del usuario de tu app

Algunos de estos productos necesitan una configuración especial o deben habilitarse a través de Firebase console.

Habilita el Acceso con Google para Firebase Authentication

Para permitir que los usuarios accedan a la aplicación web con sus Cuentas de Google, usaremos el método de acceso con Google.

Deberás habilitar el Acceso con Google:

1. En Firebase console, busca la sección Compilación en el panel izquierdo.
2. Haz clic en Authentication, en Get Started si corresponde y, luego, en la pestaña Sign-in method (o haz clic aquí para ir directamente allí).
3. Habilita el proveedor de acceso con Google
4. Establece el nombre público de tu app como Friendly Chat y elige un correo electrónico de asistencia del proyecto en el menú desplegable.
5. Haga clic en Guardar.

Configura Cloud Firestore

La app web usa Cloud Firestore para guardar mensajes de chat y recibir mensajes nuevos.

Sigue estos pasos para configurar Cloud Firestore en tu proyecto de Firebase:

1. En el panel izquierdo de Firebase console, expande Compilación y, luego, selecciona Base de datos de Firestore.
2. Haz clic en Crear base de datos.
3. Deja el ID de la base de datos establecido en (default).
4. Selecciona una ubicación para tu base de datos y, luego, haz clic en Siguiente.
   Para una app real, debes elegir una ubicación cercana a tus usuarios.
5. Haz clic en Comenzar en modo de prueba. Lee la renuncia de responsabilidad sobre las reglas de seguridad.
   Más adelante en este codelab, agregarás reglas de seguridad para proteger tus datos. No distribuyas ni expongas una app de forma pública sin agregar reglas de seguridad para tu base de datos.
6. Haz clic en Crear.

Configura Cloud Storage para Firebase

La app web utiliza Cloud Storage para Firebase para almacenar, subir y compartir fotos.

Sigue estos pasos para configurar Cloud Storage para Firebase en tu proyecto de Firebase:

1. En el panel izquierdo de Firebase console, expande Compilación y, luego, selecciona Storage.
2. Haz clic en Comenzar.
3. Selecciona una ubicación para tu bucket de Storage predeterminado.
   Los buckets en US-WEST1, US-CENTRAL1 y US-EAST1 pueden aprovechar el nivel “Siempre gratuito” para Google Cloud Storage. Los buckets de todas las demás ubicaciones siguen los precios y el uso de Google Cloud Storage.
4. Haz clic en Comenzar en modo de prueba. Lee la renuncia de responsabilidad sobre las reglas de seguridad.
   Más adelante en este codelab, agregarás reglas de seguridad para proteger tus datos. No distribuyas ni expongas una app de forma pública sin agregar reglas de seguridad para tu bucket de Storage.
5. Haz clic en Crear.

4. Configura Firebase

Desde el directorio appcheck-start, llama al siguiente comando:

firebase use --add

Cuando se te solicite, selecciona tu ID del proyecto y, luego, asígnale un alias a tu proyecto de Firebase. Para este proyecto, puedes asignar el alias default. A continuación, deberás configurar tu proyecto local para que funcione con Firebase.

1. Ve a la configuración del proyecto en Firebase console.
2. En la tarjeta "Tus apps", selecciona el apodo de la app para la que necesitas un objeto de configuración.
3. Selecciona Config en el panel de fragmentos del SDK de Firebase.
4. Copia el fragmento del objeto de configuración y, luego, agrégalo a appcheck-start/hosting/src/firebase-config.js. En el resto del codelab, se supone que la variable se llama config.

firebase-config.js

const config = {
  apiKey: "API_KEY",
  authDomain: "PROJECT_ID.firebaseapp.com",
  databaseURL: "https://PROJECT_ID.firebaseio.com",
  projectId: "PROJECT_ID",
  storageBucket: "PROJECT_ID.firebasestorage.app",
  messagingSenderId: "SENDER_ID",
  appId: "APP_ID",
  measurementId: "G-MEASUREMENT_ID",
};

Desde el mismo directorio appcheck-start, llama a:

firebase experiments:enable webframeworks

Esto habilita la compatibilidad con el framework web con el que se compiló este proyecto.

Ya deberíamos tener todo listo para ejecutar tu proyecto y probar que el proyecto predeterminado funcione.

5. Prueba la app sin la Verificación de aplicaciones

Ahora que configuraste tu app y el SDK, intenta usar la app como se diseñó originalmente. Primero, instala todas las dependencias. Desde la terminal, navega al directorio appcheck-start/hosting. Mientras te encuentres dentro de ese directorio, ejecuta npm install. Esto recupera todas las dependencias para que funcione tu proyecto. Para iniciar la app en su estado actual, puedes ejecutar firebase serve. La app te pedirá que accedas con una Cuenta de Google. Hazlo y, luego, intenta publicar algunos mensajes de chat y algunas fotos en el chat.

Ahora que lo probaste de forma local, es hora de verlo en producción. Ejecuta firebase deploy para implementar la aplicación web en la Web. Esta parte es un paso fundamental para demostrar cómo funciona la Verificación de aplicaciones en el mundo real, ya que requiere que se configure un dominio para el proveedor de certificación de reCAPTCHA Enterprise.

Esperamos que estés experimentando la capacidad predeterminada que proporciona la app. Publicar mensajes de chat y todo lo demás que solo se debe hacer desde una app como esta La desventaja del estado actual es que cualquier persona que tenga la configuración de tu app del paso anterior puede acceder a los recursos de backend. Aun así, deben cumplir con las reglas de seguridad que establecen tus sistemas de Firestore y Cloud Storage, pero, de lo contrario, pueden consultar, almacenar y acceder a los datos que se almacenan allí.

En los siguientes pasos, harás lo siguiente:

• Registrar para la Verificación de aplicaciones
• Valida la aplicación
• Comienza a aplicar las reglas

6. Activa la Verificación de aplicaciones y su aplicación forzosa

Comencemos por obtener una clave de reCAPTCHA Enterprise para tu proyecto y agregarla a la Verificación de aplicaciones. Para comenzar, visita la sección reCAPTCHA Enterprise de la consola de Google Cloud. Selecciona tu proyecto y, luego, se te solicitará que habilites la API de reCAPTCHA Enterprise. Habilita la API y espera unos minutos a que finalice el proceso. Luego, haz clic en Crear clave junto a Claves empresariales. Luego, en esta sección, especifica un nombre visible y selecciona una clave de tipo Sitio web. Debes especificar los dominios en los que se aloja tu app. Como planeas alojar esto en Firebase Hosting, usa el nombre de alojamiento predeterminado, que suele ser ${YOUR_PROJECT_ID}.web.app. Puedes encontrar tu dominio de Hosting en la sección Hosting de Firebase console. Después de completar esta información, presiona Listo y Crear clave.

Una vez que se complete, verás un ID en la parte superior de la página Detalles de la clave.

Copia este ID en el portapapeles. Esta es la clave que usas para App Check. A continuación, visita la sección Verificación de aplicaciones de Firebase console y haz clic en Comenzar. Luego, haz clic en Registrar y, luego, en reCAPTCHA Enterprise, y coloca el ID copiado en el cuadro de texto de la clave de sitio de reCAPTCHA Enterprise. Deja el resto de los parámetros de configuración con sus valores predeterminados. Tu página de App Check debería verse de la siguiente manera:

Solicitudes no verificadas y no aplicadas

Ahora que tienes una clave registrada en Firebase console, vuelve a ejecutar tu sitio en el navegador con firebase serve. Aquí tienes la app web que se ejecuta de forma local y puedes comenzar a realizar solicitudes al backend de Firebase nuevamente. A medida que las solicitudes se dirigen al backend de Firebase, la Verificación de aplicaciones las supervisa, pero no las aplica. Si quieres ver el estado de las solicitudes que se envían, puedes visitar la sección Cloud Firestore en la pestaña APIs de la página App Check en Firebase console. Como aún no configuraste el cliente para que use App Check, deberías ver algo similar a lo siguiente:

El backend recibe el 100% de solicitudes no verificadas. Esta pantalla es útil, ya que muestra que casi todas las solicitudes de clientes provienen de clientes que no tienen integrada la Verificación de aplicaciones.

Este panel puede indicar varias cosas. Lo primero que puede indicar es si todas tus apps cliente ejecutan la versión más reciente de tu cliente. Si es así, puedes aplicar la Verificación de aplicaciones de forma segura sin preocuparte por desactivar el acceso para un cliente genuino de tu aplicación. Otra cosa que esto puede indicarte es cuántos intentos de acceder a tu backend se realizaron sin provenir de tu app. Es posible que se trate de usuarios que consultan tu backend directamente sin que lo sepas. Como puedes ver que las solicitudes no se verifican, es hora de ver qué sucedería con los usuarios que podrían tener una solicitud no verificada a tu backend antes de que pases a verificar sus solicitudes.

Solicitudes no verificadas y aplicadas

Presiona el botón Aplicar en la pantalla anterior y, luego, vuelve a presionarlo si se te solicita.

Esto comenzará a aplicar la Verificación de aplicaciones, que ahora bloqueará las solicitudes a tus servicios de backend que no se verifiquen a través del proveedor de certificación que elijas (en este caso, reCAPTCHA Enterprise). Regresa a la app web en ejecución, que debería estar ejecutándose en http://localhost:5000. Cuando actualizas la página y tratas de obtener datos de la base de datos, no sucede nada. Si abres la consola de Chrome para leer los errores, deberías ver algo similar a lo siguiente:

Uncaught Error in snapshot listener: FirebaseError: [code=permission-denied]: Missing or insufficient permissions.

Esto significa que la Verificación de aplicaciones bloqueó las solicitudes que no pasaron un token de certificación válido en sus solicitudes a tus recursos de Firebase. Por el momento, puedes desactivar la aplicación de la Verificación de aplicaciones. En la siguiente sección, examinarás cómo agregar la Verificación de aplicaciones de reCAPTCHA Enterprise al ejemplo de Friendly Chat.

7. Agrega la clave de reCAPTCHA Enterprise al sitio

Agregaremos la clave empresarial a tu aplicación. Primero, abre hosting/src/firebase-config.js y agrega tu clave de reCAPTCHA Enterprise al siguiente fragmento de código:

const reCAPTCHAEnterpriseKey = {
  // Replace with your recaptcha enterprise site key
  key: "Replace with your recaptcha enterprise site key"
};

Una vez que se complete, abre hosting/src/index.js y, en la línea 51, agregarás una importación de firebase-config.js para recuperar tu clave de reCAPTCHA y también importarás la biblioteca de App Check para que puedas trabajar con el proveedor de reCAPTCHA Enterprise.

// add from here
 import {
   initializeAppCheck,
   ReCaptchaEnterpriseProvider,
 } from 'firebase/app-check';
// to here

// replace this line
import { getFirebaseConfig } from './firebase-config.js';
// with this line
import { getFirebaseConfig, getReCaptchaKey } from './firebase-config.js';

Luego, en la siguiente línea, crearás una función para configurar la Verificación de aplicaciones. Primero, la función verificará si te encuentras en un entorno de desarrollo y, si es así, imprimirá un token de depuración que puedes usar para el desarrollo local.

import { getFirebaseConfig, getReCaptchaKey } from './firebase-config.js';
// add from here
 function setupAppCheck(app) {
   if(import.meta.env.MODE === 'development') {
     self.FIREBASE_APPCHECK_DEBUG_TOKEN = true;
   }
 }
// to here

Ahora es momento de inicializar la Verificación de aplicaciones para que funcione con el proveedor seleccionado, que en este caso es reCAPTCHA Enterprise. Luego, también querrás actualizar automáticamente tu token de App Check en segundo plano, lo que evitará cualquier tipo de demora cuando el usuario interactúe con tu servicio en caso de que su token de App Check haya quedado obsoleto.

function setupAppCheck(app) {
   if(import.meta.env.MODE === 'development') {
     self.FIREBASE_APPCHECK_DEBUG_TOKEN = true;
   }
// add from here
   // Create a ReCaptchaEnterpriseProvider instance using your reCAPTCHA Enterprise
   // site key and pass it to initializeAppCheck().
   initializeAppCheck(app, {
     provider: new ReCaptchaEnterpriseProvider(getReCaptchaKey()),
     isTokenAutoRefreshEnabled: true // Set to true to allow auto-refresh.
   });
// to here
 }

Por último, una vez que te asegures de que la app se inicializó, deberás llamar a la función setupAppCheck que acabas de crear. En la parte inferior del archivo hosting/src/index.js, agrega la llamada al método que agregaste recientemente.

const firebaseApp = initializeApp(getFirebaseConfig());
// add from here
setupAppCheck(firebaseApp);
// to here
getPerformance();
initFirebaseAuth();
loadMessages();

Realiza pruebas de forma local primero

Primero, prueba tu aplicación de forma local. Si aún no publicas la aplicación de forma local, ejecuta firebase serve. Deberías observar que la aplicación aún no se carga de forma local. Esto se debe a que solo registraste tu dominio de Firebase con el proveedor de certificación de reCAPTCHA y no con el dominio de localhost. Nunca debes registrar localhost como un dominio aprobado, ya que esto permite que los usuarios accedan a tus back-ends restringidos desde una aplicación que se ejecuta de forma local en su máquina. En cambio, como estableciste self.FIREBASE_APPCHECK_DEBUG_TOKEN = true, deberías buscar en la consola de JavaScript una línea similar a la siguiente:

App Check debug token: 55183c20-de61-4438-85e6-8065789265be. You will need to add it to your app's App Check settings in the Firebase console for it to work.

Deberás tomar el token de depuración proporcionado (en el ejemplo, es 55183c20-de61-4438-85e6-8065789265be) y conectarlo a la configuración de Verificación de aplicaciones en el menú de desbordamiento de tu app.

Asigna al token un nombre único que puedas recordar y haz clic en Guardar. Esta opción te permite usar un token generado por el cliente con tu app, lo que es una alternativa más segura que generar un token de depuración y, luego, incorporarlo a tu aplicación. Si se incorpora un token en la app, es posible que se distribuya accidentalmente a los usuarios finales, y estos podrían aprovecharlo para eludir tus verificaciones. Si deseas distribuir un token de depuración, por ejemplo, en un entorno de CI, lee esta documentación para obtener más información sobre cómo distribuirlo.

Una vez que registres el token de depuración en Firebase console, podrás volver a habilitar la aplicación de App Check y probar que el contenido de la app se cargue de forma local llamando a firebase serve desde la terminal. Deberías ver que los datos ingresados anteriormente se muestran en la versión local de la aplicación web. Deberías seguir viendo el mensaje con el token de depuración impreso en la consola.

Probar en producción

Una vez que te asegures de que App Check funciona de forma local, implementa la aplicación web en producción. Desde tu terminal, vuelve a llamar a firebase deploy y vuelve a cargar la página. Esto empaquetará tu aplicación web para que se ejecute en Firebase Hosting. Una vez que tu aplicación esté alojada en Firebase Hosting, intenta visitarla en ${YOUR_PROJECT_ID}.web.app. Puedes abrir la consola de JavaScript y ya no deberías ver el token de depuración impreso allí, y deberías ver que se cargan los chats en tu proyecto. Además, después de interactuar con la aplicación durante unos minutos, puedes visitar la sección de App Check de Firebase console y validar que todas las solicitudes a tu aplicación se hayan verificado.

8. ¡Felicitaciones!

¡Felicitaciones! Agregaste correctamente la Verificación de aplicaciones de Firebase a una aplicación web.

Configuraste Firebase console para controlar un token de reCAPTCHA Enterprise para entornos de producción y hasta configuraste tokens de depuración para el desarrollo local. Esto garantiza que tus apps aún puedan acceder a los recursos de Firebase desde clientes aprobados y evita que se produzcan actividades fraudulentas dentro de tu aplicación.

Próximos pasos

Consulta la siguiente documentación para agregar la Verificación de aplicaciones de Firebase a los siguientes elementos:

• Habilita la aplicación forzosa en Cloud Functions
• Verifica los tokens de la Verificación de aplicaciones en backends personalizados

Documentos de referencia

• Comienza a usar la Verificación de aplicaciones con reCAPTCHA Enterprise en apps web
• Usar el proveedor de depuración en apps web