Inicio de sesión y espacios de trabajo

Inicio de sesión integrado

Campbooks es su propio inicio de sesión y emisor de tokens. No hay ningún servicio de identidad aparte que ejecutar. Las personas inician sesión con Google, Microsoft, Zoho o una llave de acceso (passkey), y el servidor emite todos los tokens.

No necesita configuración. Deja CAMPBOOKS_AUTH__ISSUER sin definir, como hace el compose.yaml incluido. El emisor es CAMPBOOKS_PUBLIC_URL, así que ponle la dirección que usa la gente.

• CAMPBOOKS_PUBLIC_URL tiene que ser https://. El http:// simple solo funciona con CAMPBOOKS_ENV=development, para una prueba en tu máquina.
• El servidor firma los tokens con claves que genera en el primer arranque y renueva cada 30 días. Se guardan en Postgres, cifradas con la clave secreta de la instancia.
• Las llaves de acceso no necesitan configuración. Los navegadores las ofrecen en https://, o en http://localhost en desarrollo.

La clave secreta de la instancia

En el primer arranque, el servicio puntual server-init genera la clave secreta de la instancia en el volumen server-secrets. El servidor la lee como un archivo, nunca desde .env.

La clave protege lo que Campbooks guarda por ti: las claves de firma del inicio de sesión, los tokens de las sesiones web y las credenciales de las cuentas conectadas. Si la pierdes, no se puede recuperar, ni tampoco lo que protege. El servidor se niega a arrancar cuando la clave no abre las claves de firma guardadas.

Guarda una copia en un lugar seguro, aparte de tus copias de seguridad. Una copia de seguridad que tenga la base de datos y la clave le da todo lo que hay en la base de datos a quien la encuentre. Consulta Actualizaciones y copias de seguridad.

Cómo te inicia sesión la aplicación web

El servidor inicia la sesión de los navegadores por sí mismo. Abre la aplicación y, si no has iniciado sesión, te envía a la pantalla de inicio de sesión y te devuelve. El navegador solo recibe una cookie de sesión HttpOnly, SameSite=Strict. Los tokens se quedan en el servidor, cifrados, en Postgres.

• Las sesiones terminan tras 48 horas sin uso, o 30 días como máximo, o cuando cierras la sesión.
• Con https://, la cookie es Secure y lleva el prefijo __Host-. Con http:// simple no es ninguna de las dos cosas, y el servidor registra un aviso. El http simple solo vale en localhost.

Los ajustes de sesión son el bloque CAMPBOOKS_BFF__*, listado en Configuración.

Iniciar sesión con Google, Microsoft o Zoho

Cada proveedor es opcional. Aparece en la pantalla de inicio de sesión cuando le das un ID de cliente y un secreto de cliente. Sin ninguno, la gente puede usar una llave de acceso.

Para cada proveedor que quieras:

1. Registra una aplicación OAuth en la consola del proveedor, con este URI de redirección (<provider> es google, microsoft o zoho):

   ${CAMPBOOKS_PUBLIC_URL}/auth/callback/<provider>

2. Pon el ID de cliente en .env como CAMPBOOKS_GOOGLE__CLIENT_ID, CAMPBOOKS_MICROSOFT__CLIENT_ID o CAMPBOOKS_ZOHO__CLIENT_ID.

3. Pon el secreto de cliente en un archivo de deploy/secrets/: google-client-secret, microsoft-client-secret o zoho-client-secret. Nunca pongas secretos en .env. Compose monta la carpeta en solo lectura en el servidor, en /run/secrets/campbooks, y el servidor se ejecuta con el uid 10001:

   sudo chown 10001:10001 secrets/google-client-secret
   sudo chmod 0400 secrets/google-client-secret

   Docker Desktop en macOS o Windows no necesita el chown.

4. Apunta el servidor al archivo en .env, por ejemplo:

   CAMPBOOKS_GOOGLE__CLIENT_ID=your-client-id
   CAMPBOOKS_GOOGLE__CLIENT_SECRET_FILE=/run/secrets/campbooks/google-client-secret

5. Aplícalo:

   docker compose up -d

Notas por proveedor:

• Google: tipo de aplicación Aplicación web. Es el mismo cliente OAuth que conecta Gmail, así que añade el ámbito profile a su pantalla de consentimiento. Publica la aplicación, porque una aplicación en Testing emite refresh tokens que caducan a los 7 días. Hasta que Google verifique la aplicación, la gente ve la pantalla de «aplicación no verificada» al registrarse.
• Microsoft: cuentas personales, de trabajo y de centros educativos. En el centro de administración de Microsoft Entra, registra una aplicación y añade un URI de redirección Web. CAMPBOOKS_MICROSOFT__TENANT (por defecto common) limita quién puede iniciar sesión: organizations, consumers o el ID de un tenant. Microsoft no verifica el correo que informa, así que en una instancia invite_only solo cuenta como verificado si añades la notificación opcional xms_edov al token de ID.
• Zoho: en la consola de la API de Zoho, añade una Server-based application y activa Multi-DC, para que un solo cliente sirva a todos los centros de datos. Sin Multi-DC, define CAMPBOOKS_ZOHO__ACCOUNTS_SERVER con el centro de datos de tu aplicación, por ejemplo https://accounts.zoho.eu.

Los mismos clientes de Google y Zoho también conectan buzones. Consulta Conectar buzones.

Para rotar un secreto, sustituye el archivo y ejecuta docker compose up -d.

Si tu aplicación OAuth ya registró otra ruta de retorno, define CAMPBOOKS_<PROVIDER>__REDIRECT_PATH y haz que tu proxy inverso reescriba esa ruta a /auth/callback/<provider>. Déjalo sin definir en una aplicación nueva.

Cuentas y vinculación

• Una cuenta se vincula a la cuenta del proveedor por su ID, nunca por la dirección de correo. Iniciar sesión con una cuenta de proveedor que Campbooks no conoce ofrece crear una cuenta nueva.
• Con la sesión iniciada, cada persona puede añadir más formas de entrar en Ajustes, luego Formas de iniciar sesión. La última forma de entrar no se puede quitar.

Detrás de un proxy inverso

El inicio de sesión tiene un límite de peticiones por dirección de cliente. Detrás de un proxy, todas las peticiones parecen venir del proxy, y todos los clientes comparten el mismo límite. Define CAMPBOOKS_TRUSTED_PROXIES en .env con la dirección o la red del proxy, como direcciones o bloques CIDR separados por comas:

CAMPBOOKS_TRUSTED_PROXIES=172.18.0.0/16

Espacios de trabajo y política de registro

La primera persona que inicia sesión crea el primer espacio de trabajo e invita a los demás desde Ajustes, luego Miembros. Quién más puede crear un espacio de trabajo lo decide CAMPBOOKS_SIGNUP__POLICY:

Valor	Qué ocurre
open (por defecto)	Cualquier persona con una cuenta puede crear un espacio de trabajo.
invite_only	Sin registro público. Solo las personas con una invitación reciben una cuenta.
approval	Pedir un espacio de trabajo registra una solicitud. Nadie entra hasta que se aprueba.
code	Crear un espacio de trabajo exige un código de registro de CAMPBOOKS_SIGNUP__CODES.

La misma política decide si Google, Microsoft y Zoho crean cuentas para personas nuevas. La primera persona usuaria de la instancia siempre puede crear un espacio de trabajo, así que en una instancia nueva inicia sesión tú antes de compartir la dirección.

Las invitaciones aún no se envían por correo. Quien invita recibe el enlace una sola vez, justo después de invitar, y lo envía. El enlace se construye a partir de CAMPBOOKS_PUBLIC_URL, así que ponle la dirección que usa la gente.

Usar un proveedor de identidad externo

Es una opción avanzada, y no se aprovisiona nada para ella. Definir CAMPBOOKS_AUTH__ISSUER con un emisor OpenID Connect externo hace que la API confíe en los tokens de ese emisor. Define también CAMPBOOKS_AUTH__JWKS_URL y CAMPBOOKS_AUTH__AUDIENCE. La aplicación web inicia entonces sesión a través de él con CAMPBOOKS_BFF__CLIENT_SECRET (o CAMPBOOKS_BFF__CLIENT_SECRET_FILE).

Mientras lo hagas, el inicio de sesión propio de Campbooks, las formas de iniciar sesión, las aplicaciones y la conexión de buzones quedan desactivados. Comprueba estos ajustes en la documentación de tu proveedor.