Cómo añadir control de acceso basado en roles de Auth0 a una Webflow Cloud App

Webflow Cloud se ejecuta en Cloudflare Workers, un entorno de aislamiento V8 que no expone toda la superficie de la API de Node.js. Esto significa que algunas bibliotecas de autenticación creadas en torno a módulos criptográficos específicos de Node.js no funcionarán directamente.

La biblioteca jose está diseñada explícitamente para entornos de ejecución en el borde (edge): Cloudflare Workers, Deno y Bun. El SDK oficial de Next.js de Auth0 la utiliza internamente. El enfoque que presentamos aquí se basa directamente en eso.

En esta guía, crearemos una aplicación de Webflow Cloud con tres zonas protegidas: una página de inicio pública, un panel de usuario y un panel de administración. Los visitantes que no hayan iniciado sesión verán la página de inicio. Los usuarios registrados con el rol member accederán al panel de usuario. Solo los usuarios con el rol admin accederán al panel de administración.

¿Qué necesitas para añadir el RBAC de Auth0 a una aplicación de Webflow Cloud?

Necesitas un inquilino (tenant) de Auth0, una aplicación de Webflow Cloud y un paquete npm. Auth0 se encarga de la interfaz de autenticación y la emisión de tokens. Tu aplicación en la nube se encarga de la verificación del JWT y de aplicar los roles.

Un solo paquete, jose, cubre la verificación de JWT, y la función integrada de la plataforma fetch cubre el intercambio de tokens de Auth0. No se necesita nada más aparte de las dependencias de tu framework. Sin bibliotecas de sesión ni abstracciones de adaptadores.

Estos son los requisitos previos específicos:

• Una cuenta de Auth0: el plan gratuito admite hasta 25 000 usuarios activos mensuales con conexiones sociales ilimitadas, lo cual cubre el desarrollo y la mayoría de las aplicaciones pequeñas en producción.
• Unaaplicación de Webflow Cloud: ejecuta webflow cloud init -f nextjs para crear la estructura del proyecto. Autentícate cuando se te solicite, o ejecuta webflow auth login de antemano.
• El paquete josepara la verificación de JWT: npm install jose
• Node.js 22.13.0 o superior de forma local, el requisito mínimo para Webflow CLI 2.0

El flujo completo: tu sitio de Webflow envía a los usuarios al controlador /api/auth/login de la aplicación en la nube, que redirige al inicio de sesión universal de Auth0. Tras la autenticación, Auth0 redirige de vuelta a /api/auth/callback, donde intercambias el código de autorización por tokens y guardas el token de ID en una cookie.

Cada solicitud posterior pasa por un middleware que verifica el token y extrae los roles del usuario.

Una vez que tengas los requisitos previos, puedes continuar con la configuración.

5 pasos para configurar el RBAC de Auth0 en tu aplicación de Webflow Cloud

Auth0 se encarga de la interfaz de autenticación, la emisión de tokens y el almacenamiento de las asignaciones de roles. Tu aplicación de Webflow Cloud gestiona la verificación y el cumplimiento. Los cinco pasos construyen cada pieza en orden: primero la configuración de Auth0 y, después, el código de la aplicación que la utiliza.

1. Configurar Auth0 (aplicación, RBAC, roles y acción posterior al inicio de sesión)

Cuatro cosas que debes configurar en el Panel de Auth0 antes de tocar una sola línea de código.

Crea la aplicación. En el Panel de Auth0, ve a Applications → Applications → Create Application. Elige Regular Web Applications, no SPA. Se trata de una aplicación del lado del servidor. Copia el Domain, el Client ID y el Client Secret desde la pestaña Settings. Necesitarás los tres.

En Application URIs, configura:

• Allowed Callback URLs: http://localhost:3000/app/api/auth/callback, https://your-production-domain.com/app/api/auth/callback
• Allowed Logout URLs: http://localhost:3000, https://your-production-domain.com

Nota sobre el interruptor RBAC. Auth0 tiene un interruptor nativo de RBAC (en Dashboard > Applications > APIs > tu API > Settings > RBAC Settings) que controla si los permisos del sistema de roles de Auth0 aparecen en el claim de alcance estándar de los tokens de acceso. Esta guía, en cambio, inyecta los roles en un claim personalizado dentro del token de ID mediante una acción Post-Login; un patrón que funciona sin configurar una API de Auth0 por separado y que no depende del interruptor RBAC.

Crea los roles. Ve a User Management → Roles → Create Role. Crea dos roles: member y admin. Asigna usuarios a los roles desde la pestaña Users en la página de cada rol, o desde la pestaña Roles del usuario individual en User Management → Users.

Añadir la acción Post-Login

Añade la acción Post-Login para inyectar los roles en el JWT. Auth0 no incluye datos de roles en los tokens por defecto. Debes añadirlos mediante una acción. Ve a Actions → Library y selecciona Create Action → Build from scratch. Ponle de nombre Add Roles to Token y elige el disparador Login / Post Login.

Pega este código:

exports.onExecutePostLogin = async (event, api) => {
  const namespace = 'https://webflow-app.io/claims';
  const roles = event.authorization?.roles ?? [];

  // Add roles to the ID token (used by the app to check role)
  api.idToken.setCustomClaim(`${namespace}/roles`, roles);

  // Add roles to the access token (if you're also protecting APIs)
  api.accessToken.setCustomClaim(`${namespace}/roles`, roles);
};

Despliega la acción, luego abre Actions → Flows → Login, arrástrala al flujo entre Start y Complete, y haz clic en Apply.

¿Por qué un espacio de nombres? Auth0 requiere que los claims personalizados utilicen un espacio de nombres con formato URI para evitar colisiones con los nombres de claims estándar de JWT. Usa cualquier URL válida que controles o que coincida con el dominio de tu aplicación.

Punto de control: Inicia sesión como un usuario de prueba asignado al rol admin, decodifica el token de ID en jwt.io y confirma que ves https://webflow-app.io/claims/roles: ["admin"] en el payload.

2. Añade las variables de entorno de Auth0 a Webflow Cloud

Tu aplicación en la nube necesita cinco valores de Auth0. Añádelos todos a tu .env.local para el desarrollo local y al panel de entorno de Webflow Cloud para producción.

Así es como se ve:

# .env.local
AUTH0_DOMAIN=your-tenant.auth0.com
AUTH0_CLIENT_ID=your_client_id
AUTH0_CLIENT_SECRET=your_client_secret
AUTH0_CALLBACK_URL=http://localhost:3000/app/api/auth/callback
APP_BASE_URL=http://localhost:3000

En la configuración de tu sitio Webflow, abre Webflow Cloud, selecciona tu entorno y añade cada variable en Environment Variables. Ten en cuenta que APP_BASE_URL es solo el origen, sin ruta de montaje. Webflow Cloud sirve tu aplicación desde una ruta de montaje como /app, esa ruta debe reflejarse en los campos basePath y assetPrefix de next.config.ts, y Next.js no la antepone a los destinos de redirección que tú mismo construyas. Por eso el código de abajo mantiene la ruta de montaje en su propia constante y la antepone a cada redirección dentro de la aplicación. Los patrones de coincidencia son la excepción, ya que se comparan después de eliminar la ruta de montaje.

Para producción, actualiza AUTH0_CALLBACK_URL y APP_BASE_URL a tu dominio desplegado.

AUTH0_CLIENT_SECRET es información confidencial. Autentica tu servidor ante el endpoint de tokens de Auth0. Nunca la expongas en el código del lado del cliente ni la incluyas en tu historial de git.

Punto de control: Ejecuta next dev localmente y confirma que process.env.AUTH0_DOMAIN se resuelve como el dominio de tu tenant. Si aparece como undefined, tu archivo .env.local no se está cargando. Comprueba el nombre del archivo y el directorio de trabajo.

3. Crea los controladores de ruta de inicio de sesión, callback y cierre de sesión

Tres controladores de ruta gestionan todo el flujo OAuth 2.0 de Auth0.

Créalos en:

• app/api/auth/login/route.ts: redirige al inicio de sesión universal de Auth0
• app/api/auth/callback/route.ts: intercambia el código de autorización por tokens y almacena la sesión
• app/api/auth/logout/route.ts: borra la cookie de sesión

Cada controlador es minimalista por diseño. La ruta de inicio de sesión redirige. El callback intercambia un código por tokens, y la ruta de cierre de sesión limpia el estado y finaliza la sesión en Auth0.

Controlador de inicio de sesión

El controlador de inicio de sesión genera un token de estado para la protección CSRF y redirige a Auth0:

// app/api/auth/login/route.ts
import { NextResponse } from 'next/server'

export async function GET(request: Request) {
  const state = crypto.randomUUID()
  const params = new URLSearchParams({
    response_type: 'code',
    client_id: process.env.AUTH0_CLIENT_ID!,
    redirect_uri: process.env.AUTH0_CALLBACK_URL!,
    scope: 'openid profile email',
    state,
  })

  const authUrl = `https://${process.env.AUTH0_DOMAIN}/authorize?${params}`

  const response = NextResponse.redirect(authUrl)

  // Store state in a short-lived cookie for CSRF validation on callback
  response.cookies.set('auth_state', state, {
    httpOnly: true,
    secure: process.env.NODE_ENV === 'production',
    sameSite: 'lax',
    maxAge: 60 * 10, // 10 minutes
    path: '/',
  })

  return response
}

La cookie de estado tiene una caducidad de 10 minutos. Si el usuario tarda más tiempo en completar el flujo de inicio de sesión de Auth0, el callback rechazará la discrepancia de estado y devolverá un error 400. Esto es intencional. Los tokens de estado de corta duración limitan la exposición a ataques CSRF.

Controlador de callback

El controlador de callback verifica el estado, intercambia el código por tokens y almacena el token de ID en una cookie de sesión:

// app/api/auth/callback/route.ts
import { NextResponse } from 'next/server'

export async function GET(request: Request) {
  const url = new URL(request.url)
  const code = url.searchParams.get('code')
  const state = url.searchParams.get('state')

  // Parse the incoming cookies
  const cookieHeader = request.headers.get('cookie') ?? ''
  const cookies = Object.fromEntries(
    cookieHeader.split(';').map((c) => {
      const [k, ...v] = c.trim().split('=')
      return [k, v.join('=')]
    })
  )

  // CSRF check
  if (!code || !state || state !== cookies['auth_state']) {
    return new Response('Invalid state parameter', { status: 400 })
  }

  // Exchange authorization code for tokens
  const tokenRes = await fetch(
    `https://${process.env.AUTH0_DOMAIN}/oauth/token`,
    {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        grant_type: 'authorization_code',
        client_id: process.env.AUTH0_CLIENT_ID,
        client_secret: process.env.AUTH0_CLIENT_SECRET,
        code,
        redirect_uri: process.env.AUTH0_CALLBACK_URL,
      }),
    }
  )

  if (!tokenRes.ok) {
    return new Response('Token exchange failed', { status: 500 })
  }

  const { id_token } = await tokenRes.json()

  // Store the ID token in an httpOnly cookie
  // APP_BASE_URL is the origin only, so the mount path is added here. Without it
  // the redirect lands at the site root instead of inside the app.
  const response = NextResponse.redirect(
    new URL('/app/dashboard', process.env.APP_BASE_URL!)
  )

  response.cookies.set('auth_token', id_token, {
    httpOnly: true,
    secure: process.env.NODE_ENV === 'production',
    sameSite: 'lax',
    maxAge: 60 * 60 * 24, // 24 hours
    path: '/',
  })

  // Clear the state cookie
  response.cookies.set('auth_state', '', { maxAge: 0, path: '/' })

  return response
}

El callback almacena el token de ID, no el token de acceso, porque el token de ID es el que contiene las declaraciones de roles que configuraste en la acción posterior al inicio de sesión. El token de acceso es para llamar a APIs externas; el token de ID es para la gestión de sesiones de tu propia aplicación.

Controlador de cierre de sesión

El controlador de cierre de sesión borra la sesión y redirige al endpoint de cierre de sesión de Auth0:

// app/api/auth/logout/route.ts
import { NextResponse } from 'next/server'

export async function GET() {
  const returnTo = encodeURIComponent(process.env.APP_BASE_URL!)
  const logoutUrl = `https://${process.env.AUTH0_DOMAIN}/v2/logout?client_id=${process.env.AUTH0_CLIENT_ID}&returnTo=${returnTo}`

  const response = NextResponse.redirect(logoutUrl)
  response.cookies.set('auth_token', '', { maxAge: 0, path: '/' })

  return response
}

Punto de control: Inicia el servidor de desarrollo, visita /api/auth/login, completa el flujo de inicio de sesión de Auth0 y confirma que llegas a /dashboard con una cookie auth_token establecida. Decodifica el token en jwt.io y confirma que la declaración de roles está presente.

4. Aplica roles en el middleware

El middleware se ejecuta en cada solicitud antes de que llegue a una ruta. Aquí es donde verificas el JWT y extraes los roles, para luego redirigir a cualquiera que no supere la comprobación.

Crea o actualiza middleware.ts en la raíz del proyecto:

// middleware.ts
import { NextResponse, type NextRequest } from 'next/server'
import { createRemoteJWKSet, jwtVerify } from 'jose'

const JWKS = createRemoteJWKSet(
  new URL(`https://${process.env.AUTH0_DOMAIN}/.well-known/jwks.json`)
)

const ROLES_CLAIM = 'https://webflow-app.io/claims/roles'

// Routes that require authentication (any logged-in user)
const memberRoutes = ['/dashboard']

// Routes that require the admin role
const adminRoutes = ['/admin']

// Webflow Cloud serves the app from a mount path. Next.js does not prepend it to
// redirect targets you build yourself, so every in-app redirect needs it.
const BASE_PATH = '/app'

export async function middleware(request: NextRequest) {
  const { pathname } = request.nextUrl
  const token = request.cookies.get('auth_token')?.value

  const requiresMember = memberRoutes.some((p) => pathname.startsWith(p))
  const requiresAdmin = adminRoutes.some((p) => pathname.startsWith(p))

  if (!requiresMember && !requiresAdmin) {
    return NextResponse.next()
  }

  if (!token) {
    return NextResponse.redirect(
      new URL(`${BASE_PATH}/api/auth/login`, request.url)
    )
  }

  try {
    const { payload } = await jwtVerify(token, JWKS, {
      issuer: `https://${process.env.AUTH0_DOMAIN}/`,
      audience: process.env.AUTH0_CLIENT_ID,
    })

    const roles = (payload[ROLES_CLAIM] as string[]) ?? []

    if (requiresAdmin && !roles.includes('admin')) {
      return NextResponse.redirect(new URL(`${BASE_PATH}/dashboard`, request.url))
    }

    // Do not pass roles to handlers via headers: inbound headers are client-controlled
    const response = NextResponse.next()
    response.headers.set('x-auth-roles', roles.join(','))
    response.headers.set('x-auth-sub', payload.sub ?? '')
    return response
  } catch {
    // Token expired or invalid: clear cookie and redirect to login
    const response = NextResponse.redirect(
      new URL(`${BASE_PATH}/api/auth/login`, request.url)
    )
    response.cookies.set('auth_token', '', { maxAge: 0, path: '/' })
    return response
  }
}

export const config = {
  matcher: ['/dashboard/:path*', '/admin/:path*'],
}

createRemoteJWKSet obtiene las claves públicas de Auth0 y las almacena en caché por aislamiento. En la primera solicitud, realiza una llamada de red a /.well-known/jwks.json. Las solicitudes posteriores dentro de la misma instancia de Worker utilizan las claves almacenadas en caché. Al rotar las claves, jose vuelve a obtener automáticamente el JWKS cuando encuentra un ID de clave que no reconoce.

5. Verifica los roles en la capa de acceso a datos

El middleware protege las páginas, pero puede saltarse si alguien llama directamente a los controladores de ruta de tu API. Vuelve a verificar siempre los roles dentro de cualquier controlador de ruta que maneje datos confidenciales u operaciones privilegiadas. Las cabeceras del middleware no son un límite de confianza.

El asistente requireRole que aparece a continuación lee la cookie de autenticación directamente de la solicitud, verifica el JWT contra el JWKS de Auth0 y devuelve la carga útil decodificada o nulo.

Llámalo en la primera línea de cualquier controlador de ruta que acceda a datos confidenciales:

// app/api/admin/users/route.ts
import { createRemoteJWKSet, jwtVerify } from 'jose'

const JWKS = createRemoteJWKSet(
  new URL(`https://${process.env.AUTH0_DOMAIN}/.well-known/jwks.json`)
)

const ROLES_CLAIM = 'https://webflow-app.io/claims/roles'

async function requireRole(request: Request, role: string) {
  const cookieHeader = request.headers.get('cookie') ?? ''
  const match = cookieHeader.match(/auth_token=([^;]+)/)
  const token = match?.[1]

  if (!token) return null

  try {
    const { payload } = await jwtVerify(token, JWKS, {
      issuer: `https://${process.env.AUTH0_DOMAIN}/`,
      audience: process.env.AUTH0_CLIENT_ID,
    })
    const roles = (payload[ROLES_CLAIM] as string[]) ?? []
    return roles.includes(role) ? payload : null
  } catch {
    return null
  }
}

export async function GET(request: Request) {
  const user = await requireRole(request, 'admin')

  if (!user) {
    return Response.json({ error: 'Forbidden' }, { status: 403 })
  }

  // Fetch and return admin data
  const users = await fetchAllUsers()
  return Response.json(users)
}

El requireRole asistente verifica el JWT independientemente del middleware y devuelve la carga útil decodificada o nulo. Llamarlo en la primera línea de cualquier controlador confidencial significa que incluso una llamada directa a la API queda totalmente verificada.

¿Por qué verificar dos veces? El middleware se ejecuta antes del enrutamiento, pero una configuración incorrecta de matcher, una caché de borde o una solicitud directa a tu origen pueden saltárselo. Verificar en la capa de datos significa que un middleware evadido produce un error 403, no una filtración de datos. Este es el mismo principio detrás de CVE-2025-29927.

Punto de control: Llama a GET /api/admin/users sin una cookie de autenticación y confirma una respuesta 403. Inicia sesión como un usuario sin el admin rol y confirma el mismo 403. Inicia sesión como un usuario admin y confirma un 200 con la lista de usuarios.

¿Qué causa que el RBAC de Auth0 falle en Webflow Cloud?

La mayoría de los fallos se dividen en cuatro categorías: falta de notificaciones de rol en el token, discrepancias en el estado CSRF durante la devolución de llamada, fallos en la obtención de JWKS y problemas con las cookies de sesión.

Analicemos cada uno.

Falta la notificación de roles en el JWT decodificado

Navega a Actions → Flows → Login en el panel de control de Auth0 y confirma que la acción posterior al inicio de sesión (Post-Login Action) esté implementada y conectada entre Start y Complete. Una acción desconectada no ejecuta ningún código.

Además, confirma que el usuario tenga roles realmente asignados en Auth0. Navega a User Management → Users, selecciona al usuario, abre la pestaña Roles y verifica que el rol esperado aparezca allí. event.authorization?.roles en la acción refleja las asignaciones de roles de User Management y no se ve afectada por el interruptor de la API de RBAC.

Si ambos ajustes son correctos, verifica el espacio de nombres en la acción. La notificación en el token debe coincidir exactamente con la constante ROLES_CLAIM en tu middleware y controladores de ruta. Una diferencia de un solo carácter significa que la notificación está presente, pero la verificación de rol siempre devuelve falso.

La devolución de llamada falla con "Parámetro de estado no válido"

La verificación CSRF del estado compara el state parámetro de consulta de Auth0 con la auth_state cookie establecida al iniciar sesión. Esto falla cuando la devolución de llamada tarda más de 10 minutos (el maxAge de la cookie) o cuando las solicitudes de inicio de sesión y devolución de llamada llegan a diferentes instancias de Workers con diferentes almacenes de cookies en entornos de prueba.

En el desarrollo local, asegúrate de acceder al mismo origen para el inicio de sesión y la devolución de llamada. En producción en Webflow Cloud, esto es automático. Todas las solicitudes para una sesión determinada se enrutan a través del mismo dominio de cookies.

La obtención de JWKS falla o devuelve claves obsoletas

createRemoteJWKSet llama a https://{auth0-domain}/.well-known/jwks.json en la primera solicitud dentro de cada aislamiento de Worker. Si esta obtención agota el tiempo de espera, todas las verificaciones de JWT en ese aislamiento fallarán hasta el siguiente intento.

Comprueba que AUTH0_DOMAIN esté configurado correctamente en el panel de entorno de Webflow Cloud (sin el prefijo https:// , solo el dominio base como your-tenant.auth0.com). Un dominio incorrecto hace que la obtención de JWKS falle con un error de DNS, lo que aparece como un 500 en tus registros en lugar de un error de autenticación claro.

La cookie auth_token no se establece después de iniciar sesión

El controlador de callback almacena el token de ID en una cookie marcada httpOnly y secure. En el desarrollo local con http://localhost, secure: true impide que la cookie se establezca. El controlador de callback configura secure: process.env.NODE_ENV === 'production' para gestionar esto. Confirma que tu entorno local tiene NODE_ENV establecido en development (Next.js lo hace por defecto).

Si la cookie está presente pero la verificación falla, lo más probable es que el token haya caducado. La duración predeterminada del token de ID de Auth0 es de 36000 segundos (10 horas), mientras que la cookie anterior dura 24 horas, por lo que la cookie puede sobrevivir al token que contiene. Registra el error JWT en el bloque catch durante la depuración: console.log('JWT verify error:', err.message).

Qué construir después de tener el RBAC de Auth0 funcionando en tu Webflow Cloud App

Con el control de roles implementado, el siguiente paso natural es usar Auth0 Organizations para aplicaciones multiinquilino. Auth0 Organizations te permite agrupar usuarios por cuenta de cliente, donde cada organización tiene sus propios roles, conexiones y marca personalizada. El patrón RBAC de esta guía se extiende a las organizaciones: event.organization?.name está disponible en las acciones post-inicio de sesión junto con la matriz de roles.

Explora Webflow + Auth0 para obtener una visión general completa de la integración, incluyendo cómo se conecta Auth0 a los sitios de Webflow y qué casos de uso cubre esta combinación.