Access control

Vertex AI uses Identity and Access Management (IAM) to manage access to resources. To grant access to a resource, assign one or more roles to a user, group, or service account.

There are different types of IAM roles that can be used in Vertex AI:

  • Predefined roles allow you to grant a set of related permissions to your Vertex AI resources at the project level.

  • Basic roles (Owner, Editor, and Viewer) provide access control to your Vertex AI resources at the project level,and are common to all Google Cloud services.

  • Custom roles enable you to choose a specific set of permissions, create your own role with those permissions, and grant the role to users in your organization.

To add, update, or remove these roles in your Vertex AI project, see the documentation on granting, changing, and revoking access to team members.

Predefined roles for Vertex AI

Role Title Description Permissions Lowest resource
roles/aiplatform.admin Vertex AI Administrator Beta Grants full access to all resources in Vertex AI
  • aiplatform.*
  • resourcemanager.projects.get
  • resourcemanager.projects.list
roles/aiplatform.featurestoreAdmin Vertex AI Feature Store Admin Beta Grants full access to all resources in Vertex AI Feature Store
  • aiplatform.entityTypes.*
  • aiplatform.features.*
  • aiplatform.featurestores.*
  • aiplatform.operations.*
  • resourcemanager.projects.get
  • resourcemanager.projects.list
roles/aiplatform.featurestoreUser Vertex AI Feature Store User Beta Deprecated. Use featurestoreAdmin instead.
  • aiplatform.entityTypes.*
  • aiplatform.features.*
  • aiplatform.featurestores.*
  • aiplatform.operations.*
  • resourcemanager.projects.get
  • resourcemanager.projects.list
roles/aiplatform.migrator Vertex AI Migration Service User Beta Grants access to use migration service in Vertex AI
  • aiplatform.migratableResources.*
roles/aiplatform.user Vertex AI User Beta Grants access to use all resource in Vertex AI
  • aiplatform.annotationSpecs.*
  • aiplatform.annotations.*
  • aiplatform.artifacts.*
  • aiplatform.batchPredictionJobs.*
  • aiplatform.contexts.*
  • aiplatform.customJobs.*
  • aiplatform.dataItems.*
  • aiplatform.dataLabelingJobs.*
  • aiplatform.datasets.*
  • aiplatform.edgeDeploymentJobs.*
  • aiplatform.edgeDeviceDebugInfo.*
  • aiplatform.edgeDevices.*
  • aiplatform.endpoints.*
  • aiplatform.entityTypes.*
  • aiplatform.executions.*
  • aiplatform.features.*
  • aiplatform.featurestores.*
  • aiplatform.humanInTheLoops.*
  • aiplatform.hyperparameterTuningJobs.*
  • aiplatform.indexEndpoints.*
  • aiplatform.indexes.*
  • aiplatform.locations.*
  • aiplatform.metadataSchemas.*
  • aiplatform.metadataStores.*
  • aiplatform.modelDeploymentMonitoringJobs.*
  • aiplatform.modelEvaluationSlices.*
  • aiplatform.modelEvaluations.*
  • aiplatform.models.*
  • aiplatform.nasJobs.*
  • aiplatform.operations.*
  • aiplatform.pipelineJobs.*
  • aiplatform.specialistPools.*
  • aiplatform.studies.*
  • aiplatform.tensorboardExperiments.*
  • aiplatform.tensorboardRuns.*
  • aiplatform.tensorboardTimeSeries.*
  • aiplatform.tensorboards.*
  • aiplatform.trainingPipelines.*
  • aiplatform.trials.*
  • resourcemanager.projects.get
  • resourcemanager.projects.list
roles/aiplatform.viewer Vertex AI Viewer Beta Grants access to view all resource in Vertex AI
  • aiplatform.annotationSpecs.get
  • aiplatform.annotationSpecs.list
  • aiplatform.annotations.get
  • aiplatform.annotations.list
  • aiplatform.artifacts.get
  • aiplatform.artifacts.list
  • aiplatform.batchPredictionJobs.get
  • aiplatform.batchPredictionJobs.list
  • aiplatform.contexts.get
  • aiplatform.contexts.list
  • aiplatform.contexts.queryContextLineageSubgraph
  • aiplatform.customJobs.get
  • aiplatform.customJobs.list
  • aiplatform.dataItems.get
  • aiplatform.dataItems.list
  • aiplatform.dataLabelingJobs.get
  • aiplatform.dataLabelingJobs.list
  • aiplatform.datasets.get
  • aiplatform.datasets.list
  • aiplatform.edgeDeploymentJobs.get
  • aiplatform.edgeDeploymentJobs.list
  • aiplatform.edgeDeviceDebugInfo.*
  • aiplatform.edgeDevices.get
  • aiplatform.edgeDevices.list
  • aiplatform.endpoints.get
  • aiplatform.endpoints.list
  • aiplatform.entityTypes.get
  • aiplatform.entityTypes.list
  • aiplatform.executions.get
  • aiplatform.executions.list
  • aiplatform.executions.queryExecutionInputsAndOutputs
  • aiplatform.features.get
  • aiplatform.features.list
  • aiplatform.featurestores.get
  • aiplatform.featurestores.list
  • aiplatform.humanInTheLoops.get
  • aiplatform.humanInTheLoops.list
  • aiplatform.hyperparameterTuningJobs.get
  • aiplatform.hyperparameterTuningJobs.list
  • aiplatform.indexEndpoints.get
  • aiplatform.indexEndpoints.list
  • aiplatform.indexes.get
  • aiplatform.indexes.list
  • aiplatform.locations.*
  • aiplatform.metadataSchemas.get
  • aiplatform.metadataSchemas.list
  • aiplatform.metadataStores.get
  • aiplatform.metadataStores.list
  • aiplatform.modelDeploymentMonitoringJobs.get
  • aiplatform.modelDeploymentMonitoringJobs.list
  • aiplatform.modelDeploymentMonitoringJobs.searchStatsAnomalies
  • aiplatform.modelEvaluationSlices.*
  • aiplatform.modelEvaluations.get
  • aiplatform.modelEvaluations.list
  • aiplatform.models.get
  • aiplatform.models.list
  • aiplatform.nasJobs.get
  • aiplatform.nasJobs.list
  • aiplatform.operations.*
  • aiplatform.pipelineJobs.get
  • aiplatform.pipelineJobs.list
  • aiplatform.specialistPools.get
  • aiplatform.specialistPools.list
  • aiplatform.specialistPools.update
  • aiplatform.studies.get
  • aiplatform.studies.list
  • aiplatform.tensorboardExperiments.get
  • aiplatform.tensorboardExperiments.list
  • aiplatform.tensorboardRuns.get
  • aiplatform.tensorboardRuns.list
  • aiplatform.tensorboardTimeSeries.get
  • aiplatform.tensorboardTimeSeries.list
  • aiplatform.tensorboardTimeSeries.read
  • aiplatform.tensorboards.get
  • aiplatform.tensorboards.list
  • aiplatform.trainingPipelines.get
  • aiplatform.trainingPipelines.list
  • aiplatform.trials.get
  • aiplatform.trials.list
  • resourcemanager.projects.get
  • resourcemanager.projects.list

Basic roles

The older Google Cloud basic roles are common to all Google Cloud services. These roles are Owner, Editor, and Viewer.

The basic roles provide permissions across Google Cloud, not just for Vertex AI. For this reason, you should use Vertex AI roles whenever possible.

Custom roles

If the predefined IAM roles for Vertex AI don't meet your needs, you can define custom roles. Custom roles enable you to choose a specific set of permissions, create your own role with those permissions, and grant the role to users in your organization. For more information, see Understanding IAM custom roles.

About service accounts and service agents

Service accounts

A service account is a special kind of account used by an application or a virtual machine (VM) instance, not a person. You can create and assign permissions to service accounts to provide specific permissions to a resource or application.

For information about using a service account to customize the permissions available to a custom training container or a container that serves online predictions for a custom-trained model, read Using a custom service account.

Service accounts are identified by an email address.

Service agents

Service agents are Google-managed service accounts that are automatically provided; they enable a service to access resources on your behalf. Vertex AI uses these service agents:

Name Used for Email address
Vertex AI Service Agent Vertex AI functionality service-PROJECT_NUMBER@gcp-sa-aiplatform.iam.gserviceaccount.com
Vertex AI Custom Code Service Agent Custom training code service-PROJECT_NUMBER@gcp-sa-aiplatform-cc.iam.gserviceaccount.com

The Vertex AI Custom Code Service Agent is created only if you run custom training code to train a custom-trained model.

When created, each service agent is granted one of the following predefined roles for your project. Each service agent is granted the role that matches its name.

Role Title Description Permissions
roles/aiplatform.serviceAgent Vertex AI Service Agent Gives Vertex AI the permissions it needs to function.
  • aiplatform.artifacts.*
  • aiplatform.batchPredictionJobs.create
  • aiplatform.batchPredictionJobs.get
  • aiplatform.batchPredictionJobs.list
  • aiplatform.contexts.*
  • aiplatform.customJobs.cancel
  • aiplatform.customJobs.create
  • aiplatform.customJobs.get
  • aiplatform.customJobs.list
  • aiplatform.datasets.create
  • aiplatform.datasets.get
  • aiplatform.datasets.import
  • aiplatform.datasets.update
  • aiplatform.endpoints.explain
  • aiplatform.endpoints.predict
  • aiplatform.entityTypes.exportFeatureValues
  • aiplatform.entityTypes.get
  • aiplatform.executions.*
  • aiplatform.featurestores.exportFeatures
  • aiplatform.featurestores.get
  • aiplatform.metadataSchemas.*
  • aiplatform.metadataStores.*
  • artifactregistry.repositories.create
  • artifactregistry.repositories.downloadArtifacts
  • artifactregistry.repositories.get
  • artifactregistry.repositories.list
  • artifactregistry.repositories.uploadArtifacts
  • artifactregistry.tags.get
  • artifactregistry.versions.get
  • automl.datasets.export
  • automl.datasets.get
  • automl.datasets.list
  • automl.modelEvaluations.list
  • automl.models.get
  • automl.models.list
  • automl.operations.get
  • automl.tableSpecs.get
  • bigquery.datasets.create
  • bigquery.datasets.get
  • bigquery.jobs.create
  • bigquery.jobs.get
  • bigquery.readsessions.create
  • bigquery.tables.create
  • bigquery.tables.export
  • bigquery.tables.get
  • bigquery.tables.getData
  • bigquery.tables.update
  • bigquery.tables.updateData
  • bigtable.tables.get
  • bigtable.tables.list
  • bigtable.tables.readRows
  • datalabeling.annotateddatasets.get
  • datalabeling.datasets.export
  • datalabeling.datasets.get
  • datalabeling.datasets.list
  • datalabeling.operations.get
  • iam.serviceAccounts.actAs
  • iam.serviceAccounts.getAccessToken
  • logging.logEntries.create
  • ml.models.list
  • ml.operations.get
  • ml.versions.get
  • ml.versions.list
  • resourcemanager.projects.get
  • resourcemanager.projects.list
  • serviceusage.services.use
  • storage.buckets.create
  • storage.buckets.delete
  • storage.buckets.get
  • storage.buckets.list
  • storage.objects.create
  • storage.objects.delete
  • storage.objects.get
  • storage.objects.list
  • storage.objects.update
roles/aiplatform.customCodeServiceAgent Vertex AI Custom Code Service Agent Gives Vertex AI Custom Code the proper permissions.
  • aiplatform.annotationSpecs.*
  • aiplatform.annotations.*
  • aiplatform.artifacts.*
  • aiplatform.batchPredictionJobs.*
  • aiplatform.contexts.*
  • aiplatform.customJobs.*
  • aiplatform.dataItems.*
  • aiplatform.dataLabelingJobs.*
  • aiplatform.datasets.*
  • aiplatform.edgeDeploymentJobs.*
  • aiplatform.edgeDeviceDebugInfo.*
  • aiplatform.edgeDevices.*
  • aiplatform.endpoints.*
  • aiplatform.entityTypes.*
  • aiplatform.executions.*
  • aiplatform.features.*
  • aiplatform.featurestores.*
  • aiplatform.humanInTheLoops.*
  • aiplatform.hyperparameterTuningJobs.*
  • aiplatform.indexEndpoints.*
  • aiplatform.indexes.*
  • aiplatform.locations.*
  • aiplatform.metadataSchemas.*
  • aiplatform.metadataStores.*
  • aiplatform.modelDeploymentMonitoringJobs.*
  • aiplatform.modelEvaluationSlices.*
  • aiplatform.modelEvaluations.*
  • aiplatform.models.*
  • aiplatform.nasJobs.*
  • aiplatform.operations.*
  • aiplatform.pipelineJobs.*
  • aiplatform.specialistPools.*
  • aiplatform.studies.*
  • aiplatform.tensorboardExperiments.*
  • aiplatform.tensorboardRuns.*
  • aiplatform.tensorboardTimeSeries.*
  • aiplatform.tensorboards.*
  • aiplatform.trainingPipelines.*
  • aiplatform.trials.*
  • artifactregistry.repositories.downloadArtifacts
  • artifactregistry.repositories.get
  • artifactregistry.repositories.list
  • artifactregistry.tags.get
  • artifactregistry.versions.get
  • bigquery.datasets.create
  • bigquery.datasets.get
  • bigquery.jobs.create
  • bigquery.jobs.get
  • bigquery.readsessions.create
  • bigquery.tables.create
  • bigquery.tables.export
  • bigquery.tables.get
  • bigquery.tables.getData
  • bigquery.tables.update
  • bigquery.tables.updateData
  • iam.serviceAccounts.get
  • iam.serviceAccounts.getAccessToken
  • iam.serviceAccounts.getOpenIdToken
  • iam.serviceAccounts.implicitDelegation
  • iam.serviceAccounts.list
  • iam.serviceAccounts.signBlob
  • iam.serviceAccounts.signJwt
  • logging.logEntries.create
  • resourcemanager.projects.get
  • resourcemanager.projects.list
  • serviceusage.services.use
  • storage.buckets.create
  • storage.buckets.delete
  • storage.buckets.get
  • storage.buckets.list
  • storage.objects.create
  • storage.objects.delete
  • storage.objects.get
  • storage.objects.list
  • storage.objects.update

Granting Vertex AI service agents access to other resources

Sometimes you need to grant additional roles to a Vertex AI service agent. For example, if you need Vertex AI to access a Cloud Storage bucket in a different project, you will need to grant one or more additional roles to the service agent.

Role addition requirements for BigQuery

The following table described the required additional roles needed to be added to the Vertex AI Service Agent for BigQuery tables or view in a different project or backed by an external data source.

The term home project refers to the project where the Vertex AI dataset or model is located. The term foreign project refers to any other project.

Table type Table project Data source project Role addition required
Native BigQuery table Home project N/A None.
Native BigQuery table Foreign project N/A BigQuery Data Viewer for foreign project. Learn more.
BigQuery view Home project N/A None.
BigQuery view Foreign project N/A BigQuery Data Viewer for foreign project. Learn more.
External BigQuery data source backed by Bigtable Home project Home project Bigtable Reader for home project. Learn more.
External BigQuery data source backed by Bigtable Home project Foreign project Bigtable Reader for foreign project. Learn more.
External BigQuery data source backed by Bigtable Foreign project Foreign project BigQuery Reader and Bigtable Reader for foreign project. Learn more.
External BigQuery data source backed by Cloud Storage Home project Home project None.
External BigQuery data source backed by Cloud Storage Home project Foreign project Storage Object Viewer for foreign project. Learn more.
External BigQuery data source backed by Cloud Storage Foreign project Foreign project Storage Object Viewer and BigQuery Data Viewer for foreign project. Learn more.
External BigQuery data source backed by Google Sheets Home project N/A Share your Sheets file with the Vertex AI service account. Learn more.
External BigQuery data source backed by Google Sheets Foreign project N/A BigQuery Reader for foreign project and share your Sheets file with the Vertex AI service account.

Role addition requirements for Cloud Storage

If you are accessing data in a Cloud Storage bucket in a different project, you must give the Storage > Storage Object Viewer role to Vertex AI in that project. Learn more.

If you are using a Cloud Storage bucket to receive data from your local computer for an import operation, and the bucket is in a different project than Cloud project, you must give the Storage > Storage Object Creator role to Vertex AI in that project. Learn more.

Granting access to Vertex AI to resources in your home project

To grant additional roles to a service agent for Vertex AI in your home project:

  1. Go to the IAM page of the Cloud Console for your home project.

    Go to the IAM page

  2. Select the Include Google-provided role grants checkbox.

  3. Determine the service agent you want to grant the permissions to and click the pencil icon.

    You can filter for Member:@gcp-sa-aiplatform-cc.iam.gserviceaccount.com to find the Vertex AI service agents.

  4. Grant the required roles to the service account and save your changes.

Granting access to Vertex AI to resources in a different project

When you use data sources or destinations in a different project, you must give the Vertex AI service account permissions in that project. The Vertex AI service account is automatically created when you enable the Vertex AI API.

To add permissions to Vertex AI in a different project:

  1. Go to the IAM page of the Cloud Console for your home project (the project where you are using Vertex AI).

    Go to the IAM page

  2. Select the Include Google-provided role grants checkbox.

  3. Determine the service agent you want to grant the permissions to and copy its email address (listed under Member).

    You can filter for Member:@gcp-sa-aiplatform-cc.iam.gserviceaccount.com to find the Vertex AI service agents.

  4. Change projects to the project where you need to grant the permissions.

  5. Click Add, and enter the email address in New members.

  6. Add all required roles and click Save.

Providing access to Google Sheets

If you use an external BigQuery data source backed by Google Sheets, you must share your sheet with the Vertex AI service account. The Vertex AI service account is automatically created when you enable the Vertex AI API.

To authorize Vertex AI to access your Sheets file:

  1. Go to the IAM page of the Cloud Console.

    Go to the IAM page

  2. Look for the service account with the name Vertex AI Service Agent and copy its email address (listed under Member).

  3. Open your Sheets file and share it with that address.

What's next