Secure Taskbay with OIDC

Use OIDC whenever other people can reach the console. Local development identity makes every caller an administrator. The application supports authorization code with S256 PKCE, openid profile, RS256-signed ID tokens and client_secret_post. It does not map provider groups or roles to application permissions.

1. Register a confidential web clientCopy Anchor Link

In your identity provider, register the exact callback:

https://console.example.com/api/auth/callback

Enable authorization code, PKCE S256, RS256 ID-token signing and client authentication by client_secret_post. The issuer must publish OIDC discovery and its signing keys over HTTPS. This is the supported profile; provider-specific integration has not been verified upstream.

Taskbay uses its configured origin for redirects. Host and forwarded headers cannot change it. HTTPS is required because the login and session cookies are Secure and use the __Host- prefix.

2. Configure the application processesCopy Anchor Link

Generate an independent random key for the login flow:

openssl rand -hex 32

Supply the following through your service environment or a protected environment file. Every REPLACE_... value is a placeholder.

NODE_ENV=production
A2A_AUTH_MODE=oidc
A2A_ALLOW_DEVELOPMENT_AUTH=false
A2A_AUTH_ORIGIN=https://console.example.com
A2A_OIDC_ISSUER=https://identity.example.com
A2A_OIDC_CLIENT_ID=REPLACE_WITH_CLIENT_ID
A2A_OIDC_CLIENT_SECRET=REPLACE_WITH_CLIENT_SECRET
A2A_AUTH_ORGANIZATION_SLUG=acme
A2A_AUTH_FLOW_KEY=REPLACE_WITH_64_HEX_CHARACTERS
A2A_AUTH_SESSION_SECONDS=28800

A2A_DATABASE_PROFILE=postgresql
A2A_DATABASE_URL=postgresql://taskbay:REPLACE_WITH_PASSWORD@db.internal:5432/taskbay
A2A_AUTO_MIGRATE=false
A2A_ARTIFACT_DATA_DIR=/var/lib/taskbay/artifacts
A2A_COMMAND_WORKER_MODE=external
A2A_ALLOWED_AGENT_ORIGINS=https://agents.example.com

The flow key must contain exactly 64 hex characters and be shared across web replicas. It is separate from the credential vault key and the push signing key. Rotating it invalidates login attempts in progress. The session duration must be an integer from 60 to 86400 seconds; the default is eight hours.

Install dependencies and build before loading NODE_ENV=production into an installation shell: the operator scripts need development dependencies such as tsx. Both web and workers need the database, storage and outbound policy configuration. Explicitly set NODE_ENV=production for workers; the tsx worker entry point does not set it for you. Agent credentials need a separate vault key ring, covered in the protected-agent walkthrough.

3. Migrate and provision the first administratorCopy Anchor Link

Export the environment in the shell used for operator commands. auth:provision and the database commands do not load .env.local themselves.

npm run db:migrate
npm run auth:provision -- --issuer https://identity.example.com --subject REPLACE_WITH_EXACT_SUB --organization acme --name "First administrator" --role admin

Use the exact sub claim from your provider's user record; an email address is not a substitute unless it actually is the subject. The issuer must match A2A_OIDC_ISSUER, and --organization must match A2A_AUTH_ORGANIZATION_SLUG. A person is admitted only if their local user and membership are enabled. Successful provider authentication alone never creates membership.

With PostgreSQL, provisioning can run online. With PGlite, stop the web process and add --offline-pglite; production with separate workers requires PostgreSQL.

4. Start web and workers behind HTTPSCopy Anchor Link

Run these as supervised processes using the same deployment configuration:

npm start -- -H 127.0.0.1

npm run worker:tasks

Forward public HTTPS through your reverse proxy to the web process on port 3002. Preserve support for live event streams. The production guide explains the required shared artifact directory and process topology.

An unauthenticated request to /api/auth/session should return 401 with Sign in to continue. A 503 indicates identity configuration or database availability trouble. Then use browser sign-in and confirm that only the provisioned account can enter.

5. Grant the minimum operational accessCopy Anchor Link

Provision additional people as operator or viewer, then use Settings → Teams and access to grant the agents or skills they need.

Grants can target an organization, a member or a team, and can cover a whole agent or a single skill. Skill-only invocation requires an agent that advertises and honors the skill-routing extension.

Sessions are opaque and server-side. Logout removes the session, and later requests recheck current user and membership state. To deactivate a person, a trusted database operator disables the membership or user; there is no user administration UI or disable CLI. Already accepted work continues after logout or grant revocation.

Request and failure behaviorCopy Anchor Link

Mutating browser/API requests in OIDC mode need an Origin equal to A2A_AUTH_ORIGIN as well as a session. Taskbay does not provide service API tokens. A valid identity can still receive 403 when its role, grants or origin do not permit an action.

Login attempts expire after ten minutes and are single-use. The server discards provider tokens after validation, retaining the issuer and subject for membership lookup. There is no SAML, password login, SCIM, provider-role mapping or reuse of OIDC tokens for agent calls.

Sources and related guidesCopy Anchor Link

• Sign in and roles, Teams and grants, Threat model.
• Implementation: auth configuration, OIDC adapter.