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¶
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¶
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¶
- GitHub — token, scopes, Enterprise Server
- GCP, Kubernetes, OpenShift — CLI-native sessions
Next¶
Operational examples on this site were verified against Runtime 0.14.0. After bootstrap, the version-exact files in Runtime Home win.