Service accounts  |  Compute Engine Documentation  |  Google Cloud (2024)

This page describes how service accounts work with Compute Engine.

For step-by-step information about attaching a service account to avirtual machine (VM) instance, review one of the following documents:

• To set up service account during VM creation, seeCreate a VM that uses a user-managed service account.
• To set up service account on an existing VM, seeChange the attached service account.

To learn about best practices for creating and managing service accounts, readtheBest practices for working with service accountsdocumentation.

What is a service account?

A service account is a special kind of accountused by an application or compute workload, rather than a person. Serviceaccounts are managed by Identity and Access Management (IAM).

Keep the following in mind when using service accounts with your VMs:

• You can attach the same service account to multiple VMs, but a single VMcan only have one service account attached to it.
• If you attach the same service account to multiple VMs, any subsequentchanges you make to the service account affects all VMs that use the serviceaccount. This includes any changes you make to theIAM roles granted to the service account.For example, if you remove a role, allVMs using the service account lose the permissions granted by that role.

How Compute Engine uses service accounts

Compute Engine uses two types of service accounts:

• User-managed service accounts
• Service agents

A user-managed service account can be attached to a Compute Engineinstance to provide credentials to applications running on the instance. Thesecredentials are used by the application for authentication to Google CloudAPIs, and authorization to access Google Cloud resources. Onlyuser-managed service accounts can be attached to an instance, and an instancecan have only one attached service account. You can change the service accountthat is attached to an instance at creation time or later on.

Service agents are used by the instance to access internal processes on yourbehalf.

In addition, you can create firewall rules that allow ordeny traffic to and from instances based on the service account that youassociate with each instance.

How authorization is determined

The authorization provided to applications hosted on a Compute Engineinstance is limited by two separate configurations: theroles granted to the attached service account, and theaccess scopes that you set on the instance. Both of theseconfigurations must allow access before the application running on the instancecan access a resource.

Suppose you have an app that reads and writes files on Cloud Storage, it mustfirst authenticate to the Cloud Storage API. You can create an instance with thecloud-platform scope and attach a service account to the instance. You canthen grant Identity and Access Management (IAM) roles to the service account to give yourapp access to the appropriate resources. Your app uses the service accountcredentials to authenticate to the Cloud Storage API without embedding anysecret keys or user credentials in your instance, image, or app code. Your appalso uses the authorization provided by the IAM roles on theservice account to access resources.For more information about authorization, see Authorizationon this page.

User-managed service accounts

User-managed service accounts include new service accounts that you explicitlycreate and the Compute Engine default service account.

New service accounts

You can create and manage your own service accounts usingIAM. After you create an account, you grant the accountIAM roles and set up instances to run as the service account.Apps running on instances with the service account attached can use theaccount's credentials to make requests to other Google APIs.

To create and set up a new service account, seeCreate a VM that uses a user-managed service account.

Compute Engine default service account

New projects that haveenabled theCompute Engine API have a Compute Engine default serviceaccount, which has the following email:

PROJECT_NUMBER-compute@developer.gserviceaccount.com

The Compute Engine default service account has the followingattributes:

• Automatically created, with an autogenerated name and email address, and addedto your project when you enable the Compute Engine API. You havefull control over the account.
• Attached by default to all VMs that you created by using the Google Cloud CLIor the Google Cloud console. You can override this behavior by specifyinga different service account when you create the VM, or by explicitlyspecifying that no service account be attached to the VM.

• Depending on your organization policy configuration, the default service account might automatically be granted the Editor role on your project. We strongly recommend that you disable the automatic role grant by enforcing the iam.automaticIamGrantsForDefaultServiceAccounts organization policy constraint. If you created your organization after May 3, 2024, this constraint is enforced by default.

  If you disable the automatic role grant, you must decide which roles to grant to the default service accounts, and then grant these roles yourself.

  If the default service account already has the Editor role, we recommend that you replace the Editor role with less permissive roles. To safely modify the service account's roles, use Policy Simulator to see the impact of the change, and then grant and revoke the appropriate roles.

You can disable or delete this service account from your project, but doing somight cause any applications that depend on the service account's credentials tofail. If you accidentally delete the Compute Engine default serviceaccount, you can try to recover the account within 30 days. For moreinformation, see Delete and undelete service accounts.

If the Compute Engine default service account was deleted more than30 days ago, you can try to recover the service account by following the processin Troubleshooting default service accounts.

Service agents

Service agents are createdand managed by Google Cloud and assigned to your project automatically. Theseaccounts represent different Google Cloud services, and each accounttypically has some level of access to your Google Cloud resources.

You cannot attach service agents to a Compute Engine instance.

Google APIs Service Agent

Apart from the default service account, all projects enabled withCompute Engine come with a Google APIs Service Agent,identifiable using the email:

PROJECT_NUMBER@cloudservices.gserviceaccount.com

This service agent is designed specifically to run internal Googleprocesses on your behalf. This service agent is owned by Google and is not listed inthe Service Accounts section of Google Cloud console. By default, thisservice agent is automatically granted the project editor role on the project and islisted in the IAM section of Google Cloud console.This service agentt is only deleted when the project is deleted. However, youcan change the roles granted to this account, including revoking all access toyour project.

Certain resources rely on the default editor permissions granted to this service agent.For example, managed instance groups and autoscaling uses the credentials of thisservice agent to create, delete, and manage instances. If you revoke permissionsto this service agent, or modify the permissions in such a way that it doesn'tgrant permissions to create instances, this will cause managed instance groupsand autoscaling to stop working.

For these reasons, you should not modify this service agent's roles unless arole recommendation explicitly suggests thatyou modify them.

Compute Engine Service Agent

All projects that have enabled theCompute Engine API have a Compute Engine ServiceAgent, which has the following email:

service-PROJECT_NUMBER@compute-system.iam.gserviceaccount.com

This service agent is designed specifically forCompute Engine to perform its service duties on your project.It relies on the Service Agent IAM Policy granted on yourGoogle Cloud Project. It is also the service agentCompute Engine uses toaccess the user-managed service account on VMinstances. Google owns this account, but it is specific to your project. Thisservice agent is hidden from theIAM page in theconsole unless you select Include Google-provided role grants.By default, this service agent is automatically granted the compute.serviceAgent role on your project.

This service agent is deleted only when you delete your project. Youcan change the roles granted to this service agent and revoke all accessto your project from this agent. Revoking or changing the permissions forthis service agent prevents Compute Engine from accessing theidentities of your service accounts on your VMs, and can cause outages ofsoftware running inside your VMs.

For these reasons, you should avoid modifying the roles for this service agentas much as possible.

Attaching a service account to an instance

To avoid providing an application with excess permissions, we recommend that youcreate a user-managed service account, grant it only the roles your applicationneeds to function properly, and attach it to your Compute Engineinstance. Your code can then useApplication Default Credentialsto authenticate with the credentials provided by the service account.

You can attach a service account to a Compute Engine instance whenyou create the instance, or later. Only one service account can be attachedto an instance at a time; if you attach a service account to an instance thatalready has a service account attached, the previous service account is nolonger used by that instance.

When you attach a service account to a Compute Engine instance, you mustalso ensure that the scopes set on the instance are correct. Otherwise, your appmight not be able to access all of the APIs it needs. For more information, seeAccess scopes on this page.

For step-by-step information about attaching a service account to aCompute Engine instance, review one of the following documents:

• Create a VM that uses a user-managed service account
• Change the attached service account

Authorization

When you set up an instance to run as a service account, you determine the levelof access the service account has by the IAM roles that yougrant to the service account.If the service account has no IAM roles, then no resources canbe accessed using the service account on that instance.

Furthermore, an instance's access scopes determine the default OAuth scopes forrequests made through the gcloud CLI and client libraries on theinstance. As a result, access scopes potentially further limit access to APImethods when authenticating through OAuth. However, they don't extend to otherauthentication protocols like gRPC.

The best practice is to set the full cloud-platform access scope on theinstance, then control the service account's access using IAMroles.

Essentially:

• IAM restricts access to APIs based on the IAMroles that are granted to the service account.
• Access scopes potentially further limit access to API methods.

Both access scopes and IAM roles are described in detail in thefollowing sections.

IAM roles

You mustgrant the appropriate IAM roles to a service accountto allow that service account access to relevant API methods.

For example, you can grant a service account the IAM roles formanaging Cloud Storage objects, or for managing Cloud Storagebuckets, or both, which limits the account to the permissions granted by thoseroles.

When you grant an IAM role to a service account, any applicationrunning on an instance that has that service account attached will have theauthorization conferred by that role.

Some things to keep in mind:

• Some IAM roles are in Beta.

  If there isn't a predefined role for the access level you want, you cancreate and grant custom roles.

• You must set access scopes on the instance to authorize access.

  While a service account's access level is determined by the rolesgranted to the service account, an instance's access scopes determine thedefault OAuth scopes for requests made through the gcloud CLIand client libraries on the instance. As a result, access scopes potentiallyfurther limit access to API methods when authenticating through OAuth.

Access scopes

Access scopes are the legacy method of specifying authorization for yourVM instance. They define the default OAuth scopes used in requests from thegcloud CLI or the client libraries. Access scopes don't applyfor calls made using gRPC.

Access scopes apply on a per-VM basis and persists only for the life of the VM.You can set access scopes when creating a VM orupdate the access scopeon an existing VM.

Generally, the documentation for each API method lists the scopesrequired for that method. For example, the instances.insert method provides alist of valid scopes in itsauthorizationsection.

Access scopes have no effect if you have not enabled the related API on theproject that the service account belongs to. For example, granting an accessscope for Cloud Storage on a virtual machine instance allows theinstance to call the Cloud Storage API only if you have enabled theCloud Storage API on the project.

Default scopes

When you create a new Compute Engine instance, it is automaticallyconfigured with the following access scopes:

• Read-only access to Cloud Storage:
  https://www.googleapis.com/auth/devstorage.read_only
• Write access to write Compute Engine logs:
  https://www.googleapis.com/auth/logging.write
• Write access to publish metric data to your Google Cloud projects:
  https://www.googleapis.com/auth/monitoring.write
• Read-only access to Service Management features required for Google CloudEndpoints^(Alpha):
  https://www.googleapis.com/auth/service.management.readonly
• Read or write access to Service Control features required for Google CloudEndpoints^(Alpha):
  https://www.googleapis.com/auth/servicecontrol
• Write access to Cloud Trace allows an application running on aVM to write trace data to a project.
  https://www.googleapis.com/auth/trace.append

Scopes best practice

There are manyaccess scopesavailable to choose from, but a best practice is to set the cloud-platformaccess scope, which is an OAuth scope for Google Cloud services, and thencontrol the service account's access by granting it IAM roles.

https://www.googleapis.com/auth/cloud-platform

Scopes examples

Following the scopes best practice, if you enabled the cloud-platform accessscope on an instance and then granted the followingpredefined IAM roles:

• roles/compute.instanceAdmin.v1
• roles/storage.objectViewer
• roles/compute.networkAdmin

Then the service account has only the permissions included in those three roles.Applications impersonating that service account cannot perform actions outsideof these roles despite the Google Cloud access scope.

On the other hand, if you grant a more restrictive scope on the instance, likethe Cloud Storage read-only scope(https://www.googleapis.com/auth/devstorage.read_only), andset the roles/storage.objectAdmin administrator role on the serviceaccount, then by default, requests from the gcloud CLI and theclient libraries wouldn't be able to manage Cloud Storage objects fromthat instance, even though you granted the service account theroles/storage.ObjectAdmin role. This is because the Cloud Storageread-only scope does not authorize the instance to manipulateCloud Storage data.

Example access scopes include the following:

• https://www.googleapis.com/auth/cloud-platform. View and manage your dataacross Google Cloud services in the specifiedGoogle Cloud project.
• https://www.googleapis.com/auth/compute. Full control access toCompute Engine methods.
• https://www.googleapis.com/auth/compute.readonly. Read-only access toCompute Engine methods.
• https://www.googleapis.com/auth/devstorage.read_only. Read-only access toCloud Storage.
• https://www.googleapis.com/auth/logging.write. Write access to theCompute Engine logs.

What's next

• Authenticate workloads using service accounts.
• Learn more about creating and managing service accounts.
• Learn more about IAM.
• Learn about other Compute Engine access control options.
• Learn how to view audit logsto monitor how your Compute Engine resources are modified.
• If you need to use a service account from a different project, read aboutconfiguring service accounts for a resource in a different project.