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.mdxnew file mode 100644index 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.mdxnew file mode 100644index 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.jsonindex 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.mdxindex 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 DockerSubagents, deferred tool loading, code mode, large-result offloading, and compaction — keep context leanautomatically.</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>