Service Accounts

This page gives a brief overview of Cloud IAM service accounts.

Prerequisites

Cloud IAM service accounts

A service account is a special Google account that can be used by applications to access Google services programmatically. This account belongs to your application or a virtual machine (VM), instead of to an individual end user. Your application uses the service account to call the Google API of a service, so that the users aren't directly involved.

A service account can have zero or more pairs of service account keys, which are used to authenticate to Google. A service account key is a public/private keypair generated by Google. Google retains the public key, while the user is given the private key.

You can create custom service accounts in Google Cloud Platform projects using the Google Cloud Platform Console, the Cloud IAM API, or the gcloud tool.

A service account created using the Cloud IAM API consists of the following:

  • The resource name of the service account in the format projects/[project ID]/serviceAccounts/[service account email].

  • The project ID that owns the service account.

  • The unique ID of the service account.

  • Email address of the service account.

  • A user-specified display name of the service account. Use this field to store additional information about the usage of the service account. When you create a service account, populate the name field with the purpose of the service account or the contact person for that account.

  • etag, which is used for a consistent read-modify-write. A common pattern for updating a resource, such as a service account, is to read its current state, update the data locally, and then send the modified data for writing. This pattern may result in a conflict if two or more independent processes attempt the sequence simultaneously. Cloud IAM solves this problem using an etag property in service accounts. This property is used to verify whether the service account has changed since the last read request. When you make a request to Cloud IAM with an etag value, Cloud IAM compares the etag value in the request with the existing etag value associated with the service account. It writes the service account only if the etag values match.

  • The OAuth2 client id for the service account.

The following snippet shows the structure of the service account:

{
  "name": string,
  "projectId": string,
  "uniqueId": string,
  "email": string,
  "displayName": string,
  "etag": string,
  "oauth2ClientId": string,
}

A service account key created using the Cloud IAM API consists of the following:

  • The resource name of the key in the format projects/[project ID]/serviceAccounts/[service account email]/keys/[key].

  • The type of the private key such as PKCS12 or Google credentials file format. The PKCS12 keys are supported for backwards compatibility.

  • The key data.

  • The time when the key becomes valid and can start being used.

  • The time when the key becomes invalid and can no longer be used.

Service account keys can either be managed by you (user-managed keys) or you can let Cloud Platform manage it for you (GCP-managed keys).

User-managed keys can be created and managed by you using the IAM service account API. You are responsible for keeping the keys safe and rotating them.

GCP-managed keys are used by services such as App Engine and Compute engine. You cannot explicitly create or download a GCP-managed key; Google will manage the keys and will rotate them for you once a day.

The following snippet shows the structure of the service account key:

{
  "name": string,
  "privateKeyType": enum(ServiceAccountPrivateKeyType),
  "privateKeyData": string,
  "validAfterTime": string,
  "validBeforeTime": string,
}

Service accounts represent your service-level security groups. People who have IAM policies to manage/use the service accounts and people who hold private external keys for those service accounts determine the risk/trust of these groups. As such, it is best-practice to use the IAM API to audit the service accounts, the keys, and the policies on those service accounts. If your service accounts do not need external keys, delete them. If users do not need permission to manage or use service accounts, then remove them from the IAM Policy.

Granting IAM roles to service accounts

One of the features of IAM service accounts is that you can treat it as a resource or as an identity.

Service accounts as a resource

By treating a service account as a resource, you can grant permission to a user to access that service account. You can grant an owner, editor, viewer, or a serviceAccountActor role to a user for the service account.

For example, if you want to allow a user to create a VM with the service account or authenticate as a service account, you first need to grant the user the serviceAccountActor role. In this case the service account is the resource and you grant a user permission to use this service account resource.

Service accounts as an identity

You can grant a role to a service account to access a resource. In this case the service account is the identity. Some examples include:

  • The default Compute Engine and App Engine service accounts are granted editor roles on the project when they are created so that the code executing in your App or VM instance have the necessary permissions. In this case the service accounts are identities that are granted the editor role for a resource (project).
  • If you want to allow your automation to access a storage bucket, you grant the service account (that your automation uses) the permissions to read the storage bucket. In this case the service account is the identity that you are granting permissions for another resource (Cloud Storage bucket).

Granting another user the ability to act as a service account

If you want other users to be able to use a service account, you must grant the serviceAccountActor role to the user. Users with the serviceAccountActor role can act as that service account to perform operations such as create and manage Compute Engine instances that use a service account. For information on how to do this see the Compute Engine documentation.

Users who are serviceAccountActors for a service account can access all the resources for which the service account has access. Therefore be cautious when granting the serviceAccountActor role to a user.

Next steps

Read the following guides to understand how to:

Send feedback about...

Cloud Identity and Access Management Documentation