Skip to Content

Authentication and authorization

OberonCMS uses Better Auth for email codes and sessions. Automatic signup is disabled. Users must exist in the CMS before they can sign in.

Setup

Add authPlugin from @oberoncms/core/auth to your server config. Put it after the database, send, and framework plugins. See Configuration for an example.

The auth plugin needs these Adapter capabilities:

  • getAuthDatabase and getAuthPlugins for Better Auth storage and extensions
  • sendVerificationRequest for email delivery
  • getRequestHeaders for request sessions

The database and framework plugins supply the required auth capabilities. See Database and Send for provider setup. Mount the framework HTTP handler at /cms/api/.

Environment variables

MASTER_EMAIL=admin@example.com AUTH_SECRET=your-generated-secret BASE_URL=https://your-site.example EMAIL_FROM=noreply@example.com

The installer generates AUTH_SECRET. Keep it private and stable across deployments. The auth plugin uses BASE_URL, then VERCEL_URL to select its base URL. Without either variable, Better Auth can use BETTER_AUTH_URL. Set BASE_URL to the production domain, including https://, for production builds and the deployed server. Preview deployments can use VERCEL_URL. OBERON_SITE_URL does not configure the current auth plugin. Set the credentials required by your email provider separately.

Initial admin

Bootstrap creates an admin user for MASTER_EMAIL if that email does not exist. It does not change an existing user’s role. This variable is not an emergency permission override. Use a secure mailbox for the initial admin.

Sign-in

  1. Open /cms/login.
  2. Enter an existing user’s email.
  3. Request a sign-in code.
  4. Enter the code or open the email link.

The development plugin writes verification details to the terminal instead of sending email. Production needs a configured send plugin.

Permissions

The default roles are admin and user. Admins can manage all CMS resources. Users can edit pages and images and read Site information. Unauthenticated requests can read pages.

CMS actions use can, will, and whoWill to enforce permissions. Persistence methods do not enforce these permissions themselves. Custom HTTP handlers must check access before they expose protected data or mutations.

Last updated on