Creating and managing service account keys

This page explains how to create and manage service account keys using the Google Cloud Console, the gcloud command-line tool, the Identity and Access Management API, or one of the Google Cloud Client Libraries.

Note: If you need to access resources from a workload that runs outside of Google Cloud, such as on Amazon Web Services (AWS) or Microsoft Azure, consider using workload identity federation instead of service account keys. Federation lets your workloads access resources directly, using a short-lived access token, and eliminates the maintenance and security burden associated with service account keys.

Before you begin

• Enable the IAM API.

  Enable the API

• Understand service accounts.

• Install the gcloud tool.

Required permissions

To allow a user to manage service account keys, grant the Service Account Key Admin role (roles/iam.serviceAccountKeyAdmin). For more information, see Service Accounts roles.

IAM basic roles also contain permissions to manage service account keys. You should not grant basic roles in a production environment, but you can grant them in a development or test environment.

Creating service account keys

To use a service account from outside of Google Cloud, such as on other platforms or on-premises, you must first establish the identity of the service account. Public/private key pairs provide a secure way of accomplishing this goal. When you create a service account key, the public portion is stored on Google Cloud, while the private portion is available only to you. For more information about public/private key pairs, see Service account keys.

Note: You can create service account keys in JSON or PKCS#12 (P12) format. P12 service account keys are not recommended unless they are necessary for backwards compatibility. The following examples use JSON format.

You can create a service account key using the Cloud Console, the gcloud tool, the serviceAccounts.keys.create() method, or one of the client libraries. A service account can have up to 10 keys.

In the examples below, sa-name is the name of your service account, and project-id is the ID of your Google Cloud project. You can retrieve the [email protected] string from the Service Accounts page in the Cloud Console.

Note: After you create a key, you might need to wait for 60 seconds or more before you perform another operation with the key. If you try to perform an operation with the key immediately after you create the key, and you receive an error, you can retry the request with exponential backoff.

1. In the Cloud Console, go to the Service accounts page.

   Go to Service accounts

2. Select a project.

3. Click the email address of the service account that you want to create a key for.

4. Click the Keys tab.

5. Click the Add key drop-down menu, then select Create new key.

6. Select JSON as the Key type and click Create.

Clicking Create downloads a service account key file. After you download the key file, you cannot download it again.

The downloaded key has the following format, where private-key is the private portion of the public/private key pair:

{
  "type": "service_account",
  "project_id": "project-id",
  "private_key_id": "key-id",
  "private_key": "-----BEGIN PRIVATE KEY-----\nprivate-key\n-----END PRIVATE KEY-----\n",
  "client_email": "service-account-email",
  "client_id": "client-id",
  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
  "token_uri": "https://accounts.google.com/o/oauth2/token",
  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
  "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/service-account-email"
}

Make sure to store the key file securely, because it can be used to authenticate as your service account. You can move and rename this file however you would like.

You can use service account key files to authenticate an application as a service account.

Listing service account keys

You can list the service account keys for a service account using the Cloud Console, the gcloud tool, the serviceAccount.keys.list() method, or one of the client libraries.

The serviceAccount.keys.list() method is commonly used to audit service accounts and keys, or to build custom tooling for managing service accounts.

To find out which project your key belongs to, you can download the key as a JSON file and look at that file.

You might see keys listed that you did not create. These are keys created by Google and used by the Service Account Credentials API. To learn more, see Google-managed key pairs.

1. In the Cloud Console, go to the Service accounts page.

   Go to Service accounts

2. Select a project.

3. Click the email address of the service account whose keys you want to list.

4. Click Keys. The Cloud Console displays a list of keys for the service account.

Getting a service account key

You can use the gcloud tool or the REST API to get the public key data for a service account key. In addition, you can use the Cloud Console, the gcloud tool, or the REST API to get metadata for the key, such as the algorithm that the key uses and whether the key is managed by you or by Google.

Note: You cannot get the private key data for a service account key. This data is available only when the key is created.

To get the public key data for a service account key:

Use the gcloud tool or the REST API. This data is not available in the Cloud Console.

To get metadata for a service account key:

1. In the Cloud Console, go to the Service accounts page.

   Go to Service accounts

2. Select a project.

3. Click the email address of the service account whose keys you want to list.

4. Click Keys. The Cloud Console displays a list of keys for the service account, including metadata for each key.

Uploading public keys for service accounts

You can upload the public key portion of a user-managed key pair to associate it with a service account. After you upload the public key, you can use the private key from the key pair as a service account key.

The key you upload must be an RSA public key that is wrapped in an X.509 v3 certificate and encoded in base64. You can use tools such as OpenSSL to generate a key and certificate in this format.

Important: Do not include any private information in the X.509 certificate. Specifically, use a generic subject, and do not add any optional attributes. Certificates are publicly visible; any private information in the certificate is visible to anyone who retrieves the certificate.

For example, the following command generates a 2048-bit RSA key pair and wraps the public key in a self-signed certificate that is valid for 365 days:

openssl req -x509 -nodes -newkey rsa:2048 -days 365 \
    -keyout /path/to/private_key.pem \
    -out /path/to/public_key.pem \
    -subj "/CN=unused"

You can then upload the public_key.pem file as the public key for a service account.

To disable the ability to upload keys for your project, see Restricting service account key upload.

1. In the Cloud Console, go to the Service accounts page.

   Go to Service accounts

2. Select a project.

3. Click the email address of the service account that you want to upload a key for.

4. Click the Keys tab.

5. Click the Add key drop-down menu, then select Upload existing key.

6. Click Browse, then find and select your public key file. Alternatively, you can copy and paste the contents of your public key file into the Paste existing key box.

7. Click Upload.

Disabling service account keys

Disabling a service account key prevents you from using the key to authenticate with Google APIs. You can enable a disabled key at any time.

Important: Disabling a service account key does not revoke short-lived credentials that were issued based on the key. To revoke a compromised short-lived credential, you must disable or delete the service account that the credential represents. If you do so, any workload that uses the service account will immediately lose access to your resources.

Before you delete a service account key, we recommend that you disable the key, then wait until you are sure that the key is no longer needed. You can then delete the key.

You can view disabled keys in the Cloud Console, but you cannot use the Cloud Console to disable a key. Use the gcloud tool or the REST API instead.

Execute the gcloud iam service-accounts keys disable command to disable a service account key.

Replace the following values:

• key-id: The ID of the key to disable.
• sa-name: The name of the service account that the key belongs to.
• project-id: Your Google Cloud project ID.

gcloud iam service-accounts keys disable key-id \
    [email protected]

Output:

Disabled key [key-id] for service account
[[email protected]]

Enabling service account keys

After you disable a service account key, you can enable the key at any time, then use the key to authenticate with Google APIs.

You cannot use the Cloud Console to enable service account keys. Use the gcloud tool or the REST API instead.

Execute the gcloud iam service-accounts keys enable command to enable a service account key.

Replace the following values:

• key-id: The ID of the key to enable.
• sa-name: The name of the service account that the key belongs to.
• project-id: Your Google Cloud project ID.

gcloud iam service-accounts keys enable key-id \
    [email protected]

Output:

Enabled key [key-id] for service account
[[email protected]]

Deleting service account keys

Deleting a service account key permanently prevents you from using the key to authenticate with Google APIs.

You cannot undelete a deleted key. Before you delete a key, we recommend that you disable the key, then wait until you are sure that the key is no longer needed. You can then delete the key.

As a best practice, rotate your service account keys regularly. You can rotate a key by doing the following:

1. Create a new key.
2. Update your applications to use the new key.
3. Disable the old key.
4. Wait long enough to confirm that the old key is no longer in use.
5. Delete the old key.

Important: Deleting a service account key does not revoke short-lived credentials that were issued based on the key. To revoke a compromised short-lived credential, you must disable or delete the service account that the credential represents. If you do so, any workload that uses the service account will immediately lose access to your resources.

1. In the Cloud Console, go to the Service accounts page.

   Go to Service accounts

2. Select a project.

3. Click the email address of the service account whose key you want to delete.

4. Click the Keys tab.

5. From the list of keys, click Delete delete for each key you'd like to delete.

What's next