This page describes how to use service accounts to enable apps running onyour virtual machine (VM) instances to authenticate to Google Cloud APIs andauthorize access to resources.

To use service accounts for authentication, you must first ensure that your VMis configured to use a service account. To do this complete one of the followingprocedures:

• 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.

Before you begin

• Review theService accounts overview.
• If you haven't already, set upauthentication. Authentication verifies your identity 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:

  To use the Python samples on this page in a local development environment, install and initialize the gcloud CLI, and then set up Application Default Credentials with your user credentials.

  Install the Google Cloud CLI.

  If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  Note: If you installed the gcloud CLI previously, make sure you have the latest version by runninggcloud components update.

  If you're using a local shell, then create local authentication credentials for your user account:

  gcloudauthapplication-defaultlogin

  You don't need to do this if you're using Cloud Shell.

  If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.

  For more information, see Set up authentication for a local development environment.

Overview

After you have set up a VM instance to run using a service account, an applicationrunning on the VM instance can use one of the following methods for authentication:

• For most applications, choose one of the following:
  • Use Application Default Credentials and a client library
  • Use the Google Cloud CLI
• For applications that require an OAuth2 access token,request and use access tokens directly from the metadata server

Authenticating applications using service account credentials

After setting up an instance to run as a service account, you can useservice account credentials to authenticate applications running on the instance.

Authenticating applications with a client library

Client libraries can useApplication Default Credentialsto authenticate with Google APIs and send requests to those APIs.Application Default Credentials lets applications automatically obtaincredentials from multiple sources so you can test your application locally andthen deploy it to a Compute Engine instance without changing theapplication code.

For information about setting up Application Default Credentials, seeProvide credentials to Application Default Credentials.

This example uses thePython client libraryto authenticate and make a request to the Cloud Storage API to list the buckets ina project. The example uses the following procedure:

1. Obtain the necessary authentication credentials for the Cloud Storage APIand initialize the Cloud Storage service with thebuild() methodand the credentials.
2. List buckets in Cloud Storage.

You can run this sample on an instance that has access to manage buckets inCloud Storage.

importargparsefromtypingimportListfromgoogle.cloudimportstoragedefcreate_client()->storage.Client:"""    Construct a client object for the Storage API using the    application default credentials.    Returns:        Storage API client object.    """# Construct the service object for interacting with the Cloud Storage API -# the 'storage' service, at version 'v1'.# Authentication is provided by application default credentials.# When running locally, these are available after running# `gcloud auth application-default login`. When running on Compute# Engine, these are available from the environment.returnstorage.Client()deflist_buckets(client:storage.Client,project_id:str)->List[storage.Bucket]:"""    Retrieve bucket list of a project using provided client object.    Args:        client: Storage API client object.        project_id: name of the project to list buckets from.    Returns:        List of Buckets found in the project.    """buckets=client.list_buckets()returnlist(buckets)defmain(project_id:str)->None:client=create_client()buckets=list_buckets(client,project_id)print(buckets)if__name__=="__main__":parser=argparse.ArgumentParser(description=__doc__,formatter_class=argparse.RawDescriptionHelpFormatter)parser.add_argument("project_id",help="Your Google Cloud Project ID.")args=parser.parse_args()main(args.project_id)

For most applications, you can authenticate by usingApplication Default Credentials,which finds credentials and manages tokens for you. However, if your applicationrequires you to provide an OAuth2 access token, Compute Engine lets youget an access token from its metadata server for use in your application.

There are several options for obtaining and using theseaccess tokens to authenticate your applications. For example, you can usecurl to create a simple request, or use a programming language like Pythonfor more flexibility.

importargparseimportrequestsMETADATA_URL="http://metadata.google.internal/computeMetadata/v1/"METADATA_HEADERS={"Metadata-Flavor":"Google"}SERVICE_ACCOUNT="default"defget_access_token()->str:"""    Retrieves access token from the metadata server.    Returns:        The access token.    """url=f"{METADATA_URL}instance/service-accounts/{SERVICE_ACCOUNT}/token"# Request an access token from the metadata server.r=requests.get(url,headers=METADATA_HEADERS)r.raise_for_status()# Extract the access token from the response.access_token=r.json()["access_token"]returnaccess_tokendeflist_buckets(project_id:str,access_token:str)->dict:"""    Calls Storage API to retrieve a list of buckets.    Args:        project_id: name of the project to list buckets from.        access_token: access token to authenticate with.    Returns:        Response from the API.    """url="https://www.googleapis.com/storage/v1/b"params={"project":project_id}headers={"Authorization":f"Bearer{access_token}"}r=requests.get(url,params=params,headers=headers)r.raise_for_status()returnr.json()defmain(project_id:str)->None:"""    Retrieves access token from metadata server and uses it to list    buckets in a project.    Args:        project_id: name of the project to list buckets from.    """access_token=get_access_token()buckets=list_buckets(project_id,access_token)print(buckets)if__name__=="__main__":parser=argparse.ArgumentParser(description=__doc__,formatter_class=argparse.RawDescriptionHelpFormatter)parser.add_argument("project_id",help="Your Google Cloud project ID.")args=parser.parse_args()main(args.project_id)

Access tokens expire after a short period of time. The metadata server cachesaccess tokens until they have 5 minutes of remaining time before theyexpire. If tokens are unable to be cached, requests that exceed 50 queriesper second might be rate limited. Your applications must have a valid accesstoken for their API calls to succeed.

Authenticating tools on an instance using a service account

Some applications might use commands from the gcloud CLI, which isincluded by default in most Compute Engine images. Thegcloud CLI automatically recognizes an instance's service account andrelevant permissions granted to the service account. Specifically, if you grantthe correct roles to the service account, you can use the gcloud CLIfrom your instances without having to usegcloud auth login.

This service account recognition happens automatically and applies only to thegcloud CLI that is included with the instance. If you createnew tools or add custom tools, you must authorize your applicationusing a client library or byusing access tokens directly in your application.

To take advantage of automatic service account recognition,grant the appropriate IAM rolesto the service account andattach the service account to the instance.For example, if you grant a service account theroles/storage.objectAdminrole, the gcloud CLI can automatically manage and accessCloud Storage objects.

Likewise, if you enableroles/compute.instanceAdmin.v1 for the service account,thegcloud compute tool can automatically manage instances.

What's next

• Authenticate workloads to other workloads over mTLS.
• Learn more aboutService Accounts.
• Learn more aboutCompute Engine IAM roles and permissions.
• Learn more aboutbest practices for working with service accounts.