CamelMind includes built-in support for authentication and role-based access control (RBAC).

Authentication identifies who a user is, while RBAC determines which pages they're allowed to access.

Authentication is disabled by default, so a new CamelMind site is completely public until you enable it.

Choose an authentication mode

CamelMind supports three authentication modes.

Mode	Description
Public (default)	Anyone can access every page.
Partial login	Public pages remain accessible, but users can sign in to access protected pages.
Required login	All pages require authentication.

Protected documentation pages automatically restrict access to related features, such as viewing the page or downloading its Markdown source.

Offline and PDF downloads follow your site's authentication settings automatically. If authentication is enabled, only authenticated users can download these artifacts. If authentication is disabled, the downloads are publicly accessible.

Enable authentication

Authentication is configured in camelmind.config.ts.

typescript

auth: {
  enabled: true,
  requireLogin: true,
  provider: "oidc",

  oidc: {
    issuer: process.env.OIDC_ISSUER ?? "",
    clientId: process.env.OIDC_CLIENT_ID ?? "",
    clientSecret: process.env.OIDC_CLIENT_SECRET ?? "",
    rolesClaim: "realm_access.roles",
    roleMapping: {},
  },

  publicPaths: [
    "/",
    "/home",
    "/login",
    "/api/auth",
  ],
}

Most authentication settings are supplied through environment variables.

bash

CAMELMIND_AUTH_ENABLED=true
CAMELMIND_AUTH_REQUIRE_LOGIN=true
CAMELMIND_AUTH_PROVIDER=oidc

OIDC_ISSUER=https://auth.example.com/realms/my-realm
OIDC_CLIENT_ID=my-docs
OIDC_CLIENT_SECRET=super-secret

SESSION_SECRET=your-random-session-secret

Configure your identity provider

CamelMind works with any OpenID Connect (OIDC) compatible identity provider, including:

Auth0
Okta
Microsoft Entra ID (Azure AD)
Amazon Cognito
Any standards-compliant OIDC provider

Your identity provider should be configured to:

Register CamelMind as an application.
Set the redirect URI to:

https://your-site.example.com/api/auth/callback

Include user roles in the ID token or access token.

CamelMind reads user roles from the claim specified by rolesClaim.

For example, Keycloak stores realm roles in:

typescript

rolesClaim: "realm_access.roles"

Map provider roles

Your identity provider's role names don't have to match the role names used in your documentation.

Use roleMapping to translate them.

typescript

roleMapping: {
  "Realm_Admin": "admin",
  "Realm_Vendor": "vendor",
}

This lets you keep your navigation configuration simple while adapting to existing enterprise role names.

Restrict pages

Access is controlled directly in nav.yml.

yaml

- label: Admin Dashboard
  slug: /admin/dashboard
  file: content/admin/dashboard.mdx
  roles: [admin]

- label: Vendor Portal
  slug: /vendor
  file: content/vendor.mdx
  roles: [vendor]

- label: Getting Started
  slug: /getting-started
  file: content/getting-started.mdx
  roles: []

The roles field determines who can access each page.

`roles`	Access
`[]`	Any authenticated user
`["admin"]`	Administrators only
`["vendor","admin"]`	Vendors or administrators

When authentication is disabled, every page is treated as public regardless of the roles setting.

How access is enforced

CamelMind protects documentation in two ways.

Pages the current user cannot access are automatically hidden from the navigation.

Important

Hiding a page from the navigation is not the security mechanism—CamelMind also validates permissions before rendering the page.

Public pages

When requireLogin is enabled, pages listed in publicPaths remain accessible without signing in.

typescript

publicPaths: [
  "/",
  "/home",
  "/login",
  "/api/auth",
]

This is commonly used for:

Home pages
Login pages
Marketing pages
Authentication endpoints

Local development

During development you can use the built-in mock authentication provider.

typescript

auth: {
  enabled: true,
  requireLogin: false,
  provider: "dev-mock",
}

The mock provider simulates a signed-in user without requiring an external identity provider.

This makes it easy to test navigation, protected pages, and role-based access while developing locally.

Warning

Never deploy with provider: "dev-mock". It bypasses real authentication and is intended for local development only.

Authentication & RBAC