nocobase-app-plugin-authentication

Implement session-based authentication, sign-in methods, and account lifecycle in NocoBase 3 applications.

9|3|Updated Aug 14, 2026
One-click install
npx skills add https://github.com/nocobase/nocobase3 --skill nocobase-app-plugin-authentication-nocobase
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: nocobase-app-plugin-authentication
Source: https://github.com/nocobase/nocobase3/tree/main/packages/plugins/app-plugin-authentication/skills/nocobase-app-plugin-authentication
Command: npx skills add https://github.com/nocobase/nocobase3 --skill nocobase-app-plugin-authentication-nocobase

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires better-auth, hono, @nocobase/app-plugin-authentication, @nocobase/app-server, @nocobase/db, and includes references (resource) components.

What problem does it solve? Building authentication into a NocoBase 3 application requires coordinating Better Auth configuration, route protection, session handling, sign-in pages, and deployment secrets across server and client code. This Skill guides that work so routes are actually protected, sessions behave correctly, and new sign-in methods are added without breaking the database schema. ## Core Features & Use Cases - Route and page protection: Apply auth.required() and auth.optional() middleware to Hono API routes, and gate browser pages with RequiredAuthentication, GuestAuthentication, and route auth modes. - Sign-in methods: Add social providers, generic OAuth/OIDC, magic links, or a custom Better Auth plugin for proprietary protocols, including the required application migrations and client entry points. - Account lifecycle and deployment: Disable or reset accounts via UserAdministrationService, configure password-reset email, and prepare secrets, cookies, public origin, and shared cache storage for production. - Use Case: You need to add GitHub and OIDC login to a NocoBase app. The Skill walks you through registering the providers in server/config/auth.ts, adding the client plugin, wiring SSO buttons into the login page, and verifying callback URLs under a sub-path deployment. ## Quick Start Ask the assistant to protect an API route with authentication or to add a new sign-in method such as GitHub OAuth to your NocoBase application.

Frequently Asked Questions about nocobase-app-plugin-authentication

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I protect an API route in a NocoBase application?▼

Resolve the Auth instance with authenticationToken and apply auth.required() middleware to the Hono route. Anonymous requests receive 401 with code UNAUTHORIZED, and authenticated handlers read the session from context.get('auth').

How do I add social login or OIDC to a NocoBase app?▼

Register the provider in server/config/auth.ts using socialProviders for natively supported platforms or the genericOAuth Better Auth plugin for any OAuth 2.0/OIDC server. Add the matching client plugin in client/config/auth.ts and an SSO button that calls client.signIn.social or signIn.oauth2.

Does configuring a Better Auth plugin create its database tables?▼

No. Configuring a plugin changes nothing in the database, so you must write an application migration in database/migrations/ creating every model and field the plugin's schema requires. Never run Better Auth's schema generation or edit the plugin's own migrations.

Why is my route still public after mounting it under /api?▼

Mounting under /api authenticates nothing; a route is protected only when auth.required() is applied to it. Browser guards are navigation only, and the server authenticates every request independently.

How do I disable a user account from server code?▼

Resolve userAdministrationServiceToken and call disable(userId). This sets disabledAt, deletes all sessions, disconnects realtime connections, and causes sign-in to fail with 403 ACCOUNT_DISABLED.

When should I write a custom Better Auth plugin instead of using built-in providers?▼

Write one only when the identity platform uses a protocol Better Auth cannot express, such as a proprietary ticket or enterprise handshake. Standard OAuth, OIDC, magic links, and passkeys should use existing providers or official plugins first.