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:
getAuthDatabaseandgetAuthPluginsfor Better Auth storage and extensionssendVerificationRequestfor email deliverygetRequestHeadersfor 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.comThe 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
- Open
/cms/login. - Enter an existing user’s email.
- Request a sign-in code.
- 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.