Skip to content

Authentication Overview

Engineering Runtime never issues or stores credentials. It validates that a credential the platform's own tooling already manages is present and valid.

Authenticate using the platform. Govern using the runtime.

There is no runtime login that opens a browser, no credential store, no token file the runtime owns. If a session is missing or expired, the runtime tells you which platform command to run yourself.

Two provider shapes

REST providers

For services with an HTTP API. The token lives in an environment variable — never in config.yaml. The Auth Engine calls a known validation endpoint and treats HTTP 2xx as success.

Provider Environment variable Validation call
github RUNTIME_GITHUB_TOKEN GET <base_url>/user

CLI providers

For tools that manage their own credential store. The Auth Engine runs the tool's own auth check — the runtime handles no token at all.

Provider Binary Auth check
gcp gcloud gcloud auth print-access-token for validity, gcloud config get-value account for the subject
kubernetes — Reads the kubeconfig's current-context directly, no shell-out
openshift oc oc whoami

Current provider status

Provider Kind Status
GitHub REST Implemented
GCP CLI Implemented (ADC)
Kubernetes CLI Implemented
OpenShift CLI Implemented
AWS CLI Not yet implemented
Azure CLI Not yet implemented
OIDC (CI workload identity) — Not yet implemented

Binaries with no auth provider mapping — terraform, aws, az, vault, docker, pulumi and others — still run through command run. They simply manage their own credentials, which is a declaration, not a gap.

Enabling a provider

Only providers with enabled: true are checked. A disabled provider costs nothing — no code path for it runs.

authentication:
  github:
    enabled: true
  gcp:
    enabled: true       # after `gcloud auth application-default login`

See config.yaml.

The lifecycle: login → execute → logout

runtime auth status                  # unaudited health check across every enabled provider
runtime auth login <provider>        # validate one provider explicitly; audited
runtime auth logout <provider>       # revoke where possible; audited

auth status is a diagnostic, not a prerequisite. There is no pre-flight auth check anywhere in the execution path — each execution validates the provider its operation needs, inline. Nothing is cached between commands, and no session is established.

Full command reference: runtime auth.

How a provider is chosen

Dispatch is resolved two different ways, and the distinction matters.

Runtime Providers declare their Auth Engine provider once, for every operation they expose:

Runtime Provider Auth provider
github github
files none — never touches a network or a credential

This applies whatever transport the provider picks. A CLI-backed GitHub operation authenticates as github exactly like a REST-backed one — and the Command Engine forwards the validated token to gh as GH_TOKEN, which is why gh auth login is never required.

Command Engine binaries invoked directly through runtime command run declare their provider in config.yaml's command_providers map:

command_providers:
  gcloud: gcp
  kubectl: kubernetes
  oc: openshift
  # terraform intentionally has no entry — it manages its own credentials

An unmapped binary skips the Auth Engine entirely. There is no silent fallback to a default provider: omission is treated as a "doesn't need auth" declaration.

Two senses of the word provider

An Auth Engine provider is a credential source (github, gcp, kubernetes, openshift). A Runtime Provider is an operation surface (github, files). A Runtime Provider names the Auth Engine provider it uses. See Providers.

Policy runs before authentication

The execution lifecycle evaluates policy before authentication, deliberately. A policy-denied operation is rejected and audited without ever spending a credential-validation round trip against the platform — and nothing is lost by it, since an audit record carries the OS user as executor, not a platform identity.

Diagnosing

runtime config validate

Reports every provider's enabled state, whether its CLI binary is installed, and its live auth status:

Auth Providers:
  PROVIDER    ENABLED  BINARY   INSTALLED  AUTH STATUS
  github      yes      -        -          ✓ subject=your-login
  gcp         yes      gcloud   yes        ✗ no ADC — run: gcloud auth application-default login
  kubernetes  no       -        -          -
  openshift   no       oc       no         -

Per-provider setup