SDK de Next.js (@auris/nextjs)

@auris/nextjs v0.1.0

@auris/nextjs es el paquete recomendado para aplicaciones Next.js. Extiende @auris/react con utilidades del lado del servidor que funcionan en Server Components, Route Handlers y Vercel Edge Middleware.

El paquete expone tres puntos de entrada:

Punto de entrada	Entorno	Contenido
`@auris/nextjs`	Client Components	Re-exporta todo `@auris/react`
`@auris/nextjs/server`	Server Components, Route Handlers	`getSession`, `withAuth`, `requirePermission`, `checkPermission`, `createServerManagementClient`, `createServerFgaClient`
`@auris/nextjs/middleware`	Edge Middleware	`aurisMiddleware`

Instalación


npm install @auris/nextjs @auris/react @auris/js

Variables de entorno

Configúralas en tu fichero .env.local:


# Del lado del cliente (tanto navegador como servidor)
NEXT_PUBLIC_AURIS_DOMAIN=https://auth.tudominio.com
NEXT_PUBLIC_AURIS_CLIENT_ID=app_xxxxx
NEXT_PUBLIC_APP_URL=http://localhost:3000
 
# Del lado del servidor: usadas por aurisMiddleware, getSession, withAuth, requirePermission
AURIS_DOMAIN=https://auth.tudominio.com
AURIS_CLIENT_ID=app_xxxxx
 
# Solo del lado del servidor (nunca expuesto al navegador)
AURIS_CLIENT_SECRET=cs_live_xxxxx
AURIS_TENANT=mi-tenant
 
# Opcional: habilita la verificación JWT local sin llamada de red
AURIS_JWKS_URL=https://auth.tudominio.com/.well-known/jwks.json

Nunca incluyas AURIS_CLIENT_SECRET en una variable con prefijo NEXT_PUBLIC_. El secreto debe permanecer solo del lado del servidor.

Configuración

Instala el paquete y configura las variables de entorno

Sigue los pasos de instalación y variables de entorno anteriores.

Añade AurisProvider a tu layout raíz


// app/providers.tsx
'use client'
import { AurisProvider } from '@auris/nextjs'
 
export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <AurisProvider
      domain={process.env.NEXT_PUBLIC_AURIS_DOMAIN!}
      clientId={process.env.NEXT_PUBLIC_AURIS_CLIENT_ID!}
      redirectUri={`${process.env.NEXT_PUBLIC_APP_URL}/auth/callback`}
    >
      {children}
    </AurisProvider>
  )
}

Configura el middleware


// middleware.ts
import { aurisMiddleware } from '@auris/nextjs/middleware'
 
export default aurisMiddleware({
  domain: process.env.AURIS_DOMAIN!,
  clientId: process.env.AURIS_CLIENT_ID!,
  protectedPaths: ['/dashboard/*', '/settings/*'],
  publicPaths: ['/', '/about', '/pricing', '/auth/*'],
  loginUrl: '/auth/login',
})
 
export const config = {
  matcher: ['/((?!_next/static|_next/image|favicon.ico).*)'],
}

AurisProvider detecta los parámetros code y state en la URL al montarse y realiza el intercambio de tokens por sí mismo — tu página de callback solo tiene que esperar a isAuthenticated y navegar. Si necesitas lanzar el intercambio manualmente (p. ej., fuera del provider), usa useAuris().client.handleRedirectCallback().

Helpers del lado del servidor

`getSession(config)`

Recupera la sesión del usuario actual en Server Components o Route Handlers. Devuelve un objeto AurisSession plano (userId, email, username?, firstName?, lastName?, roles, tenant?, accessToken) o null:


// app/dashboard/page.tsx
import { getSession } from '@auris/nextjs/server'
import { redirect } from 'next/navigation'
 
export default async function DashboardPage() {
  const session = await getSession({
    domain: process.env.AURIS_DOMAIN!,
    clientId: process.env.AURIS_CLIENT_ID!,
  })
  if (!session) redirect('/auth/login')
 
  return <div>Bienvenido, {session.firstName}!</div>
}

`withAuth(handler, config)`

Función de orden superior que envuelve un Route Handler e inyecta la sesión autenticada como req.session:


// app/api/data/route.ts
import { withAuth } from '@auris/nextjs/server'
 
const aurisConfig = {
  domain: process.env.AURIS_DOMAIN!,
  clientId: process.env.AURIS_CLIENT_ID!,
}
 
export const GET = withAuth(async (req) => {
  return Response.json({ userId: req.session.userId })
}, aurisConfig)

`requirePermission(permission, config, handler)`

Como withAuth, pero además exige un permiso específico. Devuelve una respuesta 403 si el usuario está autenticado pero carece del permiso requerido:


import { requirePermission } from '@auris/nextjs/server'
 
const aurisConfig = {
  domain: process.env.AURIS_DOMAIN!,
  clientId: process.env.AURIS_CLIENT_ID!,
}
 
export const DELETE = requirePermission('admin:access', aurisConfig, async (req) => {
  // Solo se ejecuta si el usuario tiene el permiso 'admin:access'
  return Response.json({ deleted: true })
})

Para el renderizado condicional en Server Components usa checkPermission(permission, config), que devuelve un booleano.

`createServerFgaClient()`

Cliente FGA del lado del servidor para comprobaciones de autorización de grano fino:


import { createServerFgaClient } from '@auris/nextjs/server'
 
const fga = await createServerFgaClient()
const { allowed } = await fga.check({
  objectType: 'document',
  objectId: params.id,
  relation: 'editor',
  subjectType: 'user',
  subjectId: req.session.userId,
})

Middleware de Edge

aurisMiddleware se ejecuta en el Edge runtime de Vercel/Next.js. Protege rutas antes de que lleguen a tu aplicación:


// middleware.ts
import { aurisMiddleware } from '@auris/nextjs/middleware'
 
export default aurisMiddleware({
  domain: process.env.AURIS_DOMAIN!,
  clientId: process.env.AURIS_CLIENT_ID!,
  protectedPaths: ['/dashboard/*', '/admin/*'],
  publicPaths: ['/', '/auth/*'],
  loginUrl: '/auth/login',
  // Solo permite el callback OAuth (?code=&state=) en esta ruta
  callbackPaths: ['/auth/callback'],
})

Los patrones de ruta no son expresiones regulares: un patrón coincide de forma exacta, o como prefijo cuando termina en /* ('/dashboard/*' coincide con /dashboard y todo lo que hay debajo).