docs: update authentication section

sgomez · sgomez · commit 8f2bb5fab608 · 2025-10-30T20:46:26.000+01:00
diff --git a/docs/security-next-auth.md b/docs/security-next-auth.md
@@ -1,197 +1,242 @@
+## Autenticación con Better Auth
 
-!!! danger
+En esta sección configuraremos Better Auth paso a paso utilizando GitHub como proveedor de autenticación y una base de datos SQLite local para almacenar las credenciales.
 
-    Next Auth ahora es parte de Better Auth [Ver anuncio]. Con lo que no se recomienda hacer nuevos proyectos con Next Auth.
-    Está sección será reescrita desde cero. Por lo que ahora mismo puede que no te funcione.
+## Instalación
 
-    [Ver anuncio]: https://www.better-auth.com/blog/authjs-joins-better-auth
+Instalamos las dependencias necesarias en el proyecto:
 
+```bash
+npm install better-auth better-sqlite3
+npm install --save-dev @types/better-sqlite3
+```
 
-NextAuth.js es una librería de autenticación que se integra fácilmente con aplicaciones web basadas en Next.js. Esta potente librería simplifica la implementación de la autenticación de usuarios, incluyendo la autenticación social y el manejo de sesiones. Con NextAuth.js, puedes configurar la autenticación de manera eficiente y segura, permitiendo a los usuarios acceder a tus aplicaciones de forma sencilla a través de múltiples proveedores, como Google, Facebook, GitHub y más.
+Vamos a usar SQLite con `better-sqlite3` porque es simple y no requiere instalar servidores adicionales. Si prefieres otro motor, puedes sustituirlo siguiendo la documentación oficial.
 
-## Instalación
+## Variables de entorno
 
-Lo primero es instalar el paquete, como siempre:
+Creamos (o actualizamos) el archivo `.env.local` con los valores que demanda Better Auth. La clave secreta se usa para encriptar y firmar cookies. Puedes generar una cadena aleatoria con cualquier herramienta (por ejemplo `openssl rand -base64 32`).
 
-```bash
-npm install next-auth
+```env title=".env.local"
+BETTER_AUTH_SECRET=pon_aqui_una_cadena_unica
+BETTER_AUTH_URL=http://localhost:3000
+NEXT_PUBLIC_APP_URL=http://localhost:3000
+GITHUB_CLIENT_ID=tu_client_id_de_github
+GITHUB_CLIENT_SECRET=tu_client_secret_de_github
 ```
 
-Y a continuación creamos el fichero de configuración:
+`NEXT_PUBLIC_APP_URL` lo utilizamos en el cliente para construir la URL base cuando el proyecto se despliega en otro dominio.
 
-```ts title="src/app/api/auth/[...nextauth]/route.ts"
-import NextAuth, { NextAuthOptions } from 'next-auth'
-import GithubProvider from 'next-auth/providers/github'
+El campo `BETTER_AUTH_URL` siempre debe apuntar a la URL pública de la aplicación (en local usaremos `http://localhost:3000`).
 
-export const config: NextAuthOptions = {
-  providers: [
-    GithubProvider({
-      clientId: process.env.GITHUB_ID || '',
-      clientSecret: process.env.GITHUB_SECRET || '',
-    }),
-],
-  secret: process.env.NEXTAUTH_SECRET,
-}
+## Configurar Better Auth
+
+Creamos el archivo `src/lib/auth.ts` con la instancia de Better Auth. En este ejemplo habilitamos el plugin `nextCookies` para que las cookies se sincronicen automáticamente en server actions y server components, configuramos SQLite y registramos el proveedor de GitHub.
 
-const handler = NextAuth(config)
+```ts title="src/lib/auth.ts"
+import { betterAuth } from 'better-auth'
+import { nextCookies } from 'better-auth/next-js'
+import Database from 'better-sqlite3'
 
-export { handler as GET, handler as POST }
+export const auth = betterAuth({
+  database: new Database('./better-auth.sqlite'),
+  plugins: [nextCookies()],
+  socialProviders: {
+    github: {
+      clientId: process.env.GITHUB_CLIENT_ID as string,
+      clientSecret: process.env.GITHUB_CLIENT_SECRET as string,
+    },
+  },
+})
 ```
 
-Y activamos el middleware que se encarga de garantizar que todas las llamadas a Next
-son seguras:
+La base de datos SQLite (`better-auth.sqlite`) se crea automáticamente en la raíz del proyecto cuando ejecutemos las migraciones.
 
-```ts title="src/middleware.ts"
-export { default } from 'next-auth/middleware'
+## Crear las tablas
 
-export const config = { matcher: ['/counter'] }
+Better Auth incluye una CLI que genera el esquema y las migraciones necesarias. Desde la raíz del proyecto ejecutamos:
+
+```bash
+npx @better-auth/cli generate
+npx @better-auth/cli migrate
 ```
 
-!!! info
-    Por defecto el middleware asegura todas los accesos. Con `matcher` podemos restringir
-    qué rutas queremos proteger. Para este ejemplo solo vamos a asegurar nuestro contador.
+El primer comando crea la migración y el segundo la aplica sobre nuestro archivo SQLite. Si utilizas otro motor o un ORM, revisa la documentación oficial para adaptar estos pasos.
 
-    Mira la documentación de [middleware en next](https://nextjs.org/docs/app/building-your-application/routing/middleware) para saber como funciona `matcher`.
+## Ruta de API
 
+Next.js necesita exponer un endpoint que procese las peticiones de autenticación. Creamos el archivo `src/app/api/auth/[...all]/route.ts` con el manejador oficial:
 
-En este fichero registraremos que proveedores de identidad queremos usar, en el
-ejemplo usaremos GitHub, pero podemos usar muchísimos mas (Google, Spotify, Twitter,...).
+```ts title="src/app/api/auth/[...all]/route.ts"
+import { toNextJsHandler } from 'better-auth/next-js'
+import { auth } from '@/lib/auth'
 
-Ahora necesitamos poder leer la sesión del usuario cuando esta logueado. NextAuth
-nos da una función, pero como requiere pasarle un parámetro vamos a crear una propia
-que nos ahorre trabajo cada vez que la queremos usar:
+export const { GET, POST } = toNextJsHandler(auth.handler)
+```
 
-```ts title="src/lib/next/auth.ts"
-import type {
-  GetServerSidePropsContext,
-  NextApiRequest,
-  NextApiResponse,
-} from 'next'
-import { getServerSession } from 'next-auth'
+Recomendamos mantener la ruta `/api/auth/[...all]`, ya que coincidimos con lo que espera la librería y con la configuración de GitHub.
 
-import { config } from '@/app/api/auth/[...nextauth]/route'
+## Registrar la aplicación en GitHub
 
-export function auth(
-  ...args:
-    | [GetServerSidePropsContext['req'], GetServerSidePropsContext['res']]
-    | [NextApiRequest, NextApiResponse]
-    | []
-) {
-  return getServerSession(...args, config)
-}
-```
+Para permitir el login social necesitamos crear una OAuth App en GitHub:
 
-## Registro de nuestra aplicación en Github
+1. Accedemos a [https://github.com/settings/developers](https://github.com/settings/developers).
 
-Para que podamos hacer login usando Github, necesitamos registrar una aplicación
-OAuth. Para ello nos iremos a la web de registro de aplicaciones OAuth:
-[https://github.com/settings/applications/new](https://github.com/settings/applications/new)
+2. Creamos una **OAuth App** con los siguientes valores en desarrollo:
+    1. **Homepage URL**: `http://localhost:3000`
+    1. **Authorization callback URL**: `http://localhost:3000/api/auth/callback/github`
 
-Necesitamos tres datos:
+    ![Registro de aplicación OAuth en Github](images/github-oauth-registry.png)
 
-* **Application name**: El que queramos, por ejemplo: `Curso de NextJS del Aula de Software Libre`
-* **Homepage URL**: Esta sería la url de nuestra web si estuviera publicada, por ahora usaremos: `http://localhost:3000/`
-* **Authorization callback URL**: Esta es la url de NextAuth que finalizará el proceso de autenticación, debemos poner: `http://localhost:3000/api/auth/callback/github`
+3. Tras completar el formulario, GitHub nos mostrará el `Client ID`. Desde la misma pantalla generamos un nuevo `Client Secret`.
 
-![Registro de aplicación OAuth en Github](images/github-oauth-registry.png)
+    ![Credenciales de aplicación OAuth en Github](images/github-oauth-credentials.png)
 
+4. Copiamos ambos valores en `.env.local`.
 
-Una vez eso ya tendremos el primero de los dos datos que necesitamos el `GITHUB_ID`, es la cadena hexadecimal que 
-aparece en la web de la aplicación. A continuación debemos pulsar a `Generate a new client secret` para
-conseguir el segundo dato necesario `GITHUB_SECRET`
 
 
-![Credenciales de aplicación OAuth en Github](images/github-oauth-credentials.png)
 
-Y por último vamos a crear un archivo de credenciales donde guardar esos datos:
+!!! info
+    Si recibes errores relacionados con el correo electrónico del usuario, revisa que tu GitHub App tenga el permiso *Email addresses* en modo lectura dentro de *Account permissions*.
 
-```env title=".env.local"
-GITHUB_ID=tu Client ID de la web de Github
-GITHUB_SECRET=tu Client Secret de la web de Github
-NEXTAUTH_URL=http://localhost:3000/api/auth
-NEXTAUTH_SECRET=CHANGE_ME
-```
+## Cliente de Better Auth en React
 
-!!! info
-    Recuerda que las credenciales son secretas, nunca las subas a Github.
-    El fichero `.env.local` está en el `.gitignore` así que no tienes que preocuparte.
+El cliente nos ayuda a iniciar sesión desde componentes de React y a recuperar la sesión desde el navegador. Creamos `src/lib/auth-client.ts`:
 
-## Acceso a la web asegurara
+```ts title="src/lib/auth-client.ts"
+'use client'
 
-Si intentamos acceder ahora a nuestro contador, veremos que nos saltará la página
-para loguearnos en Github. Solo si nos identificamos podremos verla.
+import { createAuthClient } from 'better-auth/react'
 
-Para conseguir ver los datos del usuario es tan facil como hacer lo siguiente en cualquier 
-lugar donde lo necesitemos:
+export const authClient = createAuthClient({
+  baseURL: process.env.NEXT_PUBLIC_APP_URL ?? 'http://localhost:3000',
+})
 
-```ts
-import { Session } from 'next-auth'
+export const { signIn, signOut, useSession } = authClient
+```
+
+Exportamos los métodos que utilizaremos en los componentes (`signIn`, `signOut`, `useSession`). Puedes añadir más helpers si los necesitas.
+
+## Proteger páginas y obtener la sesión
 
-import { auth } from '@/lib/next/auth'
+Better Auth expone un API preparado para ejecutarse en componentes de servidor o server actions. En este ejemplo recuperamos la sesión dentro de una página del directorio `app` y redirigimos a los usuarios no autenticados:
 
-export default async function Page() {
-  const session: Session | null = await auth()
+```tsx title="src/app/dashboard/page.tsx"
+import { headers } from 'next/headers'
+import { redirect } from 'next/navigation'
+import { auth } from '@/lib/auth'
 
-  // Podemos ver en la consola de NextJS todos los datos del servidor
-  console.table(session)
+export default async function DashboardPage() {
+  const session = await auth.api.getSession({
+    headers: await headers(),
+  })
 
   if (!session) {
-    return <>Unauthorized</>
+    redirect('/sign-in')
   }
 
-  const { user: { name } = {} } = session
-
-  return <>Hello, {name}.</>
+  return <h1>Hola, {session.user.name ?? 'Usuario'}.</h1>
 }
 ```
 
-## Ampliar datos de la sesión
+## Sign in desde el cliente
 
-En ocasiones necesitamos saber más datos provenientes del proveedor de identidad. Uno
-de ellos es el `id`, que no viene. Vamos a añadirlo.
+En el lado del cliente podemos llamar a `signIn.social` para abrir la ventana de GitHub. Crea, por ejemplo, un componente `LoginButton`:
 
-Modificamos nuestra configuración:
+```tsx title="src/components/login-button.tsx"
+'use client'
 
-```ts title="src/app/api/auth/[...nextauth]/route.ts" hl_lines="5-11"
-import NextAuth, { NextAuthOptions } from 'next-auth'
-import GithubProvider from 'next-auth/providers/github'
+import { CommandLineIcon } from '@heroicons/react/24/solid'
+import { Button } from '@heroui/react'
 
-export const config: NextAuthOptions = {
-  callbacks: {
-    async session({ session, token }) {
-      session.user.id = token.sub
+import { signIn } from '@/lib/auth-client'
 
-      return session
-    },
-  },
-  providers: [
-    GithubProvider({
-      clientId: process.env.GITHUB_ID || '',
-      clientSecret: process.env.GITHUB_SECRET || '',
-    }),
-  ],
-  secret: process.env.NEXTAUTH_SECRET,
+export function LoginButton() {
+  return (
+    <Button
+      color="primary"
+      onPress={() =>
+        signIn.social({ provider: 'github', callbackURL: '/dashboard' })
+      }
+      startContent={<CommandLineIcon className="h-5 w-5" />}
+      variant="solid"
+    >
+      Entrar con GitHub
+    </Button>
+  )
 }
+```
 
-const handler = NextAuth(config)
-
-export { handler as GET, handler as POST }
+El cliente gestiona la apertura del flujo OAuth y, tras regresar de GitHub, refresca la sesión automáticamente.
+
+## Página de inicio de sesión
+
+Cuando redirigimos a `/sign-in` necesitamos una vista sencilla que invite al usuario a iniciar sesión con GitHub. Usaremos componentes de HeroUI y un icono de Heroicons para mantener la estética del curso. Crea el archivo `src/app/sign-in/page.tsx` con el siguiente contenido:
+
+```tsx title="src/app/sign-in/page.tsx"
+import { LockClosedIcon } from '@heroicons/react/24/solid'
+import { Card, CardBody, CardHeader } from '@heroui/react'
+
+import { LoginButton } from '@/components/login-button'
+
+export default function SignInPage() {
+  return (
+    <div className="flex min-h-screen items-center justify-center bg-default-100">
+      <Card className="w-[320px]">
+        <CardHeader className="flex flex-col items-center gap-2 text-center">
+          <LockClosedIcon className="h-8 w-8 text-primary" />
+          <h1 className="font-semibold text-large">Necesitas iniciar sesión</h1>
+        </CardHeader>
+        <CardBody className="flex flex-col gap-4 text-center">
+          <p className="text-default-500 text-sm">
+            Usa tu cuenta de GitHub para continuar.
+          </p>
+          <LoginButton />
+        </CardBody>
+      </Card>
+    </div>
+  )
+}
 ```
 
-Estamos añadiendo un campo extra, desgraciadamente ese campo no existe en el interfaz
-de usuario original, pero podemos ampliarlo. Esta técnica se llama interface augmention.
-Creamos el siguiente fichero:
+Esta página funciona como destino tanto para los usuarios que llegan de forma directa como para los que han sido redirigidos por el middleware. Al reutilizar `LoginButton` mantenemos la lógica en un único sitio.
+
+## Middleware opcional
 
-```ts title="src/types/next-auth.d.ts"
-import { DefaultSession } from 'next-auth'
+Si necesitas redirigir rápidamente desde el `middleware` de Next.js, puedes comprobar la existencia de la cookie de sesión utilizando el helper `getSessionCookie`. Ten en cuenta que esta verificación es optimista: siempre valida la sesión en el servidor antes de mostrar datos sensibles.
 
-declare module 'next-auth' {
-  interface Session {
-    user: {
-      id?: string | null
-    } & DefaultSession['user']
+```ts title="src/middleware.ts"
+import { NextRequest, NextResponse } from 'next/server'
+import { getSessionCookie } from 'better-auth/cookies'
+
+export function middleware(request: NextRequest) {
+  const sessionCookie = getSessionCookie(request)
+
+  if (!sessionCookie) {
+    return NextResponse.redirect(new URL('/sign-in', request.url))
   }
+
+  return NextResponse.next()
+}
+
+export const config = {
+  matcher: ['/dashboard'],
 }
 ```
 
-Y ya el interprete de Typescript debe dejar de dar error porque el campo id no existe.
+### Validación completa en cada página
+
+La forma segura de proteger rutas es verificar la sesión dentro de la propia página o en la acción del servidor que vaya a ejecutar lógica sensible (como hicimos en el ejemplo anterior con `auth.api.getSession`).
+
+## Resumen
+
+1. Instalamos `better-auth` y configuramos una base de datos (en este curso usamos SQLite).
+2. Creamos un archivo `auth.ts` con la instancia, habilitamos GitHub como proveedor social y registramos el plugin `nextCookies`.
+3. Configuramos la ruta `/api/auth/[...all]` con `toNextJsHandler`.
+4. Registramos la aplicación en GitHub y añadimos las credenciales en `.env.local`.
+5. Creamos un cliente (`auth-client.ts`) para iniciar sesión desde componentes.
+6. Añadimos la página `/sign-in` reutilizando `LoginButton` para ofrecer el acceso social.
+7. Protegemos páginas recuperando la sesión con `auth.api.getSession`.
+
+Con estos pasos ya tenemos autenticación social con GitHub funcionando en nuestro proyecto Next.js usando Better Auth.
