This document shows you how to grant Identity and Access Management (IAM) roles
and permissions to support routing events from Google Cloud and other sources
to Cloud Run functions using Eventarc.


> [!NOTE]
> **Note:** If you want to attach a service account in one project to an Eventarc trigger in another project, you must first complete the steps outlined in [Support a cross-project service account](https://docs.cloud.google.com/eventarc/docs/use-cross-project-service-account.md.txt).

<br />

1. [Grant project-wide and deployment permissions to the principal creating
   triggers and deploying functions](https://docs.cloud.google.com/eventarc/standard/docs/functions/roles-permissions#project-perms):

   1. The **Eventarc Admin** role gives you full control over all
      Eventarc resources, including specifying a service account
      for the trigger when you create it.

   2. The **Service Account User** role lets a principal impersonate and use
      a service account, including the trigger service account and the function
      runtime or build service accounts.

   3. Depending on how you deploy your function, the **Cloud Run Source
      Developer** and **Service Usage Consumer** roles (when deploying with the
      `gcloud run` CLI or Cloud Run Admin API) or the **Cloud
      Functions Developer** or **Cloud Functions Admin** role (when deploying with
      the `gcloud functions` CLI or Cloud Functions v2 API) let you create
      and update functions.

2. [Grant Eventarc trigger permissions to the trigger service
   account](https://docs.cloud.google.com/eventarc/standard/docs/functions/roles-permissions#trigger-perms):
   The **Eventarc Event Receiver** role lets your Eventarc
   trigger receive events from event providers. You don't need to grant the
   role if you are routing direct events from Cloud Pub/Sub.

3. [Grant Cloud Run functions invocation permissions to the trigger
   service account](https://docs.cloud.google.com/eventarc/standard/docs/functions/roles-permissions#invoker-role):
   The **Cloud Run Invoker** role lets your Eventarc trigger
   invoke an authenticated Cloud Run function.

4. [Grant permissions to Google service agents](https://docs.cloud.google.com/eventarc/standard/docs/functions/roles-permissions.md.txt#agent-perms):

   1. The **Eventarc Service Agent** role lets the Eventarc
      service agent manage underlying transport resources and validate event
      sources. This role is granted by default when you create an
      Eventarc resource for the first time, but you must restore it
      if it is removed.

   2. If you are deploying functions with the `gcloud functions` CLI or
      Cloud Functions v2 API, the **Cloud Functions Service Agent** role
      lets the Cloud Functions service agent create and manage
      Eventarc triggers and underlying Cloud Run
      services. This role is granted by default when you enable the
      Cloud Functions API, but you must restore it if it is removed.

   3. If you are creating a trigger for direct events from Cloud Storage, grant
      the **Pub/Sub Publisher** role to the Cloud Storage service agent.

   4. If you enabled the Cloud Pub/Sub service agent on or before
      April 8, 2021, grant the **Service Account Token Creator** role to the
      Pub/Sub service agent.

For more information about granting IAM roles, see
[Manage access](https://docs.cloud.google.com/iam/docs/granting-changing-revoking-access.md.txt). You might also be
able to get the required permissions through
[custom roles](https://docs.cloud.google.com/iam/docs/creating-custom-roles.md.txt) or other
[predefined roles](https://docs.cloud.google.com/iam/docs/understanding-roles).

## Grant project-wide and deployment permissions

If you are the project creator, you are granted the
[basic Owner role](https://docs.cloud.google.com/iam/docs/roles-overview.md.txt#basic) (`roles/owner`). By
default, this role includes the permissions necessary for full access to most
Google Cloud resources. Otherwise, required roles must be granted by an
administrator on the appropriate resource to the appropriate *principal* (also
known as a member).

For example, a principal can be a Google Account (for end users) or a service
account (for applications and compute workloads). Each principal has its own
identifier, which is typically an email address.

1. The [Eventarc Admin role](https://docs.cloud.google.com/iam/docs/roles-permissions/eventarc.md.txt#eventarc.admin)
   (`roles/eventarc.admin`) gives you full control over all
   Eventarc resources.

   Grant the role on the project:

   ```bash
   gcloud projects add-iam-policy-binding PROJECT_ID \
     --member=PRINCIPAL \
     --role=roles/eventarc.admin
   ```

   Replace the following:
   - `PROJECT_ID`: your Google Cloud project ID.

   - `PRINCIPAL`: an identifier for the trigger creator,
     which usually has the following form:
     `PRINCIPAL_TYPE:ID`. For example,
     `user:my-user@example.com`. For a full list of the possible
     `PRINCIPAL_TYPE` values, see the
     [Policy Binding reference](https://docs.cloud.google.com/iam/docs/reference/rest/v1/Policy.md.txt#Binding).

2. The [Service Account User role](https://docs.cloud.google.com/iam/docs/roles-permissions/iam.md.txt#iam.serviceAccountUser)
   (`roles/iam.serviceAccountUser`) lets a principal run operations as a
   service account.

   You need this role so that you can associate a user-managed service account
   with an Eventarc trigger. You also need it so that you can
   act as the
   [runtime service account](https://docs.cloud.google.com/run/docs/securing/service-identity.md.txt)
   when deploying a Cloud Run function, and as the build service account
   when deploying from source. For more information, see
   [Roles for service account authentication](https://docs.cloud.google.com/iam/docs/service-account-permissions.md.txt).

   You can either grant the role on the project to let the principal
   impersonate multiple service accounts or grant the role on the service account
   to let the principal impersonate only a specific service account.

   Grant the role on the project:

   ```bash
   gcloud projects add-iam-policy-binding PROJECT_ID \
     --member=PRINCIPAL \
     --role=roles/iam.serviceAccountUser
   ```

   Or, grant the role on the service account:

   ```bash
   gcloud iam service-accounts add-iam-policy-binding \
     projects/SERVICE_ACCOUNT_PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT_NAME@SERVICE_ACCOUNT_PROJECT_ID.iam.gserviceaccount.com \
     --member=PRINCIPAL \
     --role=roles/iam.serviceAccountUser
   ```

   Replace the following:
   - `SERVICE_ACCOUNT_PROJECT_ID`: the Google Cloud
     project ID that contains the service account.

   - `SERVICE_ACCOUNT_NAME`: the name of the service
     account.

3. Grant the roles required to deploy your Cloud Run function based on
   how you deploy it:

   - **Deploying with `gcloud run deploy` or the Cloud Run
     Admin API** : Grant the
     [Cloud Run Source Developer role](https://docs.cloud.google.com/iam/docs/roles-permissions/run.md.txt#run.sourceDeveloper)
     (`roles/run.sourceDeveloper`) and the
     [Service Usage Consumer role](https://docs.cloud.google.com/iam/docs/roles-permissions/serviceusage.md.txt#serviceusage.serviceUsageConsumer)
     (`roles/serviceusage.serviceUsageConsumer`) on the project. For more
     information, including required Cloud Build service account roles for
     building from source, see
     [Required roles for deploying Cloud Run functions](https://docs.cloud.google.com/run/docs/deploy-functions.md.txt#required-roles)
     and
     [Create a trigger for functions](https://docs.cloud.google.com/run/docs/triggering/trigger-with-events.md.txt#trigger-functions).

   - **Deploying with `gcloud functions deploy` or the Cloud Functions
     v2 API** : Grant the
     [Cloud Functions Developer role](https://docs.cloud.google.com/iam/docs/roles-permissions/cloudfunctions.md.txt#cloudfunctions.developer)
     (`roles/cloudfunctions.developer`) or the
     [Cloud Functions Admin role](https://docs.cloud.google.com/iam/docs/roles-permissions/cloudfunctions.md.txt#cloudfunctions.admin)
     (`roles/cloudfunctions.admin`) on the project. For more information,
     including required Cloud Build service account roles for
     building from source, see
     [Additional configuration for deployment](https://docs.cloud.google.com/functions/docs/reference/iam/roles.md.txt#additional-configuration)
     and
     [Access control with IAM](https://docs.cloud.google.com/functions/docs/concepts/iam.md.txt).

## Grant Eventarc trigger permissions

Every Eventarc trigger is associated with an
IAM service account at the time the trigger is created. You can
specify a user-managed service account that the trigger uses as its default
identity. If you don't specify a service account during the trigger's creation,
the trigger uses the
[Compute Engine default service account](https://docs.cloud.google.com/iam/docs/service-account-types.md.txt#default)
for its identity.

> [!CAUTION]
> **Caution:** For production environments, we strongly recommend creating a new service account and granting it one or more IAM roles that contain the [minimum permissions required](https://docs.cloud.google.com/iam/docs/best-practices-service-accounts.md.txt#limit-service-account-privileges). You shouldn't use the default service account because it's automatically granted the highly privileged [basic Editor role](https://docs.cloud.google.com/iam/docs/roles-overview.md.txt#basic).

We recommend that you
[create your own user-managed service account](https://docs.cloud.google.com/iam/docs/creating-managing-service-accounts#creating)
to give you greater control and flexibility when managing your trigger.

1. Create a service account and note its name:

   ```bash
   gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \
     --description="DESCRIPTION" \
     --display-name="DISPLAY_NAME"
   ```

   Replace the following:
   - `SERVICE_ACCOUNT_NAME`: the name of the service
     account. This name appears in the email address that identifies the
     service account.

   - `DESCRIPTION`: an optional description of the
     service account.

   - `DISPLAY_NAME`: a service account name to display in
     the Google Cloud console.

2. Grant the
   [Eventarc Event Receiver role](https://docs.cloud.google.com/iam/docs/roles-permissions/eventarc.md.txt#eventarc.eventReceiver)
   (`roles/eventarc.eventReceiver`) on the project to the service account
   associated with your Eventarc trigger so that the trigger can
   receive events from event providers.

   Note that you don't need to grant the Eventarc Event Receiver role if you are
   routing
   [direct events from Cloud Pub/Sub](https://docs.cloud.google.com/run/docs/triggering/pubsub-triggers.md.txt#create-trigger).

   ```bash
   gcloud projects add-iam-policy-binding PROJECT_ID \
     --member=serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com \
     --role=roles/eventarc.eventReceiver
   ```

   Replace `SERVICE_ACCOUNT_NAME` with the name of your
   service account that you noted in the previous step.

## Grant Cloud Run functions invocation permissions

By default, Cloud Run functions require authentication, which means that
they can't be invoked without providing authentication credentials in the
request. For projects with
[domain restricted sharing organization policies](https://docs.cloud.google.com/resource-manager/docs/organization-policy/restricting-domains),
use an authenticated target function rather than one that allows
[public (unauthenticated) access](https://docs.cloud.google.com/run/docs/authenticating/public.md.txt).

1. **If you are routing events to an authenticated Cloud Run function** ,
   grant the
   [Cloud Run Invoker role](https://docs.cloud.google.com/iam/docs/roles-permissions/run.md.txt#run.invoker)
   (`roles/run.invoker`) on the underlying Cloud Run service to
   the service account associated with your Eventarc trigger:

   ```bash
   gcloud run services add-iam-policy-binding FUNCTION_NAME \
     --region=REGION \
     --member=serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com \
     --role=roles/run.invoker
   ```

   Replace the following:
   - `FUNCTION_NAME`: the name of your
     Cloud Run function.

   - `REGION`: the region where your function is deployed.

2. Optionally, you can grant the role on all Cloud Run
   services, functions, and jobs in a Google Cloud project. For more
   information, see
   [Control access on all services and jobs in a project](https://docs.cloud.google.com/run/docs/securing/managing-access.md.txt#control-access-on-all-services).

Note that if you create a trigger for an authenticated
Cloud Run function without granting the Cloud Run Invoker role, the
trigger is created successfully and is active. However, the trigger won't work
as expected and a message similar to the following appears in the logs:

`The request was not authenticated. Either allow unauthenticated
invocations or set the proper Authorization header.`

## Grant permissions to Google service agents

Some Google Cloud services have
[*service agents*](https://docs.cloud.google.com/iam/docs/service-agents.md.txt) that let the
services access your resources. If an API requires a service agent, then
Google creates the service agent after you activate and use the API.

1. **If the [Eventarc Service Agent role](https://docs.cloud.google.com/iam/docs/roles-permissions/eventarc.md.txt#eventarc.serviceAgent)
   (`roles/eventarc.serviceAgent`) was removed from the Eventarc
   service agent**, grant the role on the project so that Eventarc
   can manage underlying transport resources and validate event sources. Otherwise,
   this role is granted by default when you create an Eventarc
   resource for the first time:

   ```bash
   gcloud projects add-iam-policy-binding PROJECT_ID \
     --member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-eventarc.iam.gserviceaccount.com \
     --role=roles/eventarc.serviceAgent
   ```

   Replace `PROJECT_NUMBER` with your Google Cloud
   project number. You can find your project number on the
   [Welcome](https://console.cloud.google.com/welcome)
   page of the Google Cloud console or by running the following command:

   ```bash
   gcloud projects describe PROJECT_ID --format='value(projectNumber)'
   ```
2. **If you are deploying functions with `gcloud functions deploy` or the
   Cloud Functions v2 API and the
   [Cloud Functions Service Agent role](https://docs.cloud.google.com/iam/docs/roles-permissions/cloudfunctions.md.txt#cloudfunctions.serviceAgent)
   (`roles/cloudfunctions.serviceAgent`) was removed from the
   Cloud Functions service agent**, grant the role on the project so that
   the service agent can create and manage Eventarc triggers and
   underlying Cloud Run services. Otherwise, this role is granted
   by default when you enable the Cloud Functions API:

   ```bash
   gcloud projects add-iam-policy-binding PROJECT_ID \
     --member=serviceAccount:service-PROJECT_NUMBER@gcf-admin-robot.iam.gserviceaccount.com \
     --role=roles/cloudfunctions.serviceAgent
   ```

   Note that this role is deprecated and applies only to functions created using
   the Cloud Functions API. For functions created using
   Cloud Run, see the
   [Cloud Run roles and permissions](https://docs.cloud.google.com/iam/docs/roles-permissions/run.md.txt)
   page.
3. **If you are creating a trigger for direct events from
   Cloud Storage** , to support publishing messages to a topic, grant the
   [Pub/Sub Publisher role](https://docs.cloud.google.com/iam/docs/roles-permissions/pubsub.md.txt#pubsub.publisher)
   (`roles/pubsub.publisher`) on the project to the Cloud Storage service
   agent:

   ```bash
   gcloud projects add-iam-policy-binding PROJECT_ID \
     --member=serviceAccount:service-PROJECT_NUMBER@gs-project-accounts.iam.gserviceaccount.com \
     --role=roles/pubsub.publisher
   ```
4. **If you enabled the Cloud Pub/Sub service agent on or before
   April 8, 2021** , to support authenticated Pub/Sub push requests,
   grant the
   [Service Account Token Creator role](https://docs.cloud.google.com/iam/docs/roles-permissions/iam.md.txt#iam.serviceAccountTokenCreator)
   (`roles/iam.serviceAccountTokenCreator`) on the project to the
   Pub/Sub service agent. Otherwise, this role is granted by
   default:

   ```bash
   gcloud projects add-iam-policy-binding PROJECT_ID \
     --member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com \
     --role=roles/iam.serviceAccountTokenCreator
   ```

## What's next

- Learn about
  [access control options in Eventarc](https://docs.cloud.google.com/eventarc/standard/docs/access-control.md.txt).

- Learn how to
  [trigger Cloud Run services and functions with events](https://docs.cloud.google.com/run/docs/triggering/trigger-with-events.md.txt).

- Learn about
  [access control with IAM for Cloud Run functions](https://docs.cloud.google.com/functions/docs/concepts/iam.md.txt).

- Learn about
  [best practices for using service accounts](https://docs.cloud.google.com/iam/docs/best-practices-service-accounts.md.txt).

- Learn how to
  [describe a trigger and verify its associated service account](https://docs.cloud.google.com/eventarc/docs/managing-triggers.md.txt#trigger-describe).