Autenticación

La autenticación y la autorización son dos procesos de seguridad que manejan el acceso a tu sitio web o aplicación. La autenticación verifica la identidad de un visitante, mientras que la autorización otorga acceso a áreas y recursos protegidos.

La autenticación te permite personalizar áreas de tu sitio para personas que han iniciado sesión y proporciona la mayor protección para la información personal o privada. Las bibliotecas de autenticación (por ejemplo, Better Auth, Clerk) proporcionan utilidades para múltiples métodos de autenticación, como el inicio de sesión con correo electrónico y los proveedores de OAuth.

Consejo

No hay una solución oficial de autenticación para Astro, pero puedes encontrar integraciones de “auth” de la comunidad en el directorio de integraciones.

Consulta como agregar autenticación con Supabase o agregar autenticación con Firebase o agregar autenticación con Scalekit (EN) en nuestras guías dedicadas para estos servicios de backend.

Better Auth

Better Auth es un framework agnóstico de autenticación (y autorización) independiente para TypeScript. Proporciona un conjunto completo de funciones listas para usar e incluye un ecosistema de complementos que simplifica la adición de funcionalidades avanzadas.

Es compatible con Astro desde el primer momento, y puedes utilizarlo para añadir autenticación a tu proyecto de Astro.

Instalación

npm

npm install better-auth

pnpm

pnpm add better-auth

Yarn

yarn add better-auth

Para obtener instrucciones detalladas sobre la configuración, consulta la Guía de instalación de Better Auth.

Configuración

Configura tu tabla de base de datos para almacenar los datos de los usuarios y tus métodos de autenticación preferidos tal y como se describe en la Guía de instalación de Better Auth. A continuación, tendrás que montar el controlador Better Auth en tu proyecto de Astro.

src/pages/api/auth/[...all].ts

import { auth } from "../../../lib/auth"; // importa tu instancia de Better Auth
import type { APIRoute } from "astro";

export const prerender = false; // Innecesario en modo 'server'

export const ALL: APIRoute = async (ctx) => {
  return auth.handler(ctx.request);
};

Sigue la Guía de Better Auth en Astro para obtener más información.

Uso

Better Auth ofrece un helper createAuthClient() para varios frameworks, incluidos Vanilla JS, React, Vue, Svelte y Solid.

Por ejemplo, para crear un cliente para React, importa el helper desde 'better-auth/react':

React

src/lib/auth-client.ts

import { createAuthClient } from 'better-auth/react';

export const authClient = createAuthClient();

export const { signIn, signOut } = authClient;

Solid

src/lib/auth-client.ts

import { createAuthClient } from 'better-auth/solid';

export const authClient = createAuthClient();

export const { signIn, signOut } = authClient;

Svelte

src/lib/auth-client.ts

import { createAuthClient } from 'better-auth/svelte';

export const authClient = createAuthClient();

export const { signIn, signOut } = authClient;

Vue

src/lib/auth-client.ts

import { createAuthClient } from 'better-auth/vue';

export const authClient = createAuthClient();

export const { signIn, signOut } = authClient;

Una vez configurado el cliente, puedes utilizarlo para autenticar usuarios en tus componentes de Astro o en cualquier archivo específico del framework. El siguiente ejemplo añade la posibilidad de iniciar o cerrar sesión con las funciones signIn() y signOut() configuradas.

src/pages/index.astro

---
import Layout from "../layouts/Base.astro";
---

<Layout>
  <button id="login">Login</button>
  <button id="logout">Logout</button>

  <script>
    const { signIn, signOut } = await import("../lib/auth-client");
    const loginButton = document.querySelector<HTMLButtonElement>("#login");
    const logoutButton = document.querySelector<HTMLButtonElement>("#logout");

    if (!loginButton || !logoutButton) throw new Error("Buttons not found");

    loginButton.onclick = () =>
      signIn.social({
        provider: "github",
        callbackURL: "/dashboard",
      });
    logoutButton.onclick = () => signOut();
  </script>
</Layout>

A continuación, puedes utilizar el objeto auth para obtener los datos de sesión del usuario en tu código del lado del servidor. El siguiente ejemplo personaliza el contenido de la página mostrando el nombre de un usuario autenticado:

src/pages/index.astro

---
import { auth } from "../lib/auth"; // importa tu instancia de Better Auth

export const prerender = false; // Innecesario en modo 'server'

const session = await auth.api.getSession({
  headers: Astro.request.headers,
});
---

<p>{session.user?.name}</p>

También puedes utilizar el objeto auth para proteger tus rutas. El siguiente ejemplo utiliza el enrutamiento avanzado de Astro con Hono para requerir una sesión autenticada en todas las rutas bajo /dashboard, redirigiendo a la página de inicio en caso contrario:

src/fetch.ts

import { Hono, type Context, type Next } from "hono";
import { astro } from "astro/hono";
import { auth } from "./lib/auth"; // importa tu instancia de Better Auth

const app = new Hono();

// Protege todas las rutas bajo /dashboard.
app.use("/dashboard", requireAuth);
app.use("/dashboard/*", requireAuth);

// Ejecuta el pipeline integrado de Astro para todas las demás solicitudes.
app.use(astro());

export default app;

async function requireAuth(c: Context, next: Next) {
  const session = await auth.api.getSession({
    headers: c.req.raw.headers,
  });
  if (!session) {
    return c.redirect("/");
  }
  return next();
}

Precaución

No hay garantía de que el pathname público que ve un middleware sea el mismo que la ruta que Astro resuelve internamente: una base configurada, la codificación de la URL y las barras duplicadas pueden hacer que difieran. Un atacante puede explotar esta brecha para acceder a una ruta protegida con un pathname que tu comprobación no reconozca.

No autorices solicitudes comparando context.url.pathname con una cadena de texto (p. ej. context.url.pathname === "/dashboard" o context.url.pathname.startsWith("/dashboard")). En su lugar, restringe el acceso en un enrutador que resuelva las rutas por ti.

Siguientes pasos

• Guía de Better Auth en Astro
• Ejemplo de Better Auth en Astro
• Documentación de Better Auth
• Repositorio de GitHub de Better Auth

Clerk

Clerk es una suite completa de UIs incrustables, APIs flexibles y paneles de administración para autenticar y gestionar a tus usuarios. Un SDK oficial de Clerk para Astro está disponible.

Instalación

Instala @clerk/astro usando el gestor de paquetes de tu elección.

npm

npm install @clerk/astro

pnpm

pnpm add @clerk/astro

Yarn

yarn add @clerk/astro

Configuración

Sigue la guía de inicio rápido de Clerk para Astro para configurar la integración de Clerk y el middleware en tu proyecto de Astro.

Uso

Clerk proporciona componentes que te permiten controlar la visibilidad de las páginas basadas en el estado de autenticación de tu usuario. Muestra a los usuarios desconectados un botón de inicio de sesión en lugar del contenido disponible para los usuarios que han iniciado sesión:

src/pages/index.astro

---
import Layout from "../layouts/Base.astro";
import { Show, UserButton, SignInButton } from "@clerk/astro/components";

export const prerender = false; // Innecesario en modo 'server'
---

<Layout>
  <Show when="signed-in">
    <UserButton />
  </Show>
  <Show when="signed-out">
    <SignInButton />
  </Show>
</Layout>

Clerk también te permite proteger rutas en el servidor usando middleware:

1. Configura clerkMiddleware() como el manejador de onRequest en tu middleware:

   src/middleware.ts

   import { clerkMiddleware } from "@clerk/astro/server";
   
   export const onRequest = clerkMiddleware({
     /* opciones */
   });

2. Accede al estado de autenticación en tus páginas y rutas de API con locals.auth(). Esto te permite comprobar si un usuario está autenticado y tomar las acciones adecuadas (p. ej. redirigir a la página de inicio de sesión o devolver una respuesta diferente).

   Pages

   src/pages/dashboard.astro

   ---
   const { isAuthenticated, redirectToSignIn } = Astro.locals.auth();
   
   if (!isAuthenticated) return redirectToSignIn();
   ---
   
   <h1>Dashboard</h1>

   API routes

   src/pages/api/data.ts

   import type { APIRoute } from "astro";
   
   export const GET: APIRoute = ({ locals }) => {
     const { isAuthenticated, userId } = locals.auth();
   
     if (!isAuthenticated) {
       return new Response("Unauthorized", { status: 401 });
     }
   
     return Response.json({ userId });
   };

Siguientes pasos

• Leer la documentación de clerk/astro oficial
• Empieza usando una plantilla con el proyecto de inicio rápido de Clerk + Astro

Lucia

Lucia es un recurso para implementar la autenticación basada en sesiones en varios frameworks, incluido Astro.

Guías

1. Crea una API de sesiones básica con la base de datos que elijas.
2. Añade cookies de sesión utilizando endpoints y middleware.
3. Implementa GitHub OAuth utilizando las API que has implementado.

Ejemplos

• Ejemplo de Github OAuth en Astro
• Ejemplo de Google OAuth en Astro
• Ejemplo de correo electrónico y contraseña con 2FA en Astro
• Ejemplo de correo electrónico y contraseña con 2FA y WebAuthn en Astro

Scalekit

Scalekit es una plataforma de autenticación para aplicaciones B2B y de IA. Gestiona el flujo completo de OAuth 2.0 y OIDC, admitiendo métodos como el inicio de sesión social, SSO empresarial y enlaces mágicos. Luego, devuelve los tokens y un perfil de usuario sin requerir una UI de inicio de sesión personalizada.

Un único entorno de Scalekit puede admitir múltiples aplicaciones. Esto te permite autenticarte una vez y compartir la misma sesión en todas tus propiedades (p. ej. app.yourcompany.com y docs.yourcompany.com).

Guía

Sigue la guía de Scalekit y Astro (EN) para agregar autenticación a tu proyecto SSR de Astro utilizando el inicio de sesión social, SSO empresarial y más.

Ejemplos

• Tutorial de un blog en Astro con autenticación de Scalekit (flujo de código de autorización)
• Código fuente del sitio de documentación para desarrolladores de Scalekit (flujo PKCE, sin SDK)

Recursos de la comunidad

• Usando Microsoft Entra Id EasyAuth con Astro y Azure Static Web App