Understanding service accounts

Background

A service account is a special type of Google account intended to represent a non-human user that needs to authenticate and be authorized to access data in Google APIs.

Typically, service accounts are used in scenarios such as:

• Running workloads on virtual machines (VMs).
• Running workloads on on-premises workstations or data centers that call Google APIs.
• Running workloads which are not tied to the lifecycle of a human user.

Your application assumes the identity of the service account to call Google APIs, so that the users aren't directly involved.

Managing service accounts

Once you decide that you need a service account, you can ask yourself the following questions to understand how you're going to use the service account:

• What resources can the service account access?
• What permissions does the service account need?
• Where will the code that assumes the identity of the service account be running: on Google Cloud Platform or on-premises?

Use the following flowchart to figure out the responses to the above questions:

Note that service accounts can be thought of as both a resource and as an identity.

When thinking of the service account as an identity, you can grant a role to a service account, allowing it to access a resource (such as a project).

When thinking of a service account as a resource, you can grant roles to other users to access or manage that service account.

Granting access to service accounts

Granting access to a service account to access a resource is similar to granting access to any other identity. For example, if you have an application running on Google Compute Engine and you want the application to only have access to create objects in Google Cloud Storage. You can create a service account for the application and grant it the Storage Object Creator role. The following diagram illustrates this example:

Learn about Granting roles to service accounts.

Impersonating a service account

There are three ways to impersonate a service account to access Google APIs:

• Authentication using RSA private keys
• Authorization using Cloud IAM policies
• Deploying jobs on Google Cloud services

Note: Users that can impersonate service accounts via any of the above mechanisms can indirectly access all resources the service account has access to.

Authentication using RSA private keys

All service accounts have Google Cloud-managed key pairs which are regularly rotated, and the private keys are held in escrow by the platform and cannot be accessed directly.

It's also possible to manually create a user-managed key pair. Google Cloud will generate the private/public keys, storing the public key, and provides the private key to the user. The key pair expires 10 years from creation, and will be unable to authenticate to Google when the key pair is deleted from the service account.

Authorization using Cloud IAM policies

All service accounts have Cloud IAM policies that grant access to the service account. Some permissions allow users to impersonate, or become, the service account based on the users' credentials.

Deploying jobs on Google Cloud

Some Google Cloud services, such as Compute Engine, App Engine, or Cloud Functions, allow you to deploy a job (such as a VM or a Function) that runs as the identity of a service account.

To deploy jobs in this manner, the service account must be granted any necessary permissions for the desired service, and the user account must also be granted the iam.serviceAccounts.actAs permission on the service account. This permission is included in the Service Account User role. It is also necessary that the Google Cloud service maintain Cloud IAM permissions on the service account, but that is typically performed for you automatically.

Examples

Running a VM with a service account

Let's say that you have a long running job that your employees have permissions to start. You don't want that job to be terminated when the employee who last started that job leaves the company.

The way you would solve this problem is by creating a service account to start and stop the job. You can do this using the following steps:

1. Create a service account.

2. Grant the Service Account User (roles/iam.serviceAccountUser) role for the service account to your employees who need permission to start the job. In this scenario, the service account is treated as a resource.

3. Grant the Compute Instance Admin (roles/compute.instanceAdmin.v1) role to the same employees.

4. Now, employees can create Compute Engine instances that run that service account, connect to them, and use the service account to start the job. For example:

   gcloud compute instances create my-instance --scopes=cloud-platform \
   --service-account=[e-mail] \
   --zone=us-central1-a
   

Migrating data to Google Cloud

Let's say that you have some data processing that happens on another cloud provider and you want to transfer the processed data to Google Cloud Platform. You can use a service account from the virtual machines on the external cloud to push the data to Google Cloud Platform. To do this, you must create and download a service account key when you create the service account and then use that key from the external process to call the Cloud Platform APIs.

Keeping track of service accounts

Over time, as you create more and more service accounts, you might lose track of which service account is used for what purpose.

The display name of a service account is a good way to capture additional information about the service account, such as the purpose of the service account or a contact person for the account. For new service accounts, you can populate the display name when creating the service account. For existing service accounts use the serviceAccounts.update() method to modify the display name.

Deleting and recreating service accounts

It is possible to delete a service account and then create a new service account with the same name. If you reuse the name of a deleted service account, it may result in unexpected behavior.

When you delete a service account, its role bindings are not immediately deleted. If you create a new service account with the same name as a recently deleted service account, the old bindings may still exist; however, they will not apply to the new service account even though both accounts have the same email address. This behavior occurs because service accounts are given a unique ID within Cloud IAM at creation. Internally, all role bindings are granted using these IDs, not the service account's email address. Therefore, any role bindings that existed for a deleted service account do not apply to a new service account that uses the same email address.

To prevent this unexpected behavior, consider using a new, unique name for every service account. Also, if you accidentally delete a service account, you can try to undelete the service account instead of creating a new service account.

If you cannot undelete the original service account, and you need to create a new service account with the same name and the same roles, follow these steps:

1. Create the new service account.

2. For each resource that the new service account needs to access, revoke every role that the original service account was granted for that resource.

   Important: You must complete this step before you grant the roles to the new service account. Otherwise, when you try to grant roles to the new service account, the roles will be granted to the original service account instead.

3. After you revoke the roles from the original service account, grant the roles to the new service account.

Permissions for service accounts

This section describes common scenarios for permissions granted to service accounts, or user accounts that have the permissions to impersonate service accounts:

• Granting minimum permissions to service accounts
• Service account permissions for common scenarios

Granting minimum permissions to service accounts

You should only grant the service account the minimum set of permissions required to achieve its goal. Learn about Granting roles to a service account for specific resources.

When granting permissions to users to access a service account, keep in mind that the user can access all the resources for which the service account has permissions. Therefore it's important to configure permissions of your service accounts carefully; that is, be strict about who on your team can act as (or impersonate) a service account.

Users with Cloud IAM roles to update the App Engine and Compute Engine instances (such as App Engine Deployer or Compute Instance Admin) can effectively run code as the service accounts used to run these instances, and indirectly gain access to all the resources for which the service accounts has access. Similarly, SSH access to a Compute Engine instance may also provide the ability to execute code as that instance.

Service account permissions for common scenarios

Service accounts can be used in many different scenarios, and each of them requires certain permissions. This section describes common scenarios and what permissions are required.

Starting long-running jobs

Permissions:

• iam.serviceAccounts.actAs

Roles:

• roles/editor (Editor)
• roles/iam.serviceAccountUser (Service Account User)

A user (or service) can bind a service account to a long-running job service. Some examples include:

• Compute Engine VM
• App Engine App
• Cloud Functions Function
• Dataflow Job

In this scenario, the user must be granted both the permission to deploy the job, which varies per service, and the permission to impersonate the service account, which is granted via iam.serviceAccounts.actAs on the service account. Note that being granted the iam.serviceAccounts.actAs permission by itself does not allow any impersonation of the service account.

After the iam.serviceAccounts.actAs permission has been granted on the service account, they can start a long-running job that runs as the service account. Once the job has been started, that user no longer needs to retain access to the service account. The job remains running even if that user loses access. The job service continues to use its own permissions on the service account to keep the job running with that service account identity.

Note that it is sometimes required to have the iam.serviceAccounts.actAs permission to change a long running job (such as setting the instance metadata on a Compute Engine VM).

For more information about this flow, see Creating and enabling service accounts for instances in the Compute Engine documentation.

Directly impersonating a service account

Permissions:

• iam.serviceAccounts.getAccessToken
• iam.serviceAccounts.signBlob
• iam.serviceAccounts.signJwt
• iam.serviceAccounts.implicitDelegation

Roles:

• roles/iam.serviceAccountTokenCreator (Service Account Token Creator)

Once granted the required permissions, a user (or service) can directly impersonate (or assert) the identity of a service account in a few common scenarios.

First, the user may get short-term credentials for the service account using the iam.serviceAccounts.getAccessToken permission and by calling the generateAccessToken() method. By using short-term credentials, a user can issue commands to Google Cloud and can access all resources to which the service account has access. For example, this flow allows a user to use the gcloud --impersonate-service-account flag to impersonate the service account without requiring the use of a downloaded external service account key.

Second, the user may get artifacts signed by the Google-managed private key of the service account using the iam.serviceAccounts.signBlob permission and by calling either the signBlob() or signJwt() method. The Google-managed private key is always held in escrow and is never directly exposed. signBlob() allows signing of arbitrary payloads (such as Cloud Storage-signed URLs), while signJwt() only allows signing well-formed JWTs.

Finally, the user may impersonate (or assert) the service account without ever retrieving a credential for the service account. This is an advanced use case, and is only supported for programmatic access using the generateAccessToken() method. In scenarios with at least 3 service accounts, namely A, B, and C: service account A can get an access token for service account C if service account A is granted the iam.serviceAccounts.implicitDelegation permission on B, and B is granted the iam.serviceAccounts.getAccessToken permission on C.

Generating OpenID Connect (OIDC) ID tokens

Permissions:

• iam.serviceAccounts.getOpenIdToken

Roles:

• roles/iam.serviceAccountTokenCreator (Service Account Token Creator)

A user (or service) can generate an OpenID Connect (OIDC)-compatible JWT token signed by the Google OIDC Provider (accounts.google.com) that represents the identity of the service account using the iam.serviceAccounts.getOpenIdToken permission.

These tokens are not directly accepted by most Google APIs without your organization deploying additional identity federation to grant access to Google. There are a few exceptions, such as Identity-Aware Proxy which allows OIDC-based access to user-run applications,

Generating external private keys

Permissions:

• iam.serviceAccountKeys.create

Roles:

• roles/editor (Editor)
• roles/iam.serviceAccountAdmin (Service Account Admin)

A user or service can generate external private key material (RSA) that can be used to authenticate directly to Google as the service account. This key material can then be used with Application Default Credentials (ADC) libraries, or with the gcloud auth activate-service-account command. Any person who gains access to the key material will then have full access to all resources to which the service account has access. Such private key material should be treated with the highest concern, and should be considered less secure the longer the material exists. Therefore, rotating private key material is critical to maintaining strong security.

Managing service account keys

There are two types of service account keys:

• GCP-managed keys. These keys are used by Cloud Platform services such as App Engine and Compute Engine. They cannot be downloaded, and are automatically rotated and used for signing for a maximum of two weeks. The rotation process is probabilistic; usage of the new key will gradually ramp up and down over the key's lifetime. We recommend caching the public key set for a service account for at most 24 hours to ensure that you always have access to the current key set.

• User-managed keys. These keys are created, downloadable, and managed by users. They expire 10 years from creation, and cease authenticating successfully when they are deleted from the service account.

For user-managed keys, you need to make sure that you have processes in place to address key management requirements such as:

• Key storage
• Key distribution
• Key revocation
• Key rotation
• Protecting the keys from unauthorized users
• Key recovery

Anyone who has access to a valid private key for a service account will be able to access resources through the service account. Note that the lifecycle of the key's access to the service account (and thus, the data the service account has access to) is independent of the lifecycle of the user who has downloaded the key.

Always discourage developers from checking keys into the source code or leaving them in the Downloads directory of their workstation.

To enhance the security of keys, follow the guidance below:

• Use the IAM service account API to automatically rotate your service account keys. You can rotate a key by creating a new key, switching applications to use the new key and then deleting the old key. Use the serviceAccount.keys.create() and serviceAccount.keys.delete() methods together to automate the rotation. The GCP-managed keys are rotated approximately once a week.

  • Use the serviceAccount.keys.list() method to audit service accounts and keys.

Using service accounts with Compute Engine

Compute Engine instances need to run as service accounts to have access to other Cloud Platform resources. To make sure that your Compute Engine instances are secure, consider the following:

• You can create VMs in the same project with different service accounts. To change the service account of a VM after it's created, use the instances.setServiceAccount method.

• You can grant IAM roles to service accounts to define what they can access. In many cases you won't need to rely on scopes anymore. This gives you the advantage of being able to modify permissions of a VM's service account without recreating the instance.

• Since instances depend on their service accounts to have access to Cloud Platform resources, avoid deleting service accounts when they are still used by running instances. If you delete the service accounts, the instances may start failing their operations.

Best practices

• Restrict who can act as service accounts. Users who are Service Account Users for a service account can indirectly access all the resources the service account has access to. Therefore, be cautious when granting the serviceAccountUser role to a user.

• Grant the service account only the minimum set of permissions required to achieve their goal. Learn about Granting roles to a service account for specific resources.

• Create service accounts for each service with only the permissions required for that service.

• Use the display name of a service account to keep track of the service accounts. When you create a service account, populate its display name with the purpose of the service account.

• Define a naming convention for your service accounts.

• Implement processes to automate the rotation of user-managed service account keys.

• Take advantage of the IAM service account API to implement key rotation.

• Audit service accounts and keys using either the serviceAccount.keys.list() method or the Logs Viewer page in the console.

• Do not delete service accounts that are in use by running instances on App Engine or Compute Engine unless you want those applications to lose access to the service account.