Skip to Content
DevelopersPluginsAuth

Authentication and Authorization

OberonCMS uses an auth plugin based on Auth.js for sign-in, session handling, and role-aware access control.

Overview

The built-in auth integration provides:

  • Email-based one-time code login
  • Session management through Auth.js
  • Role-aware user context (admin and user)
  • Route handlers mounted at /cms/api/auth

Enable auth

Add the auth plugin to your adapter setup.

oberon/adapter.ts
import { initOberon } from "@oberoncms/core/adapter"
import { authPlugin } from "@oberoncms/core/auth"
import { plugin as developmentPlugin } from "@oberoncms/plugin-development"
import { plugin as tursoPlugin } from "@oberoncms/plugin-turso"
import { plugin as tailwindPlugin } from "@oberoncms/plugin-tailwind"
 
import { config } from "./config"
 
export const { adapter, handler } = initOberon({
  config,
  plugins: [developmentPlugin, tursoPlugin, tailwindPlugin, authPlugin],
})

Required adapter capabilities

The auth flow relies on your database plugin implementing Auth.js adapter operations (sessions, users, verification tokens, and account links).

See:

Email login flow

  1. A user enters an email at the CMS login screen
  2. Auth requests a verification token
  3. Oberon calls sendVerificationRequest on your send adapter
  4. User completes sign-in and receives a session

In development mode, verification details are logged by the development plugin instead of being sent.

Routes

Auth routes are served under:

  • /cms/api/auth/*

Sign-in page is configured as:

  • /cms/login

After sign-in, users are redirected to:

  • /cms

Roles

Oberon supports two built-in roles:

  • admin
  • user

Role information is attached to the session user and used by adapter-level permission checks.

Master admin email

You can configure a master admin email with environment variable:

MASTER_EMAIL=admin@example.com

When set, this email is treated as an admin override in the auth plugin.

Restrict access to this environment variable and use a secure mailbox for the master admin email.

Environment variables

Typical auth-related variables:

MASTER_EMAIL=admin@example.com
EMAIL_FROM=noreply@example.com
SEND_SECRET=your-send-provider-secret
OBERON_SITE_URL=http://localhost:3000

Your chosen database and send plugins may require additional variables.

Production checklist

  • Configure a production database adapter (Turso/PostgreSQL/custom)
  • Configure a production send adapter
  • Set MASTER_EMAIL for emergency admin access
  • Set the correct site URL environment variable for your runtime environment
  • Verify sign-in flow on your deployed domain
Last updated on
PluginsCustom