Change the attached service account

This document explains how to configure an existing virtual machine (VM) to use a different service account. A service account is a special kind of account typically used by an application or compute workload to make authorized API calls.

Service accounts are needed for scenarios where a workload, such as a custom application, needs to access Google Cloud resources or perform actions without end-user involvement. For more information about when to use service accounts, see Best practices for using service accounts.

If you have applications that need to make calls to Google Cloud APIs, Google recommends that you attach a user-managed service account to the VM on which the application or workload is running. Then, you grant the service account IAM roles, which gives the service account–and, by extension, applications running on the VM–access to Google Cloud resources.

Before you begin

If you haven't already, then set up authentication. Authentication is the process by which your identity is verified for access to Google Cloud services and APIs. To run code or samples from a local development environment, you can authenticate to Compute Engine by selecting one of the following options:

Select the tab for how you plan to use the samples on this page:
Console

When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.
gcloud
1. Install the Google Cloud CLI, then initialize it by running the following command:
```
gcloud init
```
  Note: If you installed the gcloud CLI previously, make sure you have the latest version by running gcloud components update.
2. Set a default region and zone.
REST

To use the REST API samples on this page in a local development environment, you use the credentials you provide to the gcloud CLI.
For more information, see Authenticate for using REST in the Google Cloud authentication documentation.

Required roles

To get the permissions that you need to configure service accounts on your VM, ask your administrator to grant you the Compute Instance Admin (v1) (roles/compute.instanceAdmin.v1) IAM role on the VM or your project. For more information about granting roles, see Manage access to projects, folders, and organizations.

This predefined role contains the permissions required to configure service accounts on your VM. To see the exact permissions that are required, expand the Required permissions section:

Required permissions

The following permissions are required to configure service accounts on your VM:

compute.instances.setServiceAccount
compute.instances.stop
compute.instances.start

You might also be able to get these permissions with custom roles or other predefined roles.

Overview

It is recommended that you configure service accounts for your VMs as follows:

Create a new user-managed service account rather than using the Compute Engine default service account, and grant IAM roles to that service account for only the resources and operations that it needs.
Attach the service account to your VM.
Set the cloud platform (https://www.googleapis.com/auth/cloud-platform) scope on your VM. This allows the VM's service account to call the Google Cloud APIs that it has permission to use.
- If you specify the service account by using the Google Cloud console, the VM's access scope automatically defaults to the cloud-platform scope.
- If you specify the service account by using the Google Cloud CLI or Compute Engine API, you can use the scopes parameter to set the access scope.

Set up the service account

You can either create a user-managed service account or use the Compute Engine default service account. A user-managed service account is recommended.

For the selected service account, ensure that the required Identity and Access Management (IAM) roles are assigned.

User-managed

If you don't already have a user-managed service account, create a service account. For detailed instruction, see Set up a service account.

Default

If you are familiar with the Compute Engine default service account and want to use the credentials provided by the default service account instead of creating new service accounts, you can grant IAM roles to the default service account.

Before you assign IAM roles to the default service account, note that:

Granting an IAM role to the default service account affects all VMs that are running as the default service account. For example, if you grant the default service account the roles/storage.objectAdmin role, all VMs running as the default service account with the required access scopes will have permissions granted by the roles/storage.objectAdmin role. Likewise, if you limit access by omitting certain roles, this affects all VMs running as the default service account.
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.

If you are unsure about granting IAM roles to the default service account, create a new user-managed service account instead.

Attach the service account and update the access scope

To change a VM's service account and access scopes, the VM must be temporarily stopped.

If the service account is in a different project than the VM, you must configure the service account for a resource in a different project.

Use one of the following methods to change the service account and access scopes on your VM.

Console

Go to the VM instances page.

Go to VM instances
Click the VM instance name for which you want to change the service account.
If the VM is not stopped, click Stop. Wait for the VM to be stopped.
Click Edit.
Scroll down to the Service Account section.
From the drop-down list, select the service account to assign to the VM.
- If you choose a user-managed service account, the VM's access scope defaults to the recommended cloud-platform scope. If you need a different scope for your user-managed service account, use the gcloud CLI or Compute Engine API to attach the service account.
- If you choose the Compute Engine default service account, you can modify its access scopes in the Google Cloud console.
  - To change scopes, in the Access scopes section, select Set access for each API and set the appropriate scopes for your needs.
  - Recommended If you're not sure of the proper access scopes to set, choose Allow full access to all Cloud APIs and then make sure to restrict access by setting IAM roles on the service account.
Click Save to save your changes.
Click Start/Resume to restart the VM.

gcloud

Stop the VM by using the instances stop command. Replace VM_NAME with the name of your VM instance.
```
gcloud compute instances stop VM_NAME
```
Attach the service account. To attach the service account, use the instances set-service-account command and provide the VM name, the service account email, and the desired scopes. For more information about setting access scopes, see Best practices.
```
gcloud compute instances set-service-account VM_NAME \
  --service-account=SERVICE_ACCOUNT_EMAIL \
  --scopes=SCOPES
```
Replace the following:
- SERVICE_ACCOUNT_EMAIL: the email address for the service account that you created. For example: my-sa-123@my-project-123.iam.gserviceaccount.com. To view the email address, see Listing service accounts.
  
  If you want to remove the service account from the VM, use the --no-service-account flag.
- VM_NAME: the name of the VM instance.
- SCOPES: a comma-separated list of scope URIs or aliases provided in the description for the --scopes flag.
  
  If you want to remove all scopes for the VM, use the --no-scopes flag instead.
For example, the following command assigns the service account my-sa-123@my-project-123.iam.gserviceaccount.com to a VM called example-instance and sets access scopes on that VM to allow read/write access to Compute Engine and read-only access to Cloud Storage:
```
gcloud compute instances set-service-account example-instance \
  --service-account=my-sa-123@my-project-123.iam.gserviceaccount.com \
  --scopes=compute-rw,storage-ro
```
Start the VM by using the instances start command. Replace VM_NAME with the name of your VM instance.
```
gcloud compute instances start VM_NAME
```

REST

Stop the VM by making a POST request using the instances.stop method:
```
POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME/stop
```
Replace the following:
- PROJECT_ID: the project your VM is in
- ZONE: the zone where your VM is located
- VM_NAME: the name of the VM you want to stop
Attach the service account by making a POST request to the setServiceAccount method:
```
POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME/setServiceAccount

{
  "email": "SERVICE_ACCOUNT_EMAIL",
  "scopes": [
    "SCOPE_URI",
    "SCOPE_URI",
    ...
  ]
}
```
Replace the following:
- PROJECT_ID: the project ID for this request.
- ZONE: the zone where this VM belongs to.
- VM_NAME: the name of the VM.
- SERVICE_ACCOUNT_EMAIL: the email address for the service account that you created. For example: my-sa-123@my-project-123.iam.gserviceaccount.com. To view the email address, see Listing service accounts.
- SCOPE_URI: the required scope URI.
For example, the following request uses the service account email my-sa-123@my-project-123.iam.gserviceaccount.com and sets a Cloud Storage and BigQuery scope:
```
POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME/setServiceAccount

{
  "email": "my-sa-123@my-project-123.iam.gserviceaccount.com",
  "scopes": [
    "https://www.googleapis.com/auth/bigquery",
    "https://www.googleapis.com/auth/devstorage.read_only"
  ]
}
```
Start the VM by constructing a POST request using the instances.start method:
```
POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME/start
```
Replace the following:
- PROJECT_ID: the project your VM is in
- ZONE: the zone where your VM is located
- VM_NAME: the name of the VM you want to start

View the service account that is used by a VM

To view all the service accounts in a project, see Listing service accounts.

If you need to identify the service account that is being used by a VM, complete one of the following procedures:

console

Go to the VM instances page.

Go to VM instances
Click the VM instance name for which you want to change the service account.
Go to the API and identity management section. This sections displays the service account and access scope that is used by the VM.

gcloud

Run the gcloud compute instances describe command:

gcloud compute instances describe VM_NAME \
    --format json

The output is similar to the following:

{
  ...
  "serviceAccounts":[
      {
        "email":"123845678986-compute@developer.gserviceaccount.com",
        "scopes":[
            "https://www.googleapis.com/auth/devstorage.full_control"
        ]
      }
  ]
  ...
   }

If the VM isn't using a service account, you receive a response without the serviceAccounts property.

Metadata Server

Query the metadata server from within the VM itself. Make a request to http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/:

user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/" \
-H "Metadata-Flavor: Google"

If you enabled one or more service accounts when you created the instance, this curl command returns output similar to the following:

123845678986-compute@developer.gserviceaccount.com/
default/

If the instance isn't using a service account, you receive an empty response.

Best practices

Limit the privileges of service accounts and regularly check your service account permissions to make sure they are up-to-date.
Delete service accounts with caution. Make sure your critical applications are no longer using a service account before deleting it. If you're not sure whether a service account is being used, we recommend disabling the service account instead of deleting it. Disabled service accounts can be re-enabled if they are still needed.
Mitigate the security risks for your service account. For more information, see Best practices for working with service accounts.

What's next?

Review Service account best practices
Review Authenticate workloads using service accounts