- name
- nocobase-app-plugin-authentication
- description
- Build authentication requirements in a NocoBase 3 application: protect API routes and pages with the session, read and refresh the session in the browser, customize the login, registration and password pages, add sign-in methods such as social login, OIDC or a custom Better Auth plugin, enable official Better Auth plugins (device login for a CLI, bearer tokens, organizations, two-factor, passkeys) with the migration their tables need, manage account lifecycle from server code, and configure secrets, cookies and shared storage for deployment.
- metadata
- short-description: Build authentication into a NocoBase 3 application domain-owner: '@nocobase/app-plugin-authentication'
Authentication development
Use this Skill when an application built on @nocobase/app-plugin-authentication
needs anything about who the caller is: protecting a route or page, reading the
current user, changing the sign-in pages, adding a sign-in method, disabling
accounts, or preparing authentication for deployment.
Do not use it for what a signed-in user may do — that is
nocobase-app-plugin-authorization — or for the user administration page,
which is nocobase-app-plugin-users. Do not modify the plugin's own source,
migrations, or dist/; everything below is done in the application.
The plugin wraps Better Auth. Application configuration is Better Auth configuration, and every Better Auth plugin, social provider, and hook is available through it. Read the installed Better Auth version's documentation for option details; this Skill covers where those options go in a NocoBase application and what the plugin adds on top.
Enable an official Better Auth plugin before writing anything of your own: device login for a CLI (deviceAuthorization() with bearer()), organizations, two-factor and passkeys all exist upstream, and each needs only configuration, an application migration for its tables, and its UI. Enabling an official Better Auth plugin covers the rule, the schema check and the migration.
Public surfaces
Server, from @nocobase/app-plugin-authentication (the root entry is the
server entry) or @nocobase/app-plugin-authentication/server:
authenticationTokenresolves theAuthinstance:required(),optional(),getSession(headers),handler(request),signInUser(userId, request).AuthEnvtypes a Hono router whose routes readcontext.get('auth').userAdministrationServiceTokenresolvesUserAdministrationService:list,get,create,update,disable,enable,resetPassword,revokeSessions,withConnection; errors areUserAdministrationError.AuthConfigis Better Auth'sBetterAuthOptions, the type of the application's . User initialization configuration lives separately under .