Conectar Firebase Authentication con Auth0 te permite delegar la identidad en Auth0 y, al mismo tiempo, aprovechar las reglas y servicios de Firebase con un custom token. Esta guía te muestra cómo configurar el módulo Admin, generar el token y mapear permisos a claims personalizados desde una API route de Next.js.

¿Cómo configurar Firebase Admin con una service account?

El primer paso es habilitar el acceso del servidor a Firebase usando una llave privada. Esta llave actúa como credencial de tu backend y nunca debe exponerse en repositorios públicos.

¿Dónde se descarga la llave privada de Firebase?

Dentro del proyecto de Firebase, abre Project Settings y entra a la pestaña Service Accounts. Allí verás el botón Generate New Private Key, que descarga un archivo JSON con las credenciales del servidor [00:20].

Una vez descargado, sigue estos pasos para integrarlo de forma segura:

• Mueve el archivo a la carpeta firebase de tu proyecto.
• Renómbralo a service_account_key.json.
• Agrégalo al .gitignore para evitar subirlo al repositorio.
• Verifica que el editor lo muestre opaco, señal de que Git lo está ignorando.

¿Por qué la service account key no debe ir al repositorio? Porque contiene credenciales con permisos de administrador sobre tu proyecto Firebase. Si se filtra, cualquiera podría leer o modificar tu base de datos.

¿Cómo se inicializa firebase-admin en Node.js?

Dentro de la carpeta firebase crea un archivo admin.js e instala la dependencia firebase-admin. La importas como admin y, antes de inicializar, agregas un condicional que verifique si la app ya está lista, porque el proceso es asíncrono y puede generar una race condition [01:30].

Luego cargas el serviceAccountKey con un require desde la misma carpeta y llamas a admin.initializeApp pasándole la credencial y la URL de la base de datos, construida con template literals a partir de serviceAccountKey.projectID seguido de firebaseio.com.

¿Cómo crear un custom token de Firebase desde Auth0?

Con el Admin listo, toca exponer una API route que genere el custom token solo para usuarios autenticados con Auth0. Aquí entran en juego dos utilidades del SDK: withAPIRequired, que protege la ruta, y getSession, que te da acceso al usuario y al access token [03:10].

Dentro de pages/api/firebase importas también getAuth desde firebase-admin/auth, la librería jsonwebtoken para decodificar el access token, y la configuración del admin que acabas de crear.

El flujo dentro del handler queda así:

1. Obtener la sesión con await getSession.
2. Sacar el userID desde session.user.sub, uno de los public claims de OpenID Connect.
3. Decodificar el access token de Auth0 para leer los permissions asociados a los roles.
4. Mapear esos permisos a claims con una utilidad propia llamada mapPermissionsToClaims.
5. Llamar a getAuth().createCustomToken(userID, claims) para emitir el token.
6. Responder con un JSON que contenga firebaseToken y userClaims.

Nombrar la respuesta como firebaseToken en lugar de un genérico token ayuda a que el cliente identifique con claridad de dónde viene cada credencial.

¿Qué es un custom token en Firebase? Es un JWT firmado por tu servidor con firebase-admin que el cliente intercambia para autenticarse en Firebase. Puede llevar claims propios para usarlos en reglas de Firestore.

¿Cómo mapear permisos de Auth0 a claims personalizados?

La función mapPermissionsToClaims traduce los permisos que vienen del access token a valores que tu aplicación entiende. En el ejemplo, los roles de Auth0 incluyen permisos como read:horror-movies y read:thriller-movies, asociados a los roles horror lover y similares [05:40].

La lógica recorre los permisos y construye un array genres:

• Si permissions.includes('read:horror-movies'), agrega 'horror'.
• Si permissions.includes('read:thriller-movies'), agrega 'thriller'.
• Aplica .filter(Boolean) para descartar valores vacíos.
• Retorna un objeto { genres } listo para inyectarse en el custom token.

El nombre del género coincide exactamente con el campo de la colección de películas en Firestore, lo que permite usar estos claims directamente en reglas de seguridad más adelante.

¿Cómo verificar que el token funciona correctamente?

Levanta el proyecto y llama la API route en el navegador. Vas a recibir un JSON con el firebaseToken y los userClaims. Pega el token en un debugger de JWT para confirmar que Firebase lo emitió y que los claims personalizados llegaron como esperabas [07:20].

Un detalle típico que aparece en la práctica: si solo ves un género cuando deberías ver dos, suele ser un typo en el nombre del permiso. Corregirlo y volver a llamar la API debería devolver el array completo con horror y thriller.

Con esto, Firebase Admin queda conectado a Auth0: el ID del usuario y los claims viajan juntos en un custom token que el cliente usará para autenticarse en Firebase. El siguiente paso natural es aprovechar esos claims en reglas de Firestore para autorizar lectura y escritura por género. ¿Ya tienes pensados los roles que vas a usar en tu app? Cuéntame en los comentarios cómo planeas estructurar tus permisos.