Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/temporal-sa/temporal-cloud-proxy/llms.txt

Use this file to discover all available pages before exploring further.

Worker authentication is optional per workload. When configured, every inbound gRPC request must include an authorization: Bearer <token> metadata header. The proxy validates the token before forwarding the call to Temporal Cloud — requests that are missing the header or carry an invalid token are rejected with a codes.Unauthenticated or codes.InvalidArgument gRPC error before any payload is forwarded.
Worker auth and namespace auth are completely independent concerns. Namespace auth is the credential the proxy presents to Temporal Cloud (mTLS or API key). Worker auth is the credential workers present to the proxy (JWT or SPIFFE SVID). Both can be configured simultaneously, and configuring one does not imply the other.

​
JWT authentication

The JWT authenticator fetches the provider’s public keys from a JWKS endpoint and uses them to verify the token signature. The JWKS URL is polled for updates every 5 minutes in the background, so key rotations at the provider are picked up automatically without restarting the proxy. 
authentication:
  type: "jwt"
  config:
    jwks-url: "https://auth.example.com/.well-known/keys"
    audiences:
      - "temporal_cloud_proxy"
​
authentication.config.jwks-url
string
required
The full URL of the JWKS (JSON Web Key Set) endpoint. The proxy fetches this URL at startup to obtain the initial signing keys and then refreshes it every 5 minutes. The endpoint must be reachable from the host running the proxy.
​
authentication.config.audiences
string[]
required
One or more audience values that the proxy accepts. The token’s aud claim must contain at least one entry that exactly matches a value in this list. Both single-string and multi-value aud claims are supported.

​
Validation steps

For each incoming request, the JWT authenticator performs the following checks in order:
1

Signature verification

The token’s signature is verified against the public keys fetched from the configured JWKS URL.
2

Audience check

The aud claim must contain at least one value matching an entry in the configured audiences list. Tokens with a missing or non-matching aud are rejected.
3

Expiry check

The exp claim is compared against the current time. Expired tokens are rejected.
4

Subject extraction

The sub claim is extracted and stored in the authentication result. A missing sub claim causes rejection.
The JWT authenticator is compatible with any standards-compliant OIDC provider including Auth0, Okta, Keycloak, and HashiCorp Vault OIDC. Ensure that tokens issued by your provider include an aud claim that matches one of the values in the audiences list.
For a complete example of a Temporal worker configured to obtain and send JWT tokens to the proxy, see the temporal-proxy-jwt-worker reference implementation.

​
SPIFFE / SPIRE authentication

The SPIFFE authenticator connects to a SPIRE workload API socket to obtain the JWKS used to validate JWT-SVIDs. After validating the SVID’s signature and audience, it checks the SVID’s SPIFFE ID against a configured allowlist — only SVIDs whose SPIFFE ID exactly matches one of the listed values are accepted. 
authentication:
  type: "spiffe"
  config:
    spiffe_ids:
      - "spiffe://example.org/my-workload"
    endpoint: "unix:///tmp/spire-agent/public/api.sock"
    audiences:
      - "temporal_cloud_proxy"
​
authentication.config.spiffe_ids
string[]
required
The allowlist of SPIFFE IDs. The validated SVID’s SPIFFE ID must exactly match one entry in this list (string equality). SVIDs with a valid signature but a SPIFFE ID not in the list are rejected with invalid SPIFFE ID: <id> not in allowed list.
​
authentication.config.endpoint
string
required
The SPIRE workload API socket address. Accepts unix:// paths (e.g. unix:///tmp/spire-agent/public/api.sock) or tcp:// addresses. The proxy calls workloadapi.NewJWTSource against this endpoint at startup.
​
authentication.config.audiences
string[]
required
One or more audience values the SVID must include. Passed directly to jwtsvid.ParseAndValidate, which enforces the audience check as part of standard SVID validation.
The SPIRE agent must be running and the socket must be accessible at the configured endpoint when the proxy starts. If workloadapi.NewJWTSource cannot connect to the socket, the proxy will fail to initialise with: failed to initialise JWT source: <error>. Ensure the agent is healthy before starting or restarting the proxy.
For a complete example of a Temporal worker using SPIFFE SVIDs to authenticate with the proxy, see the temporal-proxy-spiffe-worker reference implementation.
If the authentication block is omitted from a workload entirely, the proxy logs a warning at startup and forwards all inbound requests for that workload without any token validation:
WARN  workload configured without worker authentication  {"workload-id": "<id>"}
All calls are still subject to namespace-level authentication (mTLS or API key) before reaching Temporal Cloud.

Build docs developers (and LLMs) love

Get started for freeTalk to us