Setup Login

Login in TrueForge is optional. Run it without auth for personal, local use, or connect an OIDC identity provider (Okta, Microsoft Entra ID, or any standard OIDC IdP) so your team signs in and Settings stay admin-only.

Choose your mode

Mode	When to use	What users see
No login (default)	Local `npx`, or a network you fully trust	No login screen; everyone is a single shared local admin
OIDC login	Hosted or shared team deployments	Sign-in with your IdP; each person is an `admin` or a `user`

Standalone / local mode ignores OIDC even if the variables are set. OIDC login applies to hosted deployments (Docker Compose, Helm, or Railway). Local mode is intended for personal use on your own machine — it is not a production or internet-facing setup. Please keep it on localhost; we cannot take responsibility for data loss or unauthorized access if it is used beyond that.

The default. Do not set any OIDC_* variables, run TrueForge as usual (Quickstart), and open the UI — there is no login screen, and Settings and chat are available immediately.

Use this only on localhost or behind network controls you trust. On a public host, anyone who can reach the server gets full admin access under one shared identity. The Helm chart defaults to this mode (configs.oidc.enabled: false) plus a well-known bundled Postgres password and Redis without auth — see the chart README before exposing a release.

Create a confidential (Web) OIDC application. Whatever the provider, you need:

Grant type Authorization Code (PKCE is also used)
Redirect URI: https://<trueforge-url>/api/v1/auth/callback, where <trueforge-url> is the public address of your TrueForge instance (the same value you set as PUBLIC_BASE_URL)
The users or groups allowed to sign in
An ID token claim carrying group/role membership, so TrueForge can tell admins from users

Public / SPA clients are not supported — TrueForge authenticates to the token endpoint with a client secret, so a SPA app fails token exchange with an invalid client secret error.

TrueForge speaks standard OIDC, so any IdP that issues ID tokens works. Pick your provider for exact steps:

Okta
Microsoft Entra ID (Azure AD)

1. Create the application

Applications → Create App Integration → OIDC → Web Application.
Grant type: Authorization Code.
Sign-in redirect URI: https://<trueforge-url>/api/v1/auth/callback.
Assign the users or groups who should sign in.
Copy the Client ID and Client secret.

The sign-out redirect URI is unused — logout only clears the local cookie.2. Configure the Authorization ServerPoint OIDC_ISSUER_URL at a custom Authorization Server, usually https://<your-okta-domain>/oauth2/default. On that server:

Access Policies — add 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).
Scopes — if you request groups, create a custom scope named groups (it is not built in on custom authorization servers).
Claims — add an ID token claim named to match OIDC_USER_ROLE_CLAIM (default groups): Groups value type, filtered as needed, included in the ID token.

3. Example values (group harness-admin → admin role)

OIDC_ISSUER_URL=https://integrator-XXXX.okta.com/oauth2/default
OIDC_CLIENT_ID=0oa...
OIDC_CLIENT_SECRET=...
OIDC_USER_REFERENCE_CLAIM=email
OIDC_USER_DISPLAY_NAME_CLAIM=name
OIDC_USER_ROLE_CLAIM=groups
OIDC_ADMIN_ROLE_VALUE=harness-admin
OIDC_SCOPES=openid,profile,email,groups

Plug these into the environment variables in the next step.

1. Register the application

Microsoft Entra admin center → App registrations → New registration.
Under Authentication → Add a platform → Web, add the redirect URI https://<trueforge-url>/api/v1/auth/callback.
Under Certificates & secrets → New client secret, create a secret and copy its value (not the ID).
From the Overview page, copy the Application (client) ID and Directory (tenant) ID.

2. Set the issuer and group claims

Issuer: use the v2.0 endpoint https://login.microsoftonline.com/<tenant-id>/v2.0.
Under Token configuration → Add groups claim, emit the groups claim in the ID token.

Entra emits group Object IDs (GUIDs) in the groups claim, not group names — so set OIDC_ADMIN_ROLE_VALUE to your admin group’s Object ID. To use a readable value instead, define an App role and point OIDC_USER_ROLE_CLAIM at the roles claim.

3. Example values (admin group Object ID → admin role)

OIDC_ISSUER_URL=https://login.microsoftonline.com/<tenant-id>/v2.0
OIDC_CLIENT_ID=<application-client-id>
OIDC_CLIENT_SECRET=...
OIDC_USER_REFERENCE_CLAIM=email
OIDC_USER_DISPLAY_NAME_CLAIM=name
OIDC_USER_ROLE_CLAIM=groups
OIDC_ADMIN_ROLE_VALUE=<admin-group-object-id>
OIDC_SCOPES=openid,profile,email

If the email claim is missing for some users, use preferred_username or oid for OIDC_USER_REFERENCE_CLAIM.

Set the server environment

Set all three required OIDC variables together — partial config fails startup — plus the public origin.

Variable	Required	Purpose
	Yes	Public origin users and the IdP see (no trailing path)
`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
`OIDC_USER_REFERENCE_CLAIM`	No (default `sub`)	Claim used as the user id for session ownership
`OIDC_USER_DISPLAY_NAME_CLAIM`	No (default `name`)	Claim used as the user’s display name
`OIDC_USER_ROLE_CLAIM`	No (default `groups`)	Claim inspected for admin membership
`OIDC_ADMIN_ROLE_VALUE`	No (default `admin`)	Exact string that grants `admin` (case-sensitive)
`OIDC_SCOPES`	No (default `openid,profile,email`)	Scopes for the authorize request
`OIDC_ALLOWED_EMAILS`	No	Comma-separated allowlist of exact emails and/or `` globs (e.g. `[email protected],@partner.com`). When set, only ID tokens whose `email` claim matches an entry may sign in. Empty / unset = unrestricted. Matching is case-insensitive.

How you pass these depends on how you run TrueForge:

Docker Compose
Helm

Add the variables to packages/trueforge/.env (the source Compose reads):

packages/trueforge/.env

PUBLIC_BASE_URL=https://trueforge.myorg.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_DISPLAY_NAME_CLAIM=name
OIDC_USER_ROLE_CLAIM=groups
OIDC_ADMIN_ROLE_VALUE=harness-admin
OIDC_SCOPES=openid,profile,email,groups
# Optional: restrict who can sign in (exact emails and/or * globs)
# [email protected],*@partner.com

Set server.publicBaseUrl and configs.oidc. Prefer clientSecret as valueFrom.secretKeyRef to a Kubernetes Secret you manage — the chart does not create Secrets for you:

values.yaml

server:
  publicBaseUrl: "https://trueforge.myorg.com"
configs:
  oidc:
    enabled: true
    issuerUrl: "https://integrator-XXXX.okta.com/oauth2/default"
    clientId: "0oa..."
    clientSecret:
      valueFrom:
        secretKeyRef:
          name: trueforge-oidc
          key: client-secret
    userReferenceClaim: email
    userDisplayNameClaim: name
    userRoleClaim: groups
    adminRoleValue: harness-admin
    scopes: "openid,profile,email,groups"
    # Optional: restrict who can sign in
    # allowedEmails: "[email protected],*@partner.com"
extraObjects:
  - apiVersion: v1
    kind: Secret
    metadata:
      name: trueforge-oidc
    type: Opaque
    stringData:
      client-secret: "..."

See the chart README for the full values shape.

Keep OIDC_CLIENT_SECRET in a secret store — never commit it to version control.

Open the UI — you should be redirected to your IdP login.
After login, confirm admins see Settings and non-admins do not.
If someone expected admin but got user, decode their ID token and check the role claim value (exact match, case-sensitive). Sign out and back in after any IdP claim change.

Roles: admin vs user

Each signed-in person maps to exactly one role, decided by the role claim in their ID token.

Role	Who	Can chat & use agents	Can change Settings
admin	Role claim contains `OIDC_ADMIN_ROLE_VALUE`	Yes	Yes — models, connectors, skills, sandbox
user	Everyone else who can sign in	Yes	No — Settings hidden

Two current limitations:

Session history is owner-only — admins are not global session superusers today.
The Agent Library is shared — agents created by anyone are visible to everyone on the instance.

To call the HTTP API or SDK against a server with login enabled, pass an ID token — see Get a token and connect.

Troubleshooting

Symptom	Likely cause
`no_matching_policy` / policy evaluation failed	Authorization Server access policy does not include this client, grant, scopes, or user (Okta)
`You are not allowed to access this app`	User not assigned to the application, or the app sign-on policy denies them
`invalid client secret`	App is SPA/public — recreate it as a Web (confidential) app with a client secret
Blank authorize screen when requesting `groups`	Custom Authorization Server is missing the `groups` scope and/or ID-token groups claim (Okta)
Login works but everyone is `role: "user"`	Groups/roles claim missing from the ID token, wrong claim name, or admin value mismatch (case-sensitive)
SDK returns `401`	OIDC is on and the request has no ID token or session cookie
Sign-in fails with `login_failed` / APIs return `401` after allowlist rollout	Caller’s `email` claim is outside `OIDC_ALLOWED_EMAILS`, or the ID token has no `email` claim while an allowlist is set. Failures stay generic so the allowlist is not disclosed.

Security checklist

Store OIDC_CLIENT_SECRET in a secret manager; never commit it.
Do not expose a no-OIDC deployment on the public internet.
Register the exact callback URL your users hit (scheme + host).

Getting Started

TrueForge Harness

SDK

UI Chat

Project

Choose your mode

Roles: admin vs user

Troubleshooting

Security checklist

​Choose your mode

​Option A — leave login off

​Option B — enable OIDC login

​Roles: admin vs user

​Troubleshooting

​Security checklist

Choose your mode

Option A — leave login off

Option B — enable OIDC login

Roles: admin vs user

Troubleshooting

Security checklist