Skip to main content
Deploy your Restate services as containers on Google Cloud Run. Restate can invoke private Cloud Run services natively by minting short-lived, Google-signed OIDC ID tokens for each discovery and invocation request.
Native Google OIDC authentication to private Cloud Run services requires a Google-recognized identity for restate-server: either an ambient GCP workload identity, or an AWS identity federated into your Google Cloud project via a workload identity provider. On Restate Cloud, use the latter — see connecting Google Cloud Run services for the environment-specific trust setup, then register with the flags described on this page.

​
Set up your service on Cloud Run

Package your Restate service as a container image and deploy it to Cloud Run following the Cloud Run documentation. A typical Restate service exposes its handler on port 9080; configure the Cloud Run service to forward traffic to whichever port your container listens on. Restate’s service deployment protocol uses HTTP/2 (h2c), so the Cloud Run service must use end-to-end HTTP/2 to the container. Enable it when you deploy with --use-http2 (equivalently, the run.googleapis.com/use-http2 annotation); without it, discovery and invocation fail with an upstream protocol error.
For a private Cloud Run service, leave the default access policy in place (no unauthenticated invocations). Restate authenticates to the service using a Google OIDC ID token, which Cloud Run validates before forwarding the request to your container.

​
Register the service with native authentication

When registering an HTTP deployment, opt into native Google OIDC authentication with --gcp-id-token. Restate mints a Google-signed ID token for every discovery and invocation request and attaches it as X-Serverless-Authorization: Bearer <token>. Cloud Run validates this header in precedence over Authorization and strips it before forwarding the request to your container, so any Authorization value you set via --extra-header reaches the workload unchanged.
To call the Cloud Run service as a specific service account, impersonate it via the IAM Credentials generateIdToken API:
--gcp-impersonate-service-account implies --gcp-id-token.

​
Custom domains and audience overrides

By default, Restate derives the OIDC aud claim from the deployment URL origin (scheme, host, and optional port). If your Cloud Run service sits behind a custom domain, a load balancer, or a traffic tag, set the audience explicitly to the canonical Cloud Run service URL:
--gcp-audience also implies --gcp-id-token.

​
Updating or removing authentication

Authentication configuration is set when the deployment is registered. To rotate the impersonation target, change the audience, or remove authentication entirely, re-register with --force:
Re-registration with --force re-runs discovery against the deployment, so the new configuration must itself be able to reach the service. Removing authentication from a service that still requires authenticated invocations therefore fails at discovery with 403 Forbidden; only remove authentication once the service accepts the request without a token.

​
Credentials available to Restate

Restate discovers credentials through Google’s Application Default Credentials (ADC) chain. Not every ADC source can mint an OIDC ID token directly; the table below summarizes what works. When the ambient identity cannot mint ID tokens for arbitrary audiences, pair it with --gcp-impersonate-service-account so Restate calls the IAM Credentials generateIdToken API on a target service account that the ambient identity is authorized to impersonate.

​
AWS-hosted Restate: workload identity federation

A Restate server whose ambient identity is an AWS identity (such as Restate Cloud, or a self-hosted deployment on EKS/EC2) can mint Google ID tokens without any Google credential, by exchanging a signed AWS identity assertion through a workload identity federation provider in your Google Cloud project. Register with the provider’s full resource name, always paired with a service account to impersonate:
The server operator configures which AWS role is assumed for federation (worker.invoker.gcp-federation in the server configuration); the provider you create must trust that role, and the impersonation grant is made to the resulting federated subject. On Restate Cloud this is preconfigured — follow connecting Google Cloud Run services for the exact trust setup.

​
IAM roles

The principal whose identity ends up in the minted token must hold:
  • roles/run.invoker on the target Cloud Run service, so that Cloud Run IAM accepts the request.
  • roles/iam.serviceAccountOpenIdTokenCreator on the impersonation target, when --gcp-impersonate-service-account is used.

​
Self-hosted Restate

For self-hosted Restate calling private Cloud Run services, ensure one of the following:
  • The Restate process can reach Google’s metadata server (typical on GCE, GKE, or Cloud Run hosts), or
  • GOOGLE_APPLICATION_CREDENTIALS points to a service-account JSON key file readable by the Restate user.
Restate does not contact any Google API or read any ADC source until the first deployment with native authentication enabled is observed.

​
Local development

For local development, run gcloud auth application-default login to populate ADC. This is distinct from gcloud auth login, which only populates user credentials for the gcloud tool itself. Authorized-user ADC credentials cannot mint ID tokens for arbitrary audiences without impersonation, so pair them with --gcp-impersonate-service-account for the dev flow.

​
Token caching and rotation

Credentials are cached per identity — (workload identity provider, impersonated service account, audience) — and shared across discovery and invocations. Each cached credential refreshes its token proactively in the background, so steady-state requests never wait on a mint. Idle credentials are evicted after an hour of disuse and rebuilt transparently on the next request.