Background
A service account is a special type of Google account intended to representa non-human user that needs to authenticate and be authorized to accessdata 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 callGoogle APIs.
- Running workloads which are not tied to the lifecycle of a human user.
Your applicationassumes the identity of the service account to call Google APIs,so that the users aren't directly involved.
Managing service accounts
Service accounts can be thought of as both aresource and as anidentity.
When thinking of the service account as an identity, you can grant a role to aservice 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 otherusers 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 grantingaccess to any other identity. For example, if you have an application running onCompute Engine and you want the application to only have access tocreate objects in Cloud Storage. You can create a service account for theapplication and grant it the Storage Object Creator role.
Learn aboutGranting roles to all types of principals,including service accounts.
Keeping track of service accounts
Over time, as you create more and more service accounts, you might lose track ofwhich service account is used for what purpose.
The display name of a service account is a good way to capture additionalinformation about the service account, such as the purpose of the serviceaccount or a contact person for the account. For new service accounts, you canpopulate the display name when creating the service account. For existingservice accounts use the serviceAccounts.update() method tomodify the display name.
Identifying unused service accounts
Unused service accounts create an unnecessary security risk, so we recommenddisabling unused service accounts, thendeleting the service accounts when you are sure that you no longerneed them. You can use the following methods to identify unused serviceaccounts:
- Service account insights tell you which service accounts inyour project have not authenticated in the past 90 days.
- Activity analyzer lets you check when a serviceaccount or key was last used.
You can also use service account usage metrics to track serviceaccount and key usage generally.
Deleting and recreating service accounts
It is possible to delete a service account and then create a new serviceaccount with the same name.
When you delete a service account, its role bindings are not immediatelydeleted. Instead, the role bindings list the service account with the prefixdeleted:
. For an example, seePolicies with deleted principals.
If you create a new service account with the same name as a recently deletedservice account, the old bindings may still exist; however, they will notapply to the new service account even though both accounts have the same emailaddress. This behavior occurs because service accounts are given a unique IDwithin Identity and Access Management (IAM) at creation. Internally, all role bindings aregranted using these IDs, not the service account's email address. Therefore, anyrole bindings that existed for a deleted service account do not apply to a newservice account that uses the same email address.
Similarly, if youattach a service account to a resource, thendelete the service account and create a new service account with the same name,the new service account will not be attached to the resource.
To prevent this unexpected behavior, consider using a new, unique name for everyservice account. Also, if you accidentally delete a service account, you can tryto undelete the service account instead of creating a new serviceaccount.
If you cannot undelete the original service account, and you need to create anew service account with the same name and the same roles, you must grant theroles to the new service account. For details, seePolicies with deleted principals.
If you also need the new service account to be attached to the same resourcesas the original service account, do one of the following:
- For Compute Engine instances, you canchange the service account that is attached to the instanceto replace the original service account with the new service account.
- For all other resources, you must delete the existing resource, then create anew resource of the same type andattach the new service account.
Permissions for service accounts
This section describes common scenarios for permissions granted to serviceaccounts, or user accounts that have the permissions to impersonate serviceaccounts:
- Granting minimum permissions to service accounts
- Service account permissions for common scenarios
Granting minimum permissions to service accounts
As with all types of principals, you should only grant the service account theminimum set of permissions required to achieve its goal. Learn aboutgranting roles to all types of principals,including service accounts.
When granting permissions to users to access a service account, keep in mindthat the user can access all the resources for which the service account haspermissions. Therefore it's important to configure permissions of your serviceaccounts carefully; that is, be strict about who on your team can act as(or impersonate) a service account. Use particular caution when allowing usersto impersonate highly privileged service accounts, such as theCompute Engine and App Enginedefault service accounts.
Users with IAM roles to updatethe App Engine and Compute Engine instances (such asApp Engine Deployeror Compute Instance Admin) can effectively run codeas the service accounts used to run these instances, and indirectly gain accessto all the resources for which the service accounts has access. Similarly,SSH access to a Compute Engine instance mayalso 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 themrequires certain permissions. This section describes common scenarios and whatpermissions are required.
Attaching service accounts to resources
If you want to start a long-running job that authenticates as a service account,you need to attach a service account to the resource that will run the job.
Permissions:
- Permissions to create the resource
iam.serviceAccounts.actAs
To find roles that include these permissions, search theroles list for the permissions.
There are several different Google Cloud resources that can runlong-running jobs as service accounts. Some examples of these resources include:
- Compute Engine VMs
- App Engine apps
- Cloud Functions
When you create these resources, you have the option to attach a serviceaccount. This service account acts as the resource's identity.
To create a resource and attach a service account, you need permissions tocreate that resource and permission to impersonate the service account that youwill attach to the resource. Permission to impersonate the service account isprovided by any role that includes the iam.serviceAccounts.actAs
permission.
After you create the resource and attach a service account to it, you can starta long-running job on the resource. The job runs as the service account that isattached to the resource, and uses that service account to authorize requests toGoogle Cloud APIs.
To learn more about attaching service accounts to resources, seeAttaching a service account to a resource.
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 directlyimpersonate (or assert) the identity of a service account in a few commonscenarios.
First, the user may get short-term credentials for the service account using theiam.serviceAccounts.getAccessToken
permission and by calling thegenerateAccessToken()method. By using short-term credentials, a user can issue commands toGoogle Cloud and can access all resources to which the service account hasaccess. For example, this flow allows a user to use thegcloud --impersonate-service-accountflag to impersonate the service account without requiring the use of adownloaded external service account key.
Second, the user may get artifacts signed by the Google-managed private key ofthe service account using the iam.serviceAccounts.signBlob
permission and bycalling either thesignBlob()orsignJwt()method. The Google-managed private key is always held in escrow and is neverdirectly exposed. signBlob()
allows signing of arbitrary payloads (such asCloud Storage-signed URLs), while signJwt()
only allows signingwell-formed JWTs.
Finally, the user may impersonate (or assert) the service account without everretrieving a credential for the service account. This is an advanced use case,and is only supported for programmatic access using thegenerateAccessToken()method. In scenarios with at least 3 serviceaccounts, namely A, B, and C: service account A can get an access tokenfor service account C if service account A is granted theiam.serviceAccounts.implicitDelegation
permission on B, and B is grantedthe 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 tokensigned by the Google OIDC Provider (accounts.google.com) that represents theidentity of the service account using the iam.serviceAccounts.getOpenIdToken
permission.
These tokens are not directly accepted by most Google APIs without yourorganization deploying additional identity federation to grant access toGoogle. There are a few exceptions—for example, Identity-Aware Proxy, which allowsOIDC-based access to user-run applications.
Generating external private keys
Permissions:
iam.serviceAccountKeys.create
Roles:
roles/editor
(Editor)roles/iam.serviceAccountKeyAdmin
(Service Account Key Admin)
A user or service can generate external private key material (RSA) that can beused to authenticate directly to Google as the service account. This keymaterial can then be used with Application Default Credentials (ADC) libraries,or with thegcloud auth activate-service-accountcommand. Any person who gains access to the key material will then have fullaccess to all resources to which the service account has access. Such privatekey material should be treated with the highest concern, and should beconsidered less secure the longer the material exists. Therefore, rotatingprivate key material is critical to maintaining strong security.
Using service accounts with Compute Engine
Compute Engine instances need to run as service accounts to have accessto other Google Cloud resources. To make sure that yourCompute Engine instances are more secure, consider the following:
You can create VMs in the same project with different service accounts. Tochange the service account of a VM after it's created, use theinstances.setServiceAccountmethod.
You cangrant IAM roles to service accountsto define what they can access. In many cases you won't need to rely on scopesanymore. This gives you the advantage of being able to modify permissions of aVM's service account without recreating the instance.
Since instances depend on their service accounts to have access toGoogle Cloud resources, avoid deleting service accounts when they arestill used by running instances. If you delete the service accounts, theinstances may start failing their operations.
What's next
- Read our best practices for working with service accounts.
Try it for yourself
If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.
Get started for free