Octov0.11.17
Platform

Users and API Keys

Authentication, user management, and API tokens.

The platform authenticates people with OIDC single sign-on and machines with per-user bearer tokens. This page covers sessions, user provisioning, roles, and how API keys are minted and verified.

Sign-in (OIDC SSO)

Authentication lives entirely in the platform app, built on Auth.js (NextAuth), with one OIDC provider using the authorization-code flow. Octo ships no identity provider and privileges none: bring any standards-compliant one, such as Auth0, Keycloak, Okta, Entra ID, Google, Authentik, or Dex. The issuer, client id, and client secret come from OIDC_ISSUER, OIDC_CLIENT_ID, and OIDC_CLIENT_SECRET (set by the Helm chart's auth.oidc values).

Sessions are JWTs with no database adapter. The session rides in a signed cookie (AUTH_SECRET), so the same config backs both route handlers and the edge request gate.

Single sign-on is not optional and there is no unauthenticated mode — local development included. An install missing any of OIDC_ISSUER, OIDC_CLIENT_ID, OIDC_CLIENT_SECRET or AUTH_SECRET is one nobody can sign in to, and the welcome page names the ones that are missing rather than offering a button that would fail at the provider. The Helm chart refuses to render without them.

Configuration

VariableRequiredDefaultPurpose
OIDC_ISSUERyesnoneIssuer URL; its .well-known/openid-configuration supplies every endpoint
OIDC_CLIENT_IDyesnoneClient id (not a secret; it travels in the redirect)
OIDC_CLIENT_SECRETyesnoneClient secret
OIDC_PROVIDER_NAMEnoOIDCName on the sign-in button: "Sign in with …"
OIDC_PROVIDER_LOGOnothe issuer's faviconMark on that button; renders without one if it 404s
OIDC_SCOPESnoopenid profile emailSpace-separated scopes requested at sign-in, and advertised to MCP clients as the scopes to request. Keep email in it: iam resolves a caller to a user by email.
OIDC_AUTHORIZATION_URLnodiscoveryEndpoint override
OIDC_TOKEN_URLnodiscoveryEndpoint override
OIDC_USERINFO_URLnodiscoveryEndpoint override; also used by /mcp
OIDC_JWKS_URLnodiscoveryEndpoint override; also used by /mcp

The endpoint overrides exist for providers whose discovery document is unreachable, incomplete, or wrong. Against a compliant provider, leave all four empty: discovery keeps working when the provider moves an endpoint.

Register {AUTH_URL}/api/auth/callback/oidc as a redirect URI on the provider. The oidc in that path is the Auth.js provider id and is fixed, whatever you call the provider in OIDC_PROVIDER_NAME.

What your provider must support

Editor sign-in asks little: the authorization-code flow, a discovery document (or the four endpoint overrides), and that redirect URI. The MCP endpoint asks for more, so check before you settle on a provider.

MCP needs Dynamic Client Registration. MCP clients (Claude Code, Codex, and the rest) read the platform's /.well-known/oauth-protected-resource/mcp document, follow it to your authorization server, and register themselves via RFC 7591. Without DCR there is no "just connect": every user has to hand-register a client with your IdP and paste a client id and secret into their harness's MCP config. Several providers ship DCR disabled, or gate it behind a plan tier, so check yours before committing.

Beyond DCR, /mcp requires three things of the provider:

  • Resource indicators (RFC 8707) must be honoured: the access token's aud must equal the MCP resource identifier ({AUTH_URL}/mcp, or MCP_RESOURCE_URL). A provider that ignores the resource parameter and mints tokens for its own default audience fails verification with a token that otherwise looks fine.
  • Access tokens must be RS256-signed JWTs with a reachable JWKS. Opaque access tokens are not supported; there is no introspection path.
  • A userinfo endpoint must be exposed. Email and name are read from it to provision the user row on first call.

Where DCR is unavailable, an MCP client cannot reach /mcp at all: it verifies access tokens the provider minted and nothing else.

The app-wide request gate redirects unauthenticated browser navigations to sign-in and answers unauthenticated /api/* calls with 401. /mcp is the one application endpoint that bypasses it, because it authenticates itself with bearer tokens (below); the welcome page, /api/auth* and two static images are exempt too. A running integration is a pod with a hostname of its own, so a webhook callback never reaches the platform app to be redirected in the first place.

Who may sign in

This platform is an allowlist. Being able to authenticate at your identity provider is not by itself permission to be here: an account has to exist before its owner can sign in, and an administrator creates it. The provider says who somebody is; the platform says who may come in. An installation whose provider admits an entire company should not admit an entire company.

The exception is the very first sign-in on a fresh installation, because there is nobody to have created that account. That person is granted platform:admin so that somebody can administer it. The rule is keyed on there being no administrator rather than on there being no users, which is the same thing on a new install and the more useful thing on one that has somehow lost its administrators.

Accounts are managed under Admin → People. Adding somebody asks for their email address and, optionally, their name. That is all, because that is all you know about a colleague who has never been here — and until they arrive their row shows Never where a last sign-in would be.

Two keys, and the difference between them matters. The address is what you provision by, and it is what decides who somebody is exactly once: the first time a person authenticates with it, their OIDC sub is written onto that waiting row. From then on the subject is what every sign-in keys on, so a changed address at the provider is a refresh of an existing account rather than a new person. Nobody ever types a subject.

One rule follows from that, and it is a refusal: somebody authenticating with an address that belongs to a row another principal has already claimed is refused. That is a different person wearing a familiar address, not the one the row was waiting for.

Addresses are unique case-insensitively, since providers treat them that way.

An address is worth what your identity provider makes it worth. Octo takes the address the provider vouches for and reads no further claim — so a provider that lets anybody self-register an address is a provider that lets anybody take the account waiting for one, including an administrator's. Point this platform at a tenant that owns its address namespace.

A users row carries a durable id, which is what integration attribution and API keys reference; deleting a user takes their API keys and role grants with them but leaves what they authored, with the attribution cleared.

The directory is paged and filtered by iam rather than by the browser — by a substring of the name or address, and by role. Each row shows the subject their provider presents, or Not signed in yet: that is the answer to "why can this person not get in", and it is the first thing to look at when somebody says they cannot.

Roles are changed in a dialog, never in the table. Adding somebody takes their address, their name and their roles together — they are granted with the row, so nobody exists here holding something nobody chose. Changing what an existing person may do means opening Edit, ticking, and saving. A role chip in a list somebody is scrolling is how platform:admin gets handed out by accident, which is the whole reason the table's pills are a reading and not a control.

An administrator cannot change their own roles or remove themselves from this screen, and iam refuses to remove the last administrator however the request arrives. Removing somebody asks first: their API keys and role grants go with them.

Roles

Roles are rows in this platform's own database, owned by the iam service, not claims the identity provider chose to send. There are four:

RoleFor
platform:adminAdministering the installation: its settings, its users, its agent.
platform:operatorRunning things — deployments, and the state behind them.
platform:developerBuilding things — integrations, resources, dev runs.
platform:monitorLooking, and nothing else.

Sign-in exchanges the provider's token for one this platform signed, carrying the caller's user id and their roles. That token is renewed while the session runs, and the renewal re-reads the roles — so a grant or a revocation takes effect within a token lifetime (an hour by default) rather than at next sign-in.

platform:admin gates the whole admin section: its pages and, more to the point, every server action behind them. Reads are gated there as well as writes, because those settings hold the installation's SMTP credentials and its LLM API keys.

AUTH_WRITE_ROLES (the chart's auth.writeRoles) is a comma-separated list of roles allowed to perform write and mutating operations elsewhere in the product. Empty (the default) means every role except platform:monitor, the role that exists to mean "looks, and nothing else". A signed-in user without a listed role gets a 403 on writes but can still read.

There are no per-integration permissions yet. The platform: prefix is there to leave room for them.

Roles per environment

A role is granted in one environment. The roles above are the default environment's, and everybody kept the roles they had when environments arrived. To grant roles elsewhere, open a person in Admin → People and tick roles under Roles in other environments. Someone can be a developer in staging and a monitor in the default, or hold nothing at all in the default.

platform:admin is granted only in the default environment, and an administrator holds every role in every environment. The dialog says so instead of offering boxes for them.

The iam endpoints are the same ones the default uses, with the environment as a segment of the path:

OperationEndpoint
Grant a role in an environmentPUT /users/{id}/environments/{environment}/roles/{role}
Revoke a role in an environmentDELETE /users/{id}/environments/{environment}/roles/{role}

A person's platform token carries their roles everywhere, so switching environments needs no new sign-in.

What the screens do with a role

The UI reflects the same split the servers enforce, and reflects it only — every decision with a consequence is made on the server, and nothing here is a control.

  • Controls are disabled, with a title saying what is missing. Deploy, roll out, scale and undeploy want Operator or Admin; creating, importing, duplicating, deleting and saving an integration want Developer, Operator or Admin. Either way write access is wanted as well as the role — AUTH_WRITE_ROLES can take it away from somebody who holds the role, so the title names both rather than sending them to look for a role they already have. They stay visible because they sit on pages anybody signed in may read, and a header that quietly loses its buttons reads as a broken page rather than as a permission not held.
  • Sections are hidden. Secrets is administrators only, reads included, so the tab and the dashboard shortcut are left out for everybody else rather than shown leading to a refusal.
  • The editor opens read-only. Somebody without Developer, Operator or Admin can open an integration, read it, and browse its resources; Save is disabled and says why.

API keys

API keys are per-user bearer tokens for programmatic access. A key belongs to one person and only ever acts as them, limited to the roles you give it when you mint it. Give each key only what its job needs.

  • Roles: pick at least one of monitor, developer, operator and CI/CD. Roles are separate facets, not levels: holding operator does not let you give a key developer.
    • monitor, developer and operator go on a key only if you hold them, or if you are an admin.
    • CI/CD is for pipelines on any CI platform. It pushes code to an existing integration, tags versions, runs a deployment's tests and rolls out an existing deployment, reading what that takes; what CI/CD can and cannot do lists every route. Nobody holds CI/CD as a person: an admin may put it on a key, and so may anyone holding both developer and operator.
    • A key never carries admin, so secrets, settings and role grants stay with a signed-in session. Asking for admin, an unknown role or no role at all is a 400; asking for a role you may not give is a 403 that names it.
  • Deploying with a key: a key with operator may deploy and roll out, and a key with CI/CD may roll out, always with the deployment's basic identity, which reaches only its own stores. Deploying or rolling out an integration that needs platform access takes a signed-in person, because a deployment's token outlives the key that deployed it.

A deployment outlives whoever deployed it

A deployed integration gets its own identity, and that identity renews itself. This holds for a person and a key alike: revoking a person's roles or deleting their account, or revoking, expiring or narrowing a key stops that person or key, but not what they already deployed. That code keeps running under its owner's name, reaching its own stores and whatever platform access a signed-in person granted it, until somebody removes the deployment.

A key makes this easier to abuse, because it is a standing secret that lives in a CI system rather than in somebody's browser. Treat a key with CI/CD or operator like a production credential:

  • Keep it only in your CI system's secret store. Never commit it, paste it into a chat, or print it in a build log.
  • Mint one key per pipeline, with only the roles that pipeline needs and the shortest expiry you can live with.
  • Rotate it on a schedule, and revoke it as soon as a pipeline stops using it.
  • If a key leaks, revoke it, then review the deployments it may have touched and remove or roll back anything you did not ship. Do the same when somebody who deploys leaves.

CI/CD is not yet scoped to particular integrations: within what it may do, it reaches every integration and deployment on the installation, not only the ones its pipeline ships. Keys scoped to the exact integrations a pipeline ships are planned. Until then, weigh this risk before you mint one.

  • Re-checked on every use: a key's token carries only the key's roles that its owner could still give it, by the same rule as when it was minted. Revoke a role from someone and their keys lose it within one token lifetime; a CI/CD key stays usable while its owner is an admin or holds both developer and operator. A key left with no role is refused with a 403.
  • Format: octo_ followed by 32 bytes of random material, base64url-encoded.
  • Shown once: the plaintext is returned only by the create call. iam stores a SHA-256 hash, so a database leak exposes no usable keys, plus the first four and last four characters for display.
  • Expiry: you choose the date a key expires, at most two years out. It is enforced on every exchange.
  • Revocation: deleting a key is a soft revoke (the row is kept for audit); a revoked key stops exchanging immediately, and the platform tokens it was already exchanged for lapse within one token lifetime. Those tokens cannot be refreshed, and lend a deployment at most its basic identity, so the key's own reach does not outlive it.

What CI/CD can and cannot do

CI/CD is confined to rolling out a new version of an integration and a deployment that already exist. Somebody holding developer and operator creates the integration and deploys it once; from then on the pipeline ships to it. The orchestrator admits a CI/CD token on an exact list of routes, matched segment for segment, so nothing beneath a listed route comes with it.

A CI/CD key canRoute
List integrations and read oneGET /integrations, GET /integrations/{id}
Replace an existing integration's codePUT /integrations/{id}/bundle
Tag a version and read versionsPOST and GET /integrations/{id}/snapshots, GET /snapshots/{id}
List deployments and read oneGET /deployments, GET /deployments/{id}, GET /integrations/{id}/deployments
Roll an existing deployment onto a version or runtimePOST /deployments/{id}/rollout
Run a deployment's test suites and read the reportPOST and GET /deployments/{id}/testruns, GET /deployments/{id}/testruns/{runId}
See which runtimes it can move toGET /upgrades, GET /runtimes
A CI/CD key cannotWhy it matters
Create, import, rename or delete an integrationA leaked key cannot plant a new app or remove one.
Create, scale or remove a deploymentIt cannot start new workloads, take one down, or change its size.
Delete a versionThe versions you can roll back to stay.
Grant a deployment platform accessA rollout keeps the basic identity; a deployment that has grants needs a signed-in person to roll out.
Read an integration's bundle, files, resources or agent memory, or a version's resourcesIt cannot pull your code, configuration or conversations out.
Read logs or traces, or a deployment's storesIt cannot read what your integrations process.
Use the editor, dev runs, folders, secrets, settings or emailNone of the platform's own configuration is in reach.

What remains, and is the attack surface to weigh: a leaked CI/CD key can push its own code into any existing integration and roll it out to that integration's existing deployments. The code runs with the deployment's basic identity, under the key owner's name, and keeps running after the key is revoked (see the warning above). It cannot give that code more access than the deployment's own stores.

Keys are managed from the platform's account area, backed by these iam endpoints. Only the user in the path may call them — an administrator cannot mint, list or revoke somebody else's keys — and neither a deployment's token nor a token exchanged for a key can call them at all, so a key cannot mint its own successor:

OperationEndpoint
Mint a key (returns the plaintext once)POST /users/{userId}/apikeys with {"name", "roles", "expiresAt"}, and optionally "environment"
List your keys (metadata only)GET /users/{userId}/apikeys
Revoke a keyDELETE /users/{userId}/apikeys/{id}

For example, a key for a pipeline that expires in 90 days. expiresAt must be in the future and at most two years out:

EXPIRES_AT=$(date -u -d '+90 days' +%Y-%m-%dT%H:%M:%SZ)   # macOS: date -u -v+90d +%Y-%m-%dT%H:%M:%SZ
curl -X POST http://iam:8093/users/$USER_ID/apikeys \
  -H "Authorization: Bearer $PLATFORM_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"name\": \"ci-billing\", \"roles\": [\"platform:cicd\"], \"expiresAt\": \"$EXPIRES_AT\"}"

On the account page, hover a role, on its checkbox or on a key's role pill, to see what a key with that role may do. Delete expired revokes every expired key at once.

The account view: a new key scoped to the developer role, and existing keys with their roles

Using a key

From outside the cluster, send the key to the public API as a bearer token; it does the exchange below for you. A CI/CD job does this with the octopaas CLI by setting OCTOPAAS_KEY, while people sign in with their browser instead. Inside the cluster, present the key as a bearer token at iam's POST /auth, the same exchange a sign-in uses. iam answers with a platform token for the key's owner, carrying the key's roles that the owner could still give it. The user in the answer reports those same roles:

curl -X POST http://iam:8093/auth \
  -H "Authorization: Bearer octo_..."

The token names the key it came from, and POST /auth/refresh refuses it: when it expires, exchange the key again. That is what makes a revocation stick.

Keys and environments

A key can be bound to one environment with "environment": "<name>" when you mint it. The account page binds a new key to the environment chosen in the top bar, offers the roles you hold there, and shows each key's environment beside its roles. Without it, the key is bound to the default environment, octo. Every key minted before environments existed is bound there too.

A bound key's roles are checked against what you may delegate in that environment, and its token acts there and nowhere else. A staging key cannot touch default-environment integrations, and it cannot lend a deployment an identity anywhere but staging. Deleting an environment deletes the keys bound to it.

API keys do not reach /mcp. It is an OAuth 2.1 resource server and accepts only access tokens minted by the identity provider — see MCP Authentication.

Platform tokens and environments

A platform token tells each service which environments its bearer may act in:

  • A person's token carries roles for the default environment and envRoles, a map from each other environment to the roles held there. platform:admin is only ever granted in the default environment, and an administrator holds it in every environment.
  • A deployment's token carries an environment claim: the environment the deployment runs in. Its roles apply there and nowhere else. They are the runtime role plus any platform access lent at deploy time, judged against what the deploying person holds in that environment. Renewing the token keeps the environment and the access exactly; it never widens them. So a compromised pod reaches no further than its own environment.
  • A key's token carries the key's environment and is confined to it in the same way.

A deployment's or key's token minted before environments existed carries no environment claim and is treated as bound to the default environment, never as unbound.

On this page