> For a complete documentation index, see /llms.txt. To read any public page as Markdown, append .md to the URL.

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.

| `enabled` | `requireLogin` | Behavior |
| --- | --- | --- |
| `false` | — | Public. Anyone can access every page. |
| `true` | `false` | Partial login. Public pages remain accessible, but users can sign in to access protected pages. |
| `true` | `true` | Required login. Users must sign in to access pages unless you list the page in `publicPaths`. |

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.

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

You supply most authentication settings through environment variables.

```bash
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:

```text
[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:

```typescript
rolesClaim: "realm_access.roles"
```

The complete OIDC configuration can look like this:

```typescript
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`:

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

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

| Identity provider role | CamelMind role |
| --- | --- |
| `Realm_Admin` | `admin` |
| `Realm_Vendor` | `vendor` |

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.

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

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

| `roles` | Access |
| --- | --- |
| `[]` | Public page |
| `["admin"]` | Users with the `admin` role |
| `["vendor","admin"]` | Users with either the `vendor` or `admin` role |

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.

=== "Navigation filtering"

CamelMind automatically hides pages from the navigation when the current user does not have the required role.

=== "Route protection"

CamelMind checks the user's permissions before rendering a protected page. Knowing the page URL does not bypass 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>

===

---

## How to allow unauthenticated access with publicPaths

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

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

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

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