---
title: Authentication & RBAC
description: Protect your documentation with authentication and control page access using role-based permissions.
---

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:

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

```
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 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.

=== "Navigation filtering"

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

=== "Route protection"

Even if someone knows the URL, CamelMind blocks access unless the user has the required role.

===

<Callout type="important">
Hiding a page from the navigation is not the security mechanism—CamelMind also validates permissions before rendering the page.
</Callout>


---

## 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.

<Callout type="warning">
Never deploy with `provider: "dev-mock"`. It bypasses real authentication and is intended for local development only.
</Callout>