Guides / Sign-in of its own
Guides / sign-in
Sign-in of its own
People, passwords, passkeys, two-step codes, single sign-on and invitations, for apps without a login.
Most apps already have a login and pass it in with resolveUser. When yours does not (or for the standalone server), the CMS can sign people in itself.
import { createAuth } from "@mainsoft/agent-cms/auth";
import { createCmsHandler } from "@mainsoft/agent-cms/http";
const auth = createAuth({
cms,
origin: "https://cms.example.com", // passkeys and mail links use it
appName: "Example CMS",
sendMail: async ({ to, subject, text }) => { /* Resend, SES, SMTP… */ },
oidc: { issuer: "https://accounts.google.com", clientId, clientSecret, label: "Google", allowedDomains: ["example.com"] },
});
export const handler = createCmsHandler({ cms, auth });Nothing new goes into the database schema: people, sessions, passkeys and one-time links live in cms_records.
The first admin#
While nobody has an account, the server prints a setup code where it logs (valid for 15 minutes; a new one comes with the next request after that):
[agent-cms] No one can sign in yet. Open https://cms.example.com/admin/setup and enter the setup code K7M2-9XQ4 (valid for 15 minutes).POST /auth/setup with the code makes the first admin. After that, setup is closed.
Ways to sign in#
| Password | At least 12 characters; common and guessable ones are refused (the 10,000 most common, the email name, runs like abcdefgh…). Hashed with scrypt (N=2^17, r=8, p=1); weaker hashes are replaced at the next sign-in. Turn passwords off with passwords: false. |
| Passkey | WebAuthn without a library: ES256, EdDSA, RS256; no email typed first. A passkey counts as two factors. |
| Two-step code | Any authenticator app (TOTP, RFC 6238), a QR code on setup, ten recovery codes that work once. "Trust this device" skips the code for 30 days. |
| Single sign-on | OpenID Connect with PKCE: Google, Microsoft Entra, Okta, Keycloak, Auth0… allowedDomains limits who may sign in (and lets them in without an invitation, unless autoCreate: false). |
Sessions#
- An
HttpOnly,SameSite=Laxcookie; on HTTPS it is__Host-cms_sessionandSecure. Only a hash of it is stored. - 30 days from the last use, at most 90 days.
- Ten wrong passwords for one email in 15 minutes pause password sign-in for that email (passkeys and SSO still work); fifty tries from one address in 15 minutes pause that address.
- Changing the password ends your other sessions; a reset ends all of them; switching someone off or taking admin away ends theirs at once.
- Making or rotating API keys, turning two-step off, removing a passkey, and switching people off or making them admin need a confirmation in the last 10 minutes (
POST /auth/reauth, or a passkey). - Requests that change something must come from the CMS's own page (login CSRF is refused).
People#
Admins invite by email (POST /users/invite, links valid for 7 days, with a role and optionally as admin). Without sendMail the answer has the links to copy. The policy requireMfa makes everyone set up a passkey or two-step codes before anything else. At least one admin always stays.
Every step is in the audit log (auth.* actions).
From code#
await auth.createUser({ email: "park@example.com", name: "Park", password, isAdmin: true });
const link = await auth.resetLink("park@example.com");The routes are listed under "sign-in", "account" and "people" in /openapi.json.