Best practices for managing service account keys  |  IAM Documentation  |  Google Cloud (2024)

Unlike normal users, service accounts don't have passwords. Instead, serviceaccounts use RSA key pairs for authentication: If you know the private key ofa service account's key pair, you can use the private key tocreate a JWT bearer tokenand use the bearer token to request an access token. The resulting access tokenreflects the service account's identity and you can use it to interact withGoogle Cloud APIs on the service account's behalf.

Because the private key lets you authenticate as the service account, havingaccess to the private key is similar to knowing a user's password. The privatekey is known as a service account key. The key pairs used by service accountsfall into two categories,Google-managed and user-managed.

Service account keys can become a security risk if not managed carefully.You should choose a more secure alternative for authenticationwhenever possible. The main threats are related to service account keys are:

• Credential leakage: Service account keys might inadvertently end up inplaces where they are not supposed to be stored. A bad actor can use a leakedservice account key to authenticate and gain a foothold in your environment.
• Privilege escalation: If a bad actor gets access to a poorly securedservice account key, they might be able to use the key to escalate their privileges.
• Information disclosure: Service account keys might inadvertently disclose confidential metadata.
• Non-repudiation: By authenticating using a service account key and lettingthe service account carry out operations on their behalf, a bad actor mightconceal their identity and actions.

The best way to mitigate these threats is toavoid user-managed service account keysand to use other methods to authenticate service accountswhenever possible. You can also use IAM conditionsand VPC Service Controls to restrictwhat resources can potentially be accessed by a compromised service account.

For situations where you can't use more secure alternatives to service account keys,this guide presents best practices for managing, using, and securing service account keys.

Protecting against credential leakage

Like a username and password, service account keys are a form of credential. Ifa user can access a valid service account key, they can use it to authenticateand access the resources the respective service account has been granted access to.

To bad actors, service account keys can be even more valuable than a leaked password:Attempting to sign in by using a leaked password is unlikely to succeed if theuser account has been configured to use 2-step verificationand login challenges. In contrast,authenticating by using a leaked service account key is likely to succeed asservice accounts are not subject to any additional sign-in verifications.

Bad actors might look for service account keys in a variety of places, including:

• Source code repositories of open source projects
• Public Cloud Storage buckets
• Public data dumps of breached services

In addition to public locations, bad actors might look for service account keysin private locations they've compromised. Examples include:

• Email inboxes
• File shares
• Backup storage
• Temporary file system directories

An effective way to lower the risk of leaking service account keys is to reducethe number of keys in circulation and to disincentivize the creation of new keys.The following sections describe how you can limit the number of service accountkeys in circulation, and what other measures can help you limit the risk of leaking service accounts.

Provide alternatives to creating service account keys

Make sure that users in your organization are aware of alternatives and canjustify the additional risk and management overhead of using a service accountkey:

• Educate your developers on more secure alternatives to service account keys
• Establish a process to help developers decide on the appropriateauthentication method for their use case before creating a new serviceaccount key.
• Use organization policy constraintsto prevent creating new service account keys, and allow exceptions only forprojects that have demonstrated that they cannot use a more securealternative.

Use organization policy constraints to limit which projects can create service account keys

Given the more secure alternatives to service account keys,it's best to consider the use of service account keys as an exception ratherthan the norm.

To prevent unnecessary usage of service account keys, useorganization policy constraints:

• At the root of your organization's resource hierarchy,apply the Disable service account key creationand Disable service account key uploadconstraints to establish a default where service account keys are disallowed.

• When needed, overrideone of the constraints for selected projects to re-enable service accountkey creation or upload.

Modifying organization policy constraints requires the orgpolicy.policy.setpermission. Because neither the Owner (roles/owner) nor the Editor (roles/editor)role includes this permission, constraints can also be effective in non-productionenvironments where some principals might have Owner or Editor access to projects.

Don't leave service account keys in temporary locations

When you create a service account key by using the Google Cloud console, most browsersimmediately download the new key and save it in a download folder on your computer.You should immediately move the key to the location where you want to store it.Make sure you're not accidentally leaving a copy in the download folder or therecycle bin of your computer.

You can reduce the risk of accidentally leaving copies of service account keysin temporary locations by using the Google Cloud CLI:The gcloud iam service-accounts keys create command lets you write the serviceaccount key file straight to the location where you need it. Also, on most operatingsystems, the gcloud CLI automatically adjusts file permissions so that the fileis only accessible by you.

Don't pass service account keys between users

When you deploy an application that requires a service account key, you mightnot have the permission to create a service account key yourself. Instead, youmight have to request a different person to create a service account key for you.

In scenarios where multiple users are involved in the creation and deployment ofa service account key, there is an increased risk that copies of the key remainin mailboxes, chat histories, or other locations. Whenever a handover betweenusers is necessary, it can be more secure to upload a service account key:

1. As the user deploying the application, create a self-signed certificate thatuses an RSA 2048-bit key pair on the target machine. To create the certificate,you can use openssl, certutil, New-SelfSignedCertificate, or other operating system tools.
2. Pass the certificate file to the user who has the permission to upload thecertificate while keeping the private key on the target machine. When passingthe certificate, make sure that it can't be replaced or tampered with, butyou don't need to keep it confidential.
3. As the user who has the necessary permissions to manage service account keys,upload the certificateto associate it with a service account.

By following this process, you avoid passing the private key and instead onlyexchange public information between users.

Don't submit service account keys to source code repositories

Service account keys are credentials, and must be protected from unauthorizedaccess. If you submit a service account key to a source code repository, thereis an increased risk that the key becomes accessible to unauthorized users andbad actors:

• Bad actors might scan the source code of public source repositories for leaked keys.
• In the future, you might decide to turn a private source repository into apublic repository, without checking it for keys first.
• Other team members might store copies of the source code on their workstation.

When you work on code that uses a service account key, always store the serviceaccount key separate from the source code to reduce the risk of accidentallysubmitting the key to the source repository. In many cases, you can further reducethis risk by not using service account keys at all during development andusing your personal credentials instead of service account keys instead.

Additionally, set up your source control system so that it detects accidentalsubmissions of service account keys:

• If you use Cloud Source Repositories,enable key detectionto block git push operations that contain private keys and to notify users.
• If you use GitHub, enable secret scanning for your repositories.
• Use Security Command Center anomaly detectionto surface information about leaked credentials.
• If your source control management system doesn't support automatic scanning,use an open-source tool like truffleHogto scan your source code for secrets by using apre-commit hook,by adding a step to continuous integration pipeline, or both.

Don't embed service account keys in program binaries

Service account keys are strings that match a certain pattern, and they can beidentified even if embedded in other files or binaries. If a bad actor has accessto the binary, they can extract any service account keys that are embedded in the binary.

Program binaries for server-side applications might be hosted in artifactrepositories or they might be copied to developer workstations for debuggingpurposes. Keeping service account keys separate from the program binaries helpsensure that a user who can access the binary does not implicitly get access toservice account credentials.

• For client-side applications such as tools, desktop programs, or mobile apps,don't use service accounts. Instead, let users authenticate with their owncredentials by using the OAuth-consent flow.
• For server-side applications, don't embed service account keys into the binary.Instead, keep the keys separate from the application binary.

Use insights and metrics to identify unused service account keys

To minimize the number of valid service account keys in circulation, it's best todisable keys as soon as they aren't needed anymore, then delete the keys whenyou're certain that they are no longer needed. If you're unsure whether a key isstill in use or not, you can use service account insights and authentication metrics:

• Service account insights let you identify serviceaccounts that have not been used in the past 90 days.
• By monitoring the Key Authentication Events metric, you canfind out when a service account key was last usedand how often it was used to authenticate a service account.

Because service accounts belong to a Google Cloud project, insights and metrics must betracked individually for each project.

Rotate service account keys to reduce security risk caused by leaked keys

Although you can reduce the probability of accidentally leaking a serviceaccount key, it can be difficult to eliminate the risk completely.

Key rotation is the process of replacing your existing keys with new keys andthen invalidating the replaced keys. We recommend that you routinelyrotate all keys that you manage, including your service account keys.

Rotating service account keys can help reduce the risk posed by leaked or stolenkeys. If a key is leaked, it might take bad actors days or weeks to discover thekey. If you regularly rotate your service account keys, there's a higher chancethat the leaked keys will be invalid by the time a bad actor gets them.

Having an established process for rotating service account keys also helps youact quickly if you suspect that a service account key has been compromised.

If you generated the public/private key pair yourself, stored the private key ina hardware security module (HSM), anduploaded the public key to Google,then you might not need to rotate the key on a regular schedule. Instead, youcan rotate the key if you believe that it might have been compromised.

Use expiry times to let keys expire automatically

By default, service account keys that you create and download fromIAM don't have an expiry time and stay valid until you deletethem. Setting an expiry time for service account keys can limit your securityrisk by reducing the lifetime of the persistent credential. However, there areother risks associated with setting expiry times; for example, setting an expirytime can cause workloads to fail when their keys expire.

Use expiry times when you need temporaryaccess to a system that requires a service account key. For example, use expirytimes when you're doing the following:

• Developing code in a non-production environment for an application that canonly authenticate with service account keys
• Using a third-party tool that can only authenticate with service account keys

Avoid using expiry times for these scenarios:

• Production workloads. In production, an expired service account key couldcause an accidental outage. Instead, use keys that do not expire, and managetheir lifecycle with key rotation.
• Non-production workloads that need permanent access, such as a continuousintegration (CI) pipeline.
• Key-rotation systems that prevent a key from being used after a specifiedamount of time. To learn about recommended key rotation strategies, seeService account key rotation.

To limit the validity of service account keys, you canconfigure an expiry time for newlycreated keys in your project, folder, or organization. The expiry time does notapply to existing keys.

Alternatively, you canupload a service account keyand specify a Valid To date in the X.509 certificate file. After theexpiry date passes, the key can't be used for authentication. However, it staysassociated with the service account until you delete it.

Use organization policy constraints to automatically disable leaked keys

Even if you follow all of the best practices for service account keys, it'spossible for your service account keys to be leaked.

To help manage leaked credentials, ensure that the Service Account Key ExposureResponseconstraintis set to DISABLE_KEY. If you set the constraint to this value, Google Cloudwill automatically disable any leaked keys that it detects.

If a key is disabled because it was leaked, the following fields areadded to the key's metadata:

• "disable_reason": "SERVICE_ACCOUNT_KEY_DISABLE_REASON_EXPOSED":indicates that the key was disabled because it was exposed.
• "extended_status": "SERVICE_ACCOUNT_KEY_EXTENDED_STATUS_KEY_EXPOSED"":indicates that the key was once publicly exposed. This value persists evenif you re-enable the key.
• "extended_status_message": "LINK_TO_EXPOSURE": ifavailable, the metadata contains a link to the place where the key wasdetected, which you can use for remediation.

These keys can be re-enabled ifrequired to mitigate an outage. However, we recommend disabling them again assoon as possible, because publicly exposed keys present a security risk, even if theinitial exposure is removed.

To learn about other best practices for managing compromised credentials, seeHandling compromised Google Cloudcredentials.

Protecting against privilege escalation

Using service account keys can expose you to privilege escalation attacks if thekeys are less well secured than the resources they grant access to.

As an example, suppose a bad actor has already gained a foothold in your environmentand now tries to access certain Google Cloud resources. They might still lack thepermissions to access these resources, but their privileges might suffice to accessa service account key that is stored on a VM, file share, or another less-wellsecured location. By authenticating using the service account key, the bad actorcan assume the identity of the service account. The service account might let thebad actor access resources they previously did not have access to, therebyescalating the bad actor's privileges.

Because a service account key indirectly grants access to resources on Google Cloud,you must consider the key itself to be as valuable, and as much worth protecting,as the resources themselves.

The following sections describe best practices for protecting service account keysand reducing the risk of unauthorized access and resulting privilege escalation.

Avoid storing keys on a file system

Service account keys created by using the Google Cloud console or the gcloud CLI areJSON files, and you can copy these files to the file system of the machine wherethey are needed. But storing service account keys as files on a file system canexpose you to several risks, including:

• Some file systems such as NTFS use inherited permissions by default. Unlessdisabled, a permission added to a parent folder might inadvertently cause akey file to become more widely accessible and visible to unauthorized users.
• In a virtualized environment, bad actors might be able to undermine file systemsecurity by accessing the underlying virtual disk.
• File system access and permission changes are often not audit-logged. Iffile permissions are inadvertently changed and the key becomes visible tounauthorized users, it might be difficult to analyze when and by whom thesechanges were made.
• Files can be easily copied and thus exfiltrated if a bad actor gains access.

Whenever possible, avoid storing service account keys on a file system. If youcan't avoid storing keys on disk, make sure to restrict access to the key file,configure file access auditing, and encrypt the underlying disk.

Use an HSM or TPM to store keys

When you create a service account key by using the Google Cloud console or thegcloud CLI, the private key is generated by Google Cloud and then revealedto you. Many security risks associated with service account keys stem from thefact that the private key is, temporarily or permanently, available in cleartext and can therefore be difficult to protect.

Instead of letting Google Cloud generate a key pair, you can use a hardwaresecurity module (HSM) or Trusted Platform Module (TPM) to create and manage keys:

1. Use a HSM or TPM to generate a RSA key pair.
2. Use the key pair to create a self-signed certificate.
3. Upload the certificateas a service account key.
4. Let the application use the HSM or TPM's signing API to sign the JWT forauthenticating the service account.

An HSM or TPM lets you use a private key without ever revealing the key in cleartext. Using an HSM or TPM to manage service account keys therefore helps youenforce access control while also mitigating the risk of keys being copied toother systems.

Some platforms provide abstractions that let you take advantage of a TPM withouthaving to directly interact with it. For example, Windows lets you manageTPM-protected keys by using the CryptoNG API in combination withthe Microsoft Platform Crypto Provider.

Service account keys managed by a TPM are unique to a physical or virtual machine.You can still let multiple machines share a service account by associating eachmachine's key with a common service account.

Use a software-based key store

In situations where using a hardware-based key store isn't viable, use asoftware-based key store to manage service account keys. Similar to hardware-basedoptions, a software-based key store lets users or applications use service accountkeys without revealing the private key. Software-based key store solutions can helpyou control key access in a fine-grained manner and can also ensure that each keyaccess is logged.

The security of a software-based key store typically depends on how its masterkey is protected. Before you use a software-based key store, make sure to review:

• how the master key is secured at rest,
• how the unsealing process works, and who is able to initiate it,
• how keys are protected from being extracted from memory,
• how the key store is protected from being undermined if a bad actor gainsshell access or hypervisor access to the underlying system.

Don't store keys in Secret Manager or other cloud-based secret stores

We don't recommend using Google Cloud's Secret Manager to storeand rotate service account keys. This is because, to accessSecret Manager secrets, your application needs an identity thatGoogle Cloud can recognize. If your application already has an identitythat Google Cloud can recognize, then your application can use thatidentity to authenticate to Google Cloud instead of using a serviceaccount key.

The same concept applies for other cloud-based secret management services, likeAzure KeyVault and AWS Secret Manager. If an application already has an identitythat these cloud providers can recognize, your application would be able to usethat identity to authenticate to Google Cloud instead of using a serviceaccount key.

Don't use the Editor role in projects that allow service account key creation or upload

A key difference between the Editor (roles/editor) and Owner (roles/owner)basic roles is that the Editor role doesn't let you change IAM policies or roles.With the Editor role, you therefore can't easily extend your own access or grantother users access to project resources.

The limitations of the Editor role can be undermined if a project contains serviceaccounts. Because the Editor roles grant permission to create or upload serviceaccount keys, a bad actor can create new keys for existing service accounts anduse these keys to either escalate their own access, or to hand the keys to otherusers to obtain access to project resources.

Instead of using the Editor role, or any other basic role, it's best to use themore narrowly defined predefined roles, or to create custom roles that only grantnecessary permissions.

If you need to use the Editor role,disable service account key uploadand key creationby using organization policy constraints to help ensure that the Editor rolecan't be abused for privilege escalation.

Avoid using service account keys for domain-wide delegation

Domain-wide delegation lets you impersonate a user so that you can access a user's data without any manual authorization on their part. Although examples illustrating the use of domain-wide delegation commonly suggest the use of service account keys, using service account keys is not necessary to perform domain-wide delegation.

When using domain-wide delegation, avoid service account keys and use thesignJwt APIinstead:

1. Authenticate a service account by using anattached service account,Workload Identity Federation for GKE,or Workload Identity Federationfirst.
2. Construct a JWTand use the sub claim to specify the email address of the user for whichyou're requesting delegated access.
3. Use the signJwt APIto sign the JWT.
4. Pass the signed JWTto the OAuth2 Token resource to obtain an access token.

By following this approach, you avoid having to manage a service account key,resulting in a setup that can be secured more easily.

Protecting against information disclosure threats

Avoid disclosing confidential information in uploaded X.509 certificates

For each service account key, IAM lets you download a X.509certificate from the endpoint https://www.googleapis.com/service_accounts/v1/metadata/x509/ACCOUNT_EMAIL.This endpoint is public and doesn't require authentication.

For Google-managed keys and user-managed keys that you created by using theGoogle Cloud console or the gcloud CLI, the X.509 certificates arecreated automatically and only contain basic metadata such as the email addressand expiry date.

For uploaded service account keys, the X.509 certificate provided by the publicendpoint is the same certificate as the one you uploaded. If the certificate youuploaded contained any optional attributes (such as address or locationinformation embedded in the common name), then this information also becomespublicly accessible. A bad actor might use this information to learn more aboutyour environment.

To avoid disclosing confidential information, don't add any optional attributesto uploaded X.509 certificates and use a generic Subject.

Protecting against non-repudiation threats

When you notice suspicious activity affecting your Google Cloudresources and want to analyze its origins, you need data that lets youreconstruct the chain of events that led to the suspicious activity. The primarysource of data to perform such analysis are typically audit logs.

Analyzing audit logs can become more difficult when service accounts areinvolved: if an activity was initiated by a service account, the log entrycontains the service account's email address, but you also need to find outwhich user or application was using the service account at the time.

The following sections contain best practices for using service account keys ina way that helps you track their usage.

Use a dedicated service account for each application

All audit log records contain a principalEmail field that identifies the principalthat initiated the activity. If you share a service account key across multipleapplications, then it can be difficult to identify which application performedan activity because audit log records contain the same principalEmail value.

Instead of sharing a key among multiple applications, create a dedicated serviceaccount for each application. That way, the principalEmail field lets youidentify the application associated with a service account which can help youreconstruct the chain of events that led to a suspicious activity.

Use a dedicated key for each machine that runs an application

If you run multiple copies of the same application across multiple machines, thenthe principalEmail field might let you identify the application, but not themachine where a particular activity originated from.

To help you narrow down the potential sources of suspicious activity, createindividual keys for each copy of the application. That way, you can use theserviceAccountKeyName field that many services add to audit log records todistinguish which machine an activity originated from.

What's next

• Read more about best practices for working with service accounts.
• Review our best practices for using service accounts in deployment pipelines.