OIDC Authentication and Exact-Match Trigger Filters

Security and authentication for event receivers is the system that allows only authorized events to invoke a Cloud Run service. In this system, Eventarc (opens in a new tab) uses an Identity and Access Management (IAM) service account as the trigger identity, Cloud Pub/Sub (opens in a new tab) carries the event, and Cloud Run (opens in a new tab) verifies the caller before passing the request to application code. Each hop is protected by a separate IAM role grant, so publishing, pulling, and invoking are authorized independently.

1.1Trigger Identity and Least-Privilege Service Accounts

The trigger service account is the identity that Eventarc uses when it invokes the Cloud Run event receiver. If no account is selected, the trigger falls back to the Compute Engine default service account with the email format PROJECT_NUMBER-compute@developer.gserviceaccount.com. That default account is acceptable for testing, but production must use a dedicated user-managed service account with only the minimum permissions it needs.

The person who creates the trigger also needs setup permissions that are separate from runtime delivery. Identity and Access Management (IAM) (opens in a new tab) setup for deployers typically includes:

• Cloud Run Source Developer (roles/run.sourceDeveloper)
• Logs View Accessor (roles/logging.viewAccessor)
• Project IAM Admin (roles/resourcemanager.projectIamAdmin)
• Service Account Admin (roles/iam.serviceAccountAdmin)
• Service Account User (roles/iam.serviceAccountUser)
• Service Usage Admin (roles/serviceusage.serviceUsageAdmin)

Default service accounts no longer receive broad access automatically in newer organizations. The organization policy constraint iam.automaticIamGrantsForDefaultServiceAccounts blocks automatic Editor grants for organizations created after May 3, 2024, so teams must grant less-permissive roles explicitly and can use Policy Simulator to check the impact before removing Editor.

1.2IAM Roles Across Producer, Trigger, and Receiver Boundaries

IAM roles for producers, triggers, and receivers authorize three trust boundaries in the secure event path. The first boundary is the producer publishing to the topic, the second is the trigger pulling from the transport, and the third is the receiver accepting the invocation. The Eventarc trigger depends on these grants before it can become active.

Without the Publisher grant, messages never enter the transport topic. Without the Subscriber and Invoker grants, Eventarc may receive the event but cannot forward it, and Cloud Run rejects the delivery because the caller is not authorized on the destination service.

1.3Authenticated OIDC Invocation of Cloud Run

Authenticated invocation of Cloud Run means the Eventarc trigger calls Cloud Run with an OpenID Connect (OIDC) identity token minted from its service account. Cloud Run verifies that token and the roles/run.invoker binding before routing to the application. By default, Cloud Run services are callable only by Project Owners, Project Editors, and Cloud Run Admins and Invokers, so unauthenticated requests never reach application code. For testing, the Invoker role can be granted at the project level, while production must grant it on the specific receiver service.

A secure receiver is configured in dependency order:

1. Create a dedicated service account: Create a user-managed account for the trigger instead of reusing the Compute Engine default account.
2. Grant least-privilege runtime roles: Grant Pub/Sub Publisher on the topic, Pub/Sub Subscriber for event pulling, and Cloud Run Invoker on the receiver service to that account.
3. Attach the account to both ends: Set the same account as the Cloud Run service identity and as the Eventarc trigger service_account, so the sender and receiver share one verifiable identity.
4. Create the trigger with authenticated delivery: Create the Eventarc trigger with matching criteria type=google.cloud.pubsub.topic.v1.messagePublished, a Pub/Sub transport topic, and a Cloud Run destination that requires authentication.

Eventarc trigger configuration and routing is the set of rules that connects an event source to a Cloud Run destination. An Eventarc (opens in a new tab) trigger listens for events, checks them against filters for type and resource, and forwards matching events to Cloud Run (opens in a new tab) as HTTP POST requests. The trigger definition holds the source, the filters, the destination service, and the identity used to invoke that service.

2.1Trigger Types and Event Providers

Eventarc trigger types define where events come from and which providers are available. Google sources cover Google Cloud providers such as Cloud Pub/Sub, Cloud Storage, Firestore, Firebase Remote Config, and Audit Logs. Custom sources cover customer-defined events, while third-party sources cover non-Google providers that offer an Eventarc source.

Eventarc configuration then narrows the source by selecting an event provider and an event type. The event provider is the product that emits the event, such as Pub/Sub or Cloud Storage, and the event type is the specific action, such as google.cloud.pubsub.topic.v1.messagePublished. Available event types change with the provider, and the event data content type selects application/json or application/protobuf encoding for the payload.

2.2Event Filters for Precise Delivery

Eventarc event filters are exact-match rules that decide which events reach the Cloud Run destination. Eventarc filters compare attributes such as type, resource name, and service, and only events that match all configured criteria are delivered. Filtering does not support wildcards or regular expressions, so values must match exactly.

The core matching criteria typically include:

• Event type: the CloudEvents type, for example google.cloud.pubsub.topic.v1.messagePublished for Pub/Sub messages.
• Resource and service: the monitored resource, such as a specific Pub/Sub topic, Cloud Storage bucket, or audited API, and the originating service for Audit Logs sources.
• Region alignment: the trigger, the monitored resource, and the destination service placed in the same Google Cloud region to reduce latency.
• Payload encoding: application/json or application/protobuf, where JSON payloads are larger and can affect reliability against destination size limits.

After an Eventarc trigger is created, its event source filters cannot be modified. To change filtering, create a new trigger with the corrected filters and delete the old one.

2.3Destination Routing from Source to Cloud Run

Destination routing to Cloud Run is the path that sends each matched event from the event source to a Cloud Run service. Traffic flows from the source to the Eventarc trigger, then from the trigger to the destination service over HTTPS as a POST to the root path / by default or to a configured path such as /route or route/subroute. For Pub/Sub-based delivery, the trigger uses a Pub/Sub transport topic, pulls the message, and forwards it to Cloud Run.

A Cloud Run routing setup moves through an ordered flow:

1. Event occurs: A message is published to the Pub/Sub topic, an object is uploaded to a Cloud Storage bucket, or an audited API call is logged.
2. Trigger matches: Eventarc evaluates the trigger name, event provider, event type, and filters against the event.
3. Destination invoked: Eventarc forwards the matched event to the selected Cloud Run service in the same project using the trigger identity.

The destination Cloud Run service depends on the trigger identity for invocation. The trigger runs under an IAM service account that must have permission to invoke the service, and the Compute Engine default service account is used when no account is selected. For production, a dedicated user-managed service account with the Cloud Run Invoker role (roles/run.invoker) follows least privilege, while retries and network attachments control delivery behavior.

2.4Activation Lifecycle and Trigger Management

The Eventarc trigger activation lifecycle controls when trigger rules become inactive or active. Saving a trigger configuration only stores the rules in the trigger definition and leaves the trigger inactive. Publishing the integration or creating the trigger through Eventarc deploys the rules, and it can take up to two minutes for the trigger to become fully active and start delivering events.

Publishing behavior determines whether Eventarc reuses or replaces the trigger. Publishing a new version with a modified trigger configuration automatically replaces the old trigger and deletes the obsolete one, so the deployment always uses the latest rules. Publishing a new version with the same trigger and configuration reuses the existing trigger instead of creating a duplicate. If trigger creation fails during publication because of configuration errors, the surrounding deployment still publishes but the trigger stays inactive until it is corrected and republished.

Cloud Pub/Sub messaging and push subscription integration is the asynchronous system that decouples event producers from event receivers. Cloud Pub/Sub (opens in a new tab) lets publishers send events to the Pub/Sub service without knowing how or when they will be processed, and Pub/Sub then delivers events to reacting services. This asynchronous integration typically delivers with latencies on the order of 100 milliseconds, without waiting as with synchronous remote procedure calls (RPCs).

3.1Publishers, Topics, and Subscribers

Publishers, topics, and subscribers are the core resources of a Pub/Sub messaging system. A publisher is an event producer that broadcasts an event to a topic, and a subscriber is an event consumer that reacts to events from that topic. A topic is the named channel that holds messages from publishers so Pub/Sub can deliver them to all interested subscribers. Because publishers and subscribers interact only through the topic, many publishers and many subscribers can join the same system independently, which increases flexibility and robustness.

Pub/Sub uses per-message parallelism rather than partition-based messaging. Pub/Sub leases individual messages to subscriber clients, then tracks whether each message is successfully processed. By contrast, partition-based systems force subscribers to process messages in each partition in order and limit concurrent clients to the number of partitions. Per-message leasing maximizes parallelism and helps keep publishers and subscribers independent.

Pub/Sub supports common event-driven patterns including:

• Ingesting user interaction and server events for streaming analytics and data integration pipelines
• Real-time event distribution through an enterprise event bus
• Replicating database change events and refreshing distributed caches
• Parallel processing and workflows that distribute tasks among multiple workers
• Load balancing for reliability across service instances in multiple zones

3.2Push and Pull Delivery Models

Push and pull delivery models control how messages flow from a Pub/Sub topic to a subscriber. A push subscription causes Pub/Sub to deliver each message as an HTTP POST request to a webhook endpoint, such as a Cloud Run service, without the subscriber polling for work. A leased or pull-style delivery causes subscriber clients to obtain individual leased messages and hold each lease until processing succeeds.

Choose a push subscription when the destination is an HTTP service such as Cloud Run (opens in a new tab) that should be invoked directly for each message. Pub/Sub offers push-based delivery of messages as HTTP POST requests to webhooks, and workflow automation can then run on Cloud Run or Cloud Run functions. Pub/Sub also adopts messaging-middleware features such as dead-letter queues and filtering, which help isolate messages that cannot be processed and select which messages reach a subscriber.

3.3Eventarc Routing for Pub/Sub Events

Eventarc (opens in a new tab) routing for Pub/Sub events declares interest in a set of events and routes matching events to a Cloud Run service. The trigger specifies filters, including the event source, and a target Cloud Run service as its destination. For direct Pub/Sub events, the filter type is google.cloud.pubsub.topic.v1.messagePublished, and Eventarc delivers the event to the receiver in CloudEvents format through an HTTP request.

Configuring event routing from Pub/Sub to Cloud Run follows an ordered flow:

1. Deploy receiver: Deploy the Cloud Run event receiver service that will receive and log events.
2. Create trigger: Create an Eventarc trigger with --destination-run-service, --destination-run-region, and --event-filters="type=google.cloud.pubsub.topic.v1.messagePublished".
3. Select topic: Omit --transport-topic to create a new Pub/Sub topic, or set --transport-topic=projects/PROJECT_ID/topics/TOPIC_ID to reuse an existing Pub/Sub topic.
4. Publish message: Publish a message with gcloud pubsub topics publish to generate an event that is routed to the Cloud Run service.

The trigger depends on the Pub/Sub topic as its transport and on the Cloud Run service as its destination. Although the trigger is created immediately, it can take up to two minutes for the trigger to become fully functional. Because Pub/Sub is globally distributed, the topic, publisher, and Eventarc trigger can span projects, so a topic in one project can be published from another project and still route to a Cloud Run service.

3.4Event Receivers on Cloud Run

A Cloud Run event receiver is an HTTP service that accepts CloudEvents from Eventarc or push requests from Pub/Sub. Data flows from the Pub/Sub topic to the subscription or trigger, then as an HTTP request to the Cloud Run service URL, where the service logs the event message and message data. The message payload includes fields such as message data and message ID, and the CloudEvents request carries metadata such as ID, source, type, and time.

Trust and access boundaries control whether Pub/Sub and Eventarc can invoke the receiver. All Cloud Run services are deployed privately by default and cannot be accessed without authentication credentials, while --allow-unauthenticated deploys a publicly accessible receiver. To accept authenticated invocations, the trigger must use a service account with the roles/run.invoker role. To support authenticated Pub/Sub push requests for service agents enabled on or before April 8, 2021, grant the Service Account Token Creator role (roles/iam.serviceAccountTokenCreator) to service-PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com; otherwise this role is granted by default.

Key Facts

• Eventarc invokes a Cloud Run event receiver using an IAM service account that must have the Cloud Run Invoker role on the destination service for OIDC authentication to succeed.
• Eventarc event filters are exact-match rules on type, resource, and service with no wildcard support, and filter changes require creating a new trigger.
• An Eventarc trigger stays inactive after saving and becomes active only after publishing, which can take up to two minutes.
• A Pub/Sub push subscription delivers each message as an HTTP POST to a webhook such as Cloud Run, while leased delivery requires subscriber clients to obtain and hold leases on individual messages.