Skip to content

Authenticate Runtime

Version boundary

This page describes the pre-0.12 authentication contract. See Governed authority for v0.12.0 sources, separate ENGRT session, raw gh compatibility change and proof model. See the v0.12.0 GitHub setup guide for human, Actions and GKE authentication recommendations and step-by-step setup.

Goal: give the runtime the platform credentials it needs, using each platform's own login — the runtime never issues or stores credentials of its own.

Engineering Runtime does not operate its own persistent credential store. It validates that a credential the platform's tooling manages is usable to the extent reported by its proof. Native tools may refresh their own caches, including private invocation-owned SDK scratch that Runtime removes on cleanup.

v0.9.9 authentication hardening

Runtime v0.9.9 distinguishes principal_verified, credential_ready and configuration_ready. Only a verified principal satisfies identity policy; none of these proves authorization for a particular resource operation.

The portability foundation now carries credential-free identity/proof, target and environment facts for each invocation. It does not create a shared process identity or a credential store. CI/Kubernetes markers cannot authenticate a provider. Runtime v0.9.9 now includes explicit in-cluster kubectl and GCP REST/native-source bindings.

Authenticate using the platform. Govern using the runtime.

There is no runtime login that opens a browser or independently managed credential store. If a local session is missing or expired, Runtime tells you which native setup is required. A selected workload source fails closed instead of starting interactive login or falling back to a local user.

Two provider shapes

REST providers

For services with an HTTP API. GitHub's token lives in an environment variable, never in config.yaml. Its Auth Engine adapter calls a known validation endpoint and requires a valid identity response, not merely an HTTP success status. Runtime v0.9.9 also supports one GCP REST read using the admitted native gcloud source. It reports credential readiness, not an independently verified principal.

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

GCP uses no raw-token environment API: an internal, single-use binding delivers the native credential only to the approved Resource Manager request. See portable GCP sources.

CLI providers

For tools that manage their own credential store. The Auth Engine runs the tool's own auth check. GCP's access token is briefly captured for a bounded readiness check, then discarded; it is not returned as an identity credential.

Provider Binary Auth check
gcp gcloud Select the admitted native account/file/metadata source and request its token with prepared selectors; credential readiness, no asserted API principal
kubernetes — Inspect admitted kubeconfig or explicit in-cluster configuration without executing credential plugins; configuration readiness
openshift oc oc whoami

Current provider status

Provider Kind Status
GitHub REST Implemented
GCP CLI + bounded REST read Native credential readiness; not ADC
Kubernetes CLI Configuration readiness; no API-authentication proof
OpenShift CLI Implemented
AWS CLI Not yet implemented
Azure CLI Not yet implemented
GCP CI federation Native credential-file adapter Explicit provisioned credential-file source

Portability matrix

These are admitted combinations, not automatic environment-to-credential selection. v0.9.9 supports macOS and Linux. Windows support is not yet available in this release.

Provider Transport Source Use and limits
GitHub REST / GraphQL / Command (gh) Configured token or admitted native gh session Supply a source explicitly; no GitHub OIDC exchange adapter
GCP Command / bounded REST project read native Existing gcloud session, not ADC
GCP Same credential_file Provisioned native external-account file, including admitted CI WIF
GCP Same gke_metadata GKE pod with explicit expected GSA; IAM remains separate from Kubernetes RBAC
Kubernetes Command (kubectl) kubeconfig Local or provisioned context; configuration readiness is not principal verification
Kubernetes Command (kubectl), read-only in_cluster Projected KSA token, endpoint and CA; RBAC controls resource access
OpenShift Command (oc) Native session Explicitly provisioned environment

Standalone ADC, other CI federation adapters, Cloud Run/VM-specific modes and AWS/Azure auth adapters are not added by v0.9.9. The current sticky- enrollment configuration path cannot enable GCP's local-only auth setting; enrolled GCP is not a supported combination until that authority contract is resolved explicitly.

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

authentication:
  github:
    enabled: true
  gcp:
    enabled: true       # after native `gcloud auth login`

enabled: false means Runtime does not probe a credential, resolve an identity or run that provider's operations — it stops before any of it. Enforced since 0.6.0. Earlier releases applied the switch to auth status display only, so a provider you had turned off still ran its credential probe the moment an operation asked for one, which for the CLI-backed providers means a process and a token refresh.

It is a feature switch, not a sandbox

It governs Runtime provider operations and mapped authentication on engrt command run. In Runtime v0.9.9, a disabled mapped adapter refuses before native target discovery as well as credential checks. Raw gh's reviewed native-session mode retains its existing exception: disabling configured GitHub auth does not disable that separately admitted native session. Unmapped tools do not acquire an auth provider from environment hints. Command policy and the compiled safety floor still apply. This switch cannot stop anyone launching a native tool outside Runtime.

See config.yaml.

What Runtime keeps

No independent persistent credential store. The HTTP binding holds a credential in memory for one bounded operation; it is not serialized into results, audit or the Control Plane. Native tools retain their own cache behavior. Metadata-mode SDK state and temporary in-cluster configuration live in private invocation scratch; cleanup removes Runtime-owned files, never platform-owned projected tokens or the user's native stores.

What it records instead is a projection: which platform authenticated the operation, in full, and a verified principal as a keyed digest. Readiness has no principal digest. That answers "was this the same principal?" without putting an employee's login in a file that gets copied to a collector. You will see it in an audit record as auth_provider and identity_digest.

Auth responses never return full token values. Native probe output is withheld on failure; principal responses are checked for malformed or recognizable credential-shaped text. This is defense in depth, not universal secret detection against a malicious native tool.

The lifecycle: login → execute → logout

engrt auth status                  # diagnostic with durable auth intent/completion
engrt auth login <provider>        # validate one provider explicitly; audited
engrt 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: engrt 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 provider-chosen gh operations. For the direct gh.repo.list mode it can instead delegate to an existing native gh session. Runtime never initiates gh auth login itself.

Command Engine binaries invoked directly through engrt 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

engrt config validate

Reports every provider's enabled state, whether its CLI binary is installed, and its actual proof or failure. Kubernetes configuration readiness is not a live API check. Enabled checks write durable auth evidence and may refresh native caches; config validate does not edit config/policy documents but is not filesystem-effect-free.

Per-provider setup

Next

Connect GitHub

Operational examples on this site were verified against Runtime 0.14.0. After bootstrap, the version-exact files in Runtime Home win.