tempogate

command module
v0.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 24, 2026 License: Apache-2.0 Imports: 2 Imported by: 0

README

tempogate

ci License Go Reference codecov

A single-binary OIDC provider and OAuth2 authorization server that gives self-hosted Temporal browser SSO and JWT machine-auth without forking temporal-server or running a sidecar proxy.

Overview

Self-hosted Temporal can authenticate users and services, but only if you supply an OIDC issuer. tempogate is that issuer. It federates sign-in to Google, mints short-lived JWTs Temporal's stock authorizer already understands, and publishes the JWKS the gRPC frontend verifies against. It runs as one distroless binary and is aimed at teams operating their own Temporal cluster.

Why it exists

Self-hosted Temporal ships two extension points:

  • the Web UI consumes any OIDC issuer via TEMPORAL_AUTH_* env vars;
  • the gRPC frontend verifies JWTs against a configurable JWKS endpoint and reads a permissions: ["<namespace>:<action>", ...] claim.

Together these cover SSO and machine-auth — but only if something issues the tokens. The usual alternatives are forking temporal-server or putting a reverse proxy in front of it; both carry ongoing cost (see the comparison below). tempogate fills the gap Temporal's own docs already describe: point the Web UI at https://tempogate.<your-domain> and the frontend's global.authorization.jwtKeyProvider.keySourceURIs at https://tempogate.<your-domain>/.well-known/jwks.json.

How it works

┌──────────────┐     OIDC      ┌────────────────────┐
│ Temporal Web │ ─────────────▶│      tempogate     │ ──wraps──▶ Google OAuth2
│      UI      │◀── our JWT ───│  (OIDC + OAuth2 AS) │
└──────┬───────┘               └────────────────────┘
       │ Bearer <tempogate JWT>          ▲
       ▼                                 │
┌──────────────┐         JWKS            │
│  temporal-   │ ◀───────────────────────┘
│  frontend    │  (stock default JWT ClaimMapper)
└──────────────┘

One binary with subcommands serve, login, token, keys, migrate, version. State is pluggable; the default is SQLite on a PVC via the pure-Go modernc.org/sqlite driver, with embedded migrations applied by tempogate migrate.

Status

Wired and exercised end to end:

  • /healthz, /readyz
  • /.well-known/jwks.json and the full /.well-known/openid-configuration
  • OIDC SSO: /authorize, /callback/google, /token, /userinfo
  • tempogate login + tempogate token for personal tokens from a laptop (persisted 0600, auto-refreshed near expiry)
  • PKCE mandatory by default, with a narrow secret-gated carve-out for confidential clients such as the Temporal Web UI — see docs/pkce-and-confidential-clients.md
  • OIDC Core nonce round-trip and aud stamping
  • Multi-arch distroless image and a Helm chart

Authorization is currently flat: every admitted identity receives cluster-level access (temporal-system:admin), the value Temporal's default ClaimMapper needs for cluster APIs. Group- or role-derived per-namespace scoping and an admin API for long-lived integration keys are planned.

Revoking integration keys

DELETE /admin/keys/:id marks a key revoked and adds its jti to a SQLite-backed denylist. The denylist is consulted by tempogate's own verifier (refresh-token exchange, /userinfo) through a 30 s read-through cache, so a revoke takes effect on those flows within 30 s on a single instance, and is hydrated synchronously in-process for the instance that served the DELETE.

Temporal's frontend, however, validates JWTs with its default ClaimMapper against /.well-known/jwks.json only — it has no hook to consult a per-issuer denylist. The practical consequence:

Verification path Time until revoke takes effect
tempogate (refresh, /userinfo) up to 30 s (denylist cache TTL)
Temporal frontend gRPC up to the token's exp lifetime

This is the acknowledged trade-off of stateless JWTs against Temporal's stock verifier. Mint integration keys with a deliberately bounded exp if your threat model needs an upper bound on revoke lag for Temporal gRPC; a future move to opaque, server-introspected keys would close the gap end-to-end.

New here? docs/getting-started.md takes you from nothing to a working Web-UI SSO + CLI token in under ten minutes, with no Google account required (a bundled mock IdP stands in).

Multi-tenancy

Tempogate serializes a token's authorization as a flat permissions claim of "<namespace>:<role>" entries — the exact shape Temporal's default JWT ClaimMapper parses into claims.Namespaces[ns] = role. Two entries in the array for different namespaces accumulate independently, so a single token can grant read on one namespace and admin on another; two entries for the same namespace last-write-wins, mirroring the ClaimMapper's own behaviour.

The four canonical Temporal roles — read, write, worker, admin — are honoured verbatim. Cluster-wide access is expressed by granting a role on the temporal-system namespace (the only construct the default ClaimMapper recognises for "every namespace"); the literal * is rejected as a real namespace name by the same authorizer, so the perms.AddWildcard Go-API sugar is internally rewritten to temporal-system:<role> before serialization. The model lives in the perms package; both the OIDC /token flow and the /admin/keys admin API funnel through perms.Grant so the wire shape stays uniform regardless of which path minted the token.

A token issued for tenant-a cannot perform any action on tenant-b. That boundary is enforced at the Temporal frontend by the default authorizer — not inside tempogate — and is the reference behaviour proved end-to-end in test/e2e/multi_tenant_test.go, which provisions two namespaces against a real temporal-frontend and asserts both the cross-namespace denial (gRPC PermissionDenied) and the multi-namespace accumulation (one token, two namespaces, different roles enforced independently).

The /admin/keys admin API deliberately mints one (namespace, role) per key so audit and rotation always reason over a minimal scope; a caller that needs multi-namespace authorization issues several keys, or — for humans — picks up the multi-ns shape automatically through the OIDC /token path as the identity-mapping layer matures.

Quick start

Run a published image:

TEMPOGATE_IMAGE=${TEMPOGATE_IMAGE:-ghcr.io/onhotpath/tempogate:latest}
export OIDC_SESSION_SIGNING_KEY="$(openssl rand -base64 32 | tr '+/' '-_' | tr -d '=')"
export OIDC_CLIENTS='tempogate-device-ui:http://127.0.0.1:8000/device/sso-callback'
export OIDC_CLIENT_SECRETS="tempogate-device-ui:$(openssl rand -hex 32)"
docker volume create tempogate-state
docker run --rm --mount source=tempogate-state,target=/var/lib/tempogate \
  -e OIDC_SESSION_SIGNING_KEY -e OIDC_CLIENTS -e OIDC_CLIENT_SECRETS \
  "$TEMPOGATE_IMAGE" migrate
docker run --rm -d --name tempogate -p 8000:8000 \
  --mount source=tempogate-state,target=/var/lib/tempogate \
  -e OIDC_SESSION_SIGNING_KEY -e OIDC_CLIENTS -e OIDC_CLIENT_SECRETS \
  -e HTTP_LISTENER=0.0.0.0:8000 "$TEMPOGATE_IMAGE"
curl --retry 20 --retry-delay 1 --retry-all-errors -fsS http://127.0.0.1:8000/healthz

Keep the signing key and SQLite volume across restarts. The generated client secret is for this health-check example; configure OIDC_ISSUER, registered clients, allowed domains, and Google credentials for real login. Save those secrets outside the shell before using this as a lasting deployment. Stop the example with docker stop tempogate.

Container images are published to ghcr.io/onhotpath/tempogate:

Tag Meaning
:vX.Y.Z, :X.Y, :X, :latest Stable releases (pushed on git tag vX.Y.Z)
:vX.Y.Z-rc.N Pre-releases (release candidates)
:sha-<short> One-off builds dispatched manually from a specific commit
Prebuilt CLI binaries

Every stable release and release candidate also ships a standalone, lean tempogate CLI — just login, token, and version, with none of the server/SQLite/OIDC-issuer stack compiled in — as GitHub Release assets for linux and darwin on amd64/arm64, alongside a checksums.txt. Stable releases are published; release candidates are marked pre-release; manual dispatch builds attach the binaries to the workflow run only.

On macOS, via the Homebrew tap (hosted in this repository):

brew tap onhotpath/tempogate https://github.com/onhotpath/tempogate
brew install tempogate

Or download a release asset directly (Linux x86_64 shown — pick your os/arch):

gh release download vX.Y.Z --repo onhotpath/tempogate \
  --pattern 'tempogate_*_linux_x86_64.tar.gz' --pattern checksums.txt
sha256sum -c --ignore-missing checksums.txt
tar -xzf tempogate_*_linux_x86_64.tar.gz
./tempogate version --detailed

Cutting a release? See RELEASING.md.

Build from source:

git clone git@github.com:onhotpath/tempogate.git
cd tempogate
make build
export STATE_SQLITE_PATH="$PWD/state.db"
export OIDC_SESSION_SIGNING_KEY="$(openssl rand -base64 32 | tr '+/' '-_' | tr -d '=')"
export OIDC_CLIENTS='tempogate-device-ui:http://127.0.0.1:8000/device/sso-callback'
export OIDC_CLIENT_SECRETS="tempogate-device-ui:$(openssl rand -hex 32)"
./.bin/tempogate migrate
./.bin/tempogate serve            # listens on 127.0.0.1:8000

Or build the container locally:

docker build -t tempogate:dev .
TEMPOGATE_IMAGE=tempogate:dev    # then run the Quick start above

Kubernetes deployment is covered by the chart in charts/tempogate/. It is published as an OCI artifact, so no repo clone is needed:

helm install tempogate oci://ghcr.io/onhotpath/charts/tempogate --version 0.3.0

The chart is versioned independently of the binary; pick the version from the chart releases.

Personal tokens from a laptop

Once the server is reachable, a user mints a short-lived Temporal JWT without hand-editing any config:

export TEMPOGATE_ISSUER=https://tempogate.example.com

tempogate login                                  # browser sign-in, once
export TEMPORAL_AUTH_TOKEN=$(tempogate token)    # thereafter; auto-refreshes

tempogate login starts a one-shot 127.0.0.1 server, opens your browser to sign in via Google, prints the token, and persists it to ~/.tempogate/token.json (0600). A fresh ephemeral loopback port is used each run — no Google Cloud Console edits, just one OIDC_CLIENTS entry on the server. tempogate token then reuses that file, refreshing the token five minutes before expiry, so it never re-opens a browser. Both print only the token to stdout, so they are safe in $(...). See docs/cli-loopback-login.md for persistence, auto-refresh, the operator one-liner, and why ephemeral ports work.

For hosts without a browser (remote SSH sessions, cloud dev VMs, CI debug shells), use tempogate login --device — the OAuth 2.0 device authorization grant (RFC 8628); the CLI prints a short code and a URL you open on any other device with a browser. See docs/cli-device-login.md.

Configuration

Configuration is layered: defaults, then an optional application.yaml, then environment variables (env wins). Nested keys flatten with _ as the separator.

Env var Required Default Notes
OIDC_ISSUER For real deploys http://127.0.0.1:8000 Externally reachable base URL; advertised as issuer and used to derive jwks_uri. May include a path (e.g. https://host/idp) — see Sub-path hosting
OIDC_CLIENTS For any login (empty) Comma-separated id:redirect_uri_prefix allowlist. Register the CLI as tempogate-cli:http://127.0.0.1:
OIDC_ALLOWED_DOMAINS For any login (empty) Comma-separated email-domain gate applied after Google sign-in
OIDC_GOOGLE_CLIENT_ID For any login (empty) Upstream Google OAuth client
OIDC_GOOGLE_CLIENT_SECRET For any login (empty) Upstream Google OAuth client secret
OIDC_CLIENT_SECRETS No (empty) Comma-separated id:secret; promotes a registered client to confidential (PKCE carve-out)
HTTP_LISTENER No 127.0.0.1:8000 host:port for the public listener
STATE_SQLITE_PATH No /var/lib/tempogate/state.db SQLite state-store path (back this with a PVC)
LOG_LEVEL No info debug / info / warn / error
TEMPOGATE_ISSUER No (empty) Client-side, read by tempogate login (not the server). Equivalent to --issuer

Sub-path hosting

OIDC_ISSUER may contain a path, so tempogate can share a hostname with another app instead of needing its own. Set the issuer to the full external URL including the path, e.g.:

OIDC_ISSUER=https://tempogate.example.com/idp

tempogate then serves its entire OIDC surface under that prefix — /idp/.well-known/openid-configuration, /idp/.well-known/jwks.json, /idp/authorize, /idp/token, /idp/userinfo, /idp/callback/google — and the discovery document advertises issuer-relative (prefixed) endpoints, so the iss claim, the advertised endpoints, and the served routes stay in lockstep. A root issuer (no path) behaves exactly as before.

Route a path prefix on the shared host to tempogate at your reverse proxy (strip nothing — tempogate owns the prefix natively). Two operational notes:

  • Health probes stay at the root: /healthz and /readyz are not moved under the prefix (they are infra probes, not part of the public OIDC surface). Point Kubernetes liveness/readiness at /healthz / /readyz regardless of the issuer path; you do not need to route them through the shared-host proxy.
  • Google authorized redirect URI must match the prefixed callback: register https://tempogate.example.com/idp/callback/google (issuer + /callback/google) in the Google OAuth client.

Why not a sidecar proxy or a fork?

Approach Pros Cons
tempogate (OIDC + OAuth2 AS, this repo) Stateless integration with stock Temporal. No fork, no proxy. A second component to operate.
Sidecar reverse-proxy in front of UI/gRPC Auth logic outside Temporal. Has to demux gRPC + HTTP; brittle around streaming; obscures Temporal's own auth machinery.
Forked temporal-server Total control. Permanent rebase tax; loses upstream support; defeats the "self-hosted but supported" posture.

Development

make tools         # install pinned gci + golangci-lint into ./.bin
make check         # fmt + vet + gci; fails on a dirty tree
make lint          # golangci-lint
make test          # check + race + coverage
make ci            # what GitHub Actions runs
make test-e2e      # container-backed acceptance proofs (needs Docker)

make test-e2e stands up temporalio/ui, a JWKS-backed temporal-frontend, a mock Google IdP, and headless Chrome via testcontainers, and proves two flows end to end: Web UI SSO login, and the tempogate login CLI loopback flow. Both assert that the minted JWT authenticates a gRPC ListNamespaces and that an unauthenticated call is rejected. It is behind a //go:build e2e tag and a dedicated CI job, so the default make ci stays fast.

Go 1.27+ is required. See CONTRIBUTING.md.

Documentation

Security

Report vulnerabilities via GitHub Security Advisories — see SECURITY.md. Do not open public issues for security reports.

License

Apache 2.0 — see LICENSE.

Documentation

The Go Gopher

There is no documentation for this package.

Directories

Path Synopsis
Package admin exposes tempogate's backend-callable integration-key API: a service can POST to /admin/keys to mint a long-lived JWT scoped to a single namespace+role, retrieve metadata, and revoke.
Package admin exposes tempogate's backend-callable integration-key API: a service can POST to /admin/keys to mint a long-lived JWT scoped to a single namespace+role, retrieve metadata, and revoke.
Package api is tempogate's HTTP surface.
Package api is tempogate's HTTP surface.
Package app is the fx composition root for the tempogate binary.
Package app is the fx composition root for the tempogate binary.
Package buildinfo exposes ldflag-injected build metadata.
Package buildinfo exposes ldflag-injected build metadata.
Package cli is the engineer-facing client half of tempogate: it talks to a running tempogate issuer over its public OIDC/OAuth2 surface rather than sharing any server state.
Package cli is the engineer-facing client half of tempogate: it talks to a running tempogate issuer over its public OIDC/OAuth2 surface rather than sharing any server state.
cmd
servercmd
Package servercmd holds the server-bound subcommands (serve, migrate, keys) — the ones that need the SQLite state store and the OIDC/API stack.
Package servercmd holds the server-bound subcommands (serve, migrate, keys) — the ones that need the SQLite state store and the OIDC/API stack.
Package log provides a zap-backed logger and a slog handler that share the same core, so callers can pick either API and still emit through one sink.
Package log provides a zap-backed logger and a slog handler that share the same core, so callers can pick either API and still emit through one sink.
Package oidc is the OIDC provider surface tempogate exposes to downstream clients (Temporal Web UI, the CLI loopback server).
Package oidc is the OIDC provider surface tempogate exposes to downstream clients (Temporal Web UI, the CLI loopback server).
google
Package google is the concrete Google leg of the OIDC flow.
Package google is the concrete Google leg of the OIDC flow.
Package perms is the shared domain type tempogate uses to describe what a token can do, before that description is serialized into the JWT's `permissions` claim.
Package perms is the shared domain type tempogate uses to describe what a token can do, before that description is serialized into the JWT's `permissions` claim.
Package state is intentionally empty of types and interfaces.
Package state is intentionally empty of types and interfaces.
sqlite
Package sqlite is the concrete SQLite-backed implementation that satisfies the per-consumer state interfaces defined across the codebase via Go's structural typing (see state/doc.go).
Package sqlite is the concrete SQLite-backed implementation that satisfies the per-consumer state interfaces defined across the codebase via Go's structural typing (see state/doc.go).
test
e2e/mockgoogle command
Command mockgoogle is a minimal but real upstream OIDC IdP used only by the end-to-end test (test/e2e).
Command mockgoogle is a minimal but real upstream OIDC IdP used only by the end-to-end test (test/e2e).

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL