Skip to content

The open-source agent harness - the runtime layer that turns an LLM into a working agent.

add docs for authn and authz (#139)

Heer Ambavic1d98f9e2344
diff --git a/docs/authentication/okta.mdx b/docs/authentication/okta.mdx
new file mode 100644
index 000000000..30d26bdf7
--- /dev/null
+++ b/docs/authentication/okta.mdx
@@ -0,0 +1,86 @@
+---
+title: 'Okta'
+sidebarTitle: 'Okta'
+description: 'Configure Okta as the OIDC identity provider for TrueForge.'
+---
+
+See [Authentication](/authentication/overview) for shared OIDC concepts, roles, and Helm patterns. This page covers Okta-specific setup.
+
+## Create the app
+
+1. Applications → **Create App Integration** → OIDC → **Web Application**.
+2. Grant type: **Authorization Code**.
+3. Sign-in redirect URI: `https://<your-public-host>/api/v1/auth/callback`.
+4. Assign users or groups who should sign in.
+5. Copy **Client ID** and **Client secret**.
+
+Use a **Web** (confidential) app with a client secret. A SPA / `PublicClientApp` fails token exchange with invalid client secret — TrueForge always authenticates to the token endpoint with the client secret.
+
+Sign-out redirect URI is unused by TrueForge (logout only clears the local cookie). Set the app origin if Okta requires a value.
+
+## Authorization Server
+
+Point `OIDC_ISSUER_URL` at a **custom** Authorization Server, usually `https://<your-oidc-domain>/oauth2/default`. On that server:
+
+1. **Access Policies** — a rule that includes this Web client, grant type Authorization Code, your users, and the scopes you request (`openid`, `profile`, `email`, and `groups` if used).
+2. **Scopes** — if you request `groups`, create a custom scope named `groups` (it is not built-in on custom authorization servers).
+3. **Claims** — add an **ID token** claim named to match `OIDC_USER_ROLE_CLAIM` (default `groups`): Groups value type, filter as needed, include in the ID token (not access token only).
+
+## Example config
+
+Group `harness-admin` → admin role:
+
+```bash
+PUBLIC_BASE_URL=https://trueforge.example.com
+OIDC_ISSUER_URL=https://integrator-XXXX.okta.com/oauth2/default
+OIDC_CLIENT_ID=0oa...
+OIDC_CLIENT_SECRET=...
+OIDC_USER_REFERENCE_CLAIM=email
+OIDC_USER_ROLE_CLAIM=groups
+OIDC_ADMIN_ROLE_VALUE=harness-admin
+OIDC_SCOPES=openid,profile,email,groups
+```
+
+Helm: set `server.publicBaseUrl` for the callback origin. Pass `OIDC_*` through `server.extraEnv` (or `extraEnvFrom`); keep the client secret in a Kubernetes Secret:
+
+```yaml
+server:
+ publicBaseUrl: "https://trueforge.example.com"
+ extraEnv:
+ - name: OIDC_ISSUER_URL
+ value: "https://integrator-XXXX.okta.com/oauth2/default"
+ - name: OIDC_CLIENT_ID
+ value: "0oa..."
+ - name: OIDC_CLIENT_SECRET
+ valueFrom:
+ secretKeyRef:
+ name: truefoundry-utils-oidc
+ key: client-secret
+ - name: OIDC_USER_REFERENCE_CLAIM
+ value: email
+ - name: OIDC_USER_ROLE_CLAIM
+ value: groups
+ - name: OIDC_ADMIN_ROLE_VALUE
+ value: harness-admin
+ - name: OIDC_SCOPES
+ value: openid,profile,email,groups
+extraObjects:
+ - apiVersion: v1
+ kind: Secret
+ metadata:
+ name: truefoundry-utils-oidc
+ type: Opaque
+ stringData:
+ client-secret: "..."
+```
+
+## Troubleshooting
+
+| Symptom | Likely cause |
+| ------- | ------------ |
+| `no_matching_policy` / Policy evaluation failed | Access Policy on the Authorization Server does not include this client, grant, scopes, or user |
+| `You are not allowed to access this app` | User not assigned to the Okta application, or app sign-on policy denies them |
+| `invalid client secret` | App is SPA/public; recreate as **Web** with a client secret |
+| Stuck blank authorize URL with `groups` scope | Custom AS missing `groups` scope and/or ID-token groups claim |
+| Login works but `role: "user"` | Groups claim missing from ID token, wrong claim name, or admin value mismatch (case-sensitive) |
+| SDK gets 401 | OIDC on and no `Authorization: Bearer` / cookie |
diff --git a/docs/authentication/overview.mdx b/docs/authentication/overview.mdx
new file mode 100644
index 000000000..d6390a880
--- /dev/null
+++ b/docs/authentication/overview.mdx
@@ -0,0 +1,155 @@
+---
+title: 'Authentication'
+sidebarTitle: 'Overview'
+description: 'OIDC login with identity providers, admin vs user roles, Bearer tokens for the SDK, and what happens when auth is disabled.'
+---
+
+TrueForge authentication is optional and identity-provider–driven. When OIDC is configured, every protected API call must present a valid ID token (browser cookie or `Authorization: Bearer`). When it is not, the server runs with a fixed local admin identity — useful for local mode and trusted networks, not for shared production.
+
+## Modes at a glance
+
+| Mode | When | Who you are | API access |
+| ---- | ---- | ----------- | ---------- |
+| **No OIDC** | `OIDC_*` unset (or standalone / local mode) | Fixed user `trueforge-default` with role `admin` | No login required |
+| **OIDC enabled** | `OIDC_ISSUER_URL`, `OIDC_CLIENT_ID`, and `OIDC_CLIENT_SECRET` all set | Claim-mapped `userRef` + `admin` or `user` | Cookie or Bearer ID token required |
+
+All OIDC variables must be set together, or all left unset. Partial configuration fails startup.
+
+Standalone / local mode (`STANDALONE=true`) ignores OIDC even if env vars are present.
+
+## No auth
+
+This is the default for local development and for hosted deploys that never set `OIDC_*`.
+
+- There is **no login screen**. The UI and API treat every caller as the same identity.
+- That identity is **`trueforge-default`** with role **`admin`**.
+- Settings (model providers, MCP servers, skills, sandbox) are open to anyone who can reach the server.
+- Session ownership still uses `created_by`, but every request shares the same `userRef`, so there is no per-person isolation.
+
+Use this only on localhost or behind network controls you trust. For a shared team deployment, enable OIDC.
+
+## Enabling OIDC
+
+Set on the server (env, Compose `.env`, or Helm `server.extraEnv`):
+
+| Variable | Required | Default | Purpose |
+| -------- | -------- | ------- | ------- |
+| `OIDC_ISSUER_URL` | yes* | — | IdP issuer (discovery at `/.well-known/openid-configuration`) |
+| `OIDC_CLIENT_ID` | yes* | — | OIDC client ID |
+| `OIDC_CLIENT_SECRET` | yes* | — | OIDC client secret (confidential / Web client) |
+| `PUBLIC_BASE_URL` | yes | — | Public origin used to build the callback URL |
+| `OIDC_USER_REFERENCE_CLAIM` | no | `sub` | Claim used as `userRef` (session ownership) |
+| `OIDC_USER_ROLE_CLAIM` | no | `groups` | Claim inspected for admin membership |
+| `OIDC_ADMIN_ROLE_VALUE` | no | `admin` | Exact string that grants `admin` (case-sensitive) |
+| `OIDC_SCOPES` | no | `openid,profile,email` | Comma-separated scopes for the authorize request |
+
+\*Required only when enabling OIDC; otherwise leave all three unset.
+
+Also set `PUBLIC_BASE_URL` to the origin users and the IdP see, for example `https://trueforge.example.com` (no trailing path). In Helm that is the first-class value `server.publicBaseUrl`. The redirect URI registered with the IdP must be:
+
+```text
+{PUBLIC_BASE_URL}/api/v1/auth/callback
+```
+
+OIDC env vars are not first-class Helm values yet — pass them through `server.extraEnv` or `server.extraEnvFrom`, and keep the client secret in a Kubernetes Secret (for example via `extraObjects`).
+
+### How credentials are sent
+
+The UI stores the ID token in an HttpOnly `id_token` cookie after login. `POST /api/v1/auth/logout` clears that cookie (local logout only — no IdP end-session redirect). `GET /api/v1/auth/me` returns the mapped identity.
+
+Login requests the reference and role claims as **essential** in the ID token. If the IdP cannot produce them, login fails instead of silently treating the user as non-admin.
+
+### API and SDK (Bearer)
+
+The same ID token is also accepted as:
+
+```http
+Authorization: Bearer <id_token>
+```
+
+If both a Bearer token and the cookie are present, **Bearer wins**.
+
+TypeScript SDK example:
+
+```typescript
+import { TrueForge } from "trueforge-sdk";
+
+const client = new TrueForge({
+ baseUrl: "https://trueforge.example.com",
+ headers: {
+ Authorization: `Bearer ${idToken}`,
+ },
+});
+```
+
+There is no first-class device/client-credentials flow yet. Callers must obtain an ID token from the IdP (or reuse one from a browser session). Refresh is the caller's responsibility.
+
+<Warning>
+ Keep ID token lifetimes short at the IdP (minutes, not days). The same JWT unlocks the API whether it arrives as a cookie or `Authorization: Bearer`, so a long-lived token is a long-lived credential.
+</Warning>
+
+## Roles: admin vs user
+
+Every authenticated principal is mapped to:
+
+```ts
+{ userRef: string; role: "admin" | "user" }
+```
+
+- **`userRef`** — from `OIDC_USER_REFERENCE_CLAIM` (default `sub`). Used as `created_by` on sessions and for ownership checks.
+- **`role`** — `admin` if the role claim’s values **include** `OIDC_ADMIN_ROLE_VALUE` (exact, case-sensitive); otherwise `user`.
+
+The role claim may be a string or an array of strings (typical for Okta `groups`).
+
+### What each role can do
+
+| Capability | `admin` | `user` |
+| ---------- | ------- | ------ |
+| Chat, sessions, turns, agents, models list, MCP authorize (user flows) | yes | yes |
+| See / change **Settings** (`/api/v1/settings/*` — providers, connectors, skills, sandbox) | yes | no |
+| Access another user’s sessions | no | no |
+
+Admins are **not** global session superusers today: session read/update/delete is still owner-only. The UI hides Settings for non-admins.
+
+Without OIDC, `isAdmin` is always true (the fixed local identity is admin), so settings stay available.
+
+## Identity providers
+
+TrueForge speaks standard OIDC (authorization code + PKCE) against any IdP that issues ID tokens. Provider-specific setup differs; the server only needs a working issuer, confidential client, redirect URI, and the claims you map for `userRef` / admin.
+
+**Common requirements for any IdP:**
+
+- **Confidential (Web) client** with a client secret — public/SPA clients are not supported
+- Grant type **Authorization Code** (server also sends PKCE)
+- Redirect URI `{PUBLIC_BASE_URL}/api/v1/auth/callback`
+- ID token includes the reference claim and role claim you configured (requested as essential at login)
+- Users who should sign in are assigned / allowed by the IdP
+
+Provider guides:
+
+- [Okta](/authentication/okta)
+
+### Verify
+
+After login with any provider:
+
+```bash
+curl -s -H "Cookie: id_token=..." https://trueforge.example.com/api/v1/auth/me
+# or
+curl -s -H "Authorization: Bearer ..." https://trueforge.example.com/api/v1/auth/me
+```
+
+Expected shape:
+
+```json
+{ "type": "oidc-connected", "email": "[email protected]", "role": "admin" }
+```
+
+(`email` here is the mapped `userRef` from `OIDC_USER_REFERENCE_CLAIM`.)
+
+If `role` is `user` but you expect admin, decode the ID token and confirm the role claim contains exactly `OIDC_ADMIN_ROLE_VALUE`. Re-login after changing IdP claims; an old cookie will not pick up new claims.
+
+## Security notes
+
+- Prefer Kubernetes Secrets (or `extraObjects` Secret) for `OIDC_CLIENT_SECRET`; avoid committing secrets in values files when you can.
+- Disabling OIDC on a publicly reachable host effectively grants every caller admin settings access under one shared identity.
diff --git a/docs/docs.json b/docs/docs.json
index c71a8c3d5..75f2f875a 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -33,7 +33,15 @@
"groups": [
{
"group": "Getting Started",
- "pages": ["introduction", "quickstart", "evaluation"]
+ "pages": [
+ "introduction",
+ "quickstart",
+ {
+ "group": "Authentication",
+ "pages": ["authentication/overview", "authentication/okta"]
+ },
+ "evaluation"
+ ]
},
{
"group": "Capabilities",
diff --git a/docs/introduction.mdx b/docs/introduction.mdx
index 699a2647f..6d9201df5 100644
--- a/docs/introduction.mdx
+++ b/docs/introduction.mdx
@@ -123,6 +123,9 @@ Like Claude's managed agents: one deployment the whole company uses, via Docker
Subagents, deferred tool loading, code mode, large-result offloading, and compaction — keep context lean
automatically.
</Card>
+ <Card title="Authentication" icon="lock" href="/authentication/overview">
+ Optional OIDC with your IdP, admin vs user roles, Bearer tokens for the SDK, and the no-auth local default.
+ </Card>
<Card title="Human in the Loop" icon="shield-check" href="/human-in-the-loop">
Pause sensitive tool calls and require explicit user approval before execution.
</Card>