Authentication & RBAC

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

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

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

Choose an authentication mode with enabled and requireLogin

CamelMind determines the authentication mode from the auth.enabled and auth.requireLogin settings.

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

Offline and PDF downloads follow your site's authentication settings automatically. When you enable authentication, only authenticated users can download these artifacts. When you disable authentication, any user can publicly access the downloads.

How to enable authentication in camelmind.config.ts

Enable authentication by setting auth.enabled: true in camelmind.config.ts. Set auth.requireLogin: true when users must sign in to access protected documentation pages.

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",
  ],
}

You supply most authentication settings through environment variables.

CAMELMIND_AUTH_ENABLED=true
CAMELMIND_AUTH_REQUIRE_LOGIN=true
CAMELMIND_AUTH_PROVIDER=oidc

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

SESSION_SECRET=your-random-session-secret

How to configure an OIDC identity provider

Configure an OpenID Connect (OIDC) identity provider to authenticate CamelMind users.

CamelMind works with any OIDC-compatible identity provider, including:

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

Configure your identity provider to:

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

[https://your-site.example.com/api/auth/callback](https://your-site.example.com/api/auth/callback)

3. Include user roles in the ID token or access token.

CamelMind reads user roles from the token claim specified by rolesClaim.

How to configure rolesClaim for provider roles

Set rolesClaim to the token claim that contains the user's roles. CamelMind reads roles from this claim before applying roleMapping.

For example, Keycloak stores realm roles in:

rolesClaim: "realm_access.roles"

The complete OIDC configuration can look like this:

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

How to map identity provider roles with roleMapping

Use roleMapping to translate role names from your identity provider into the CamelMind role names used in nav.yml.

For example, if your identity provider provides Realm_Admin and Realm_Vendor roles, map them to the CamelMind roles admin and vendor:

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

The mapping works from the identity provider's role name to the CamelMind role name:

CamelMind uses the mapped role names when evaluating the roles values defined in nav.yml.

How to restrict documentation pages with roles

Use the roles field in nav.yml to specify which CamelMind roles can access a documentation page.

- 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: []

CamelMind compares the roles assigned to the authenticated user with the roles defined for each page.

Disabling authentication treats every page as public, even if you configure the roles setting.

How CamelMind enforces authentication and RBAC access

CamelMind enforces documentation access in two ways: navigation filtering and route protection.

How to allow unauthenticated access with publicPaths

You can use publicPaths to keep specific paths accessible without signing in when you enable requireLogin.

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

Common public paths include:

• Home pages
• Login pages
• Marketing pages
• Authentication endpoints

When you enable requireLogin, users can still access any pages listed in publicPaths without authenticating.

How to test authentication locally with dev-mock

Use the built-in dev-mock authentication provider to test authentication and RBAC locally without configuring an external identity provider.

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

The mock provider simulates a signed-in user so you can test navigation, protected pages, and role-based access during local development.