Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Skip to content

Credential Proxying

iron-proxy holds the credentials your workloads use to call upstream APIs, so the workloads never see the real values.

Containers, CI jobs, and agents send unauthenticated requests (or requests carrying a placeholder token). The proxy attaches the real credential as the request leaves your network. If a workload is compromised, there is no real credential to steal.

The right mechanism depends on what the upstream API expects.

Picking A Strategy

Upstream expectsUseWhat the proxy holds
A static API key, bearer token, or basic-auth passwordStatic SecretsThe literal credential value.
An OAuth2 bearer minted from longer-lived credentialsOAuth2 Token InjectionA refresh token, client credentials, username/password, or RFC 7523 signing key.
An HMAC signature over the outbound requestHMAC Request SigningThe HMAC key and any auxiliary credentials the scheme requires.
An AWS SigV4 signatureAWS Request SigningAn AWS access key and secret, or AWS workload identity credentials.
A Google service-account access tokenGCP Service AccountsA service-account JSON keyfile, or GCP workload identity credentials.

The five are independent. One iron-proxy can use any combination, scoped to different hosts.

Common Concepts

Every credential proxying mechanism shares the same scaffolding.

Secret Sources

You never put a credential value directly in the YAML config. Each credential field is a "secret source" object: a backend type plus a lookup key. iron-proxy reads the value at startup and caches it in memory. Five backends are supported:

TypeReads from
envAn environment variable on the iron-proxy process.
aws_smAWS Secrets Manager.
aws_ssmAWS Systems Manager Parameter Store.
1password_connectA 1Password Connect server you run. Recommended for 1Password.
1password1Password's hosted SDK. Rate-limited per account.

Every source supports two optional fields:

  • json_key: when set, the value is parsed as JSON and the named field is extracted. Use this to pack a client_id and client_secret into one Secrets Manager entry.
  • ttl: when non-zero, iron-proxy re-reads the value on that interval. Rotate a credential in the backing store and the proxy picks it up on the next refresh, no restart required.

See Static Secrets / Secret Sources for the full field reference.

Host Rules

Every mechanism scopes itself with a rules list matching outbound requests by host, method, and path. Rules use the same shape as the allowlist. Scope credentials to the narrowest set of destinations that work. A credential that applies to every host leaks the moment a workload makes an unrelated request.

MITM Mode

All four mechanisms rewrite request headers, so iron-proxy has to terminate TLS. Use tls.mode: mitm (the default) and make sure workloads trust the proxy's CA. sni-only mode passes TLS through unmodified and cannot do credential proxying.

Fail-Closed Behavior

When a credential can't be resolved or a token can't be minted, iron-proxy closes the request rather than forwarding it unauthenticated:

  • secrets rejects with HTTP 403 if require: true and the workload didn't send the proxy token.
  • oauth_token rejects with HTTP 502 if token minting fails.
  • hmac_sign rejects with HTTP 400, 413, or 502 depending on the failure.
  • aws_auth rejects with HTTP 400, 403, 413, 500, or 502 depending on the failure.
  • gcp_auth rejects with HTTP 403 if token minting fails.

The audit log carries the reason on every rejection.

Pipeline Ordering

Transforms run top-to-bottom in the order they appear under transforms:. Two rules matter most:

  • Put credential injection after any policy transform (judge, mcp, body_capture) that should see proxy tokens, not real credentials.
  • Put header_allowlist after credential injection so injected headers survive the allowlist.

When two credential transforms target the same host, the first one in config order wins.

Related Pages