Upload service account keys

This page explains how to upload a public key for a service account. After you upload the public key, you can use the private key from the key pair to authenticate as the service account.

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 account credentials.

Required roles

To get the permissions that you need to upload service account keys, ask your administrator to grant you the Service Account Key Admin (roles/iam.serviceAccountKeyAdmin) IAM role on the project, or the service account whose keys you want to manage. For more information about granting roles, see Manage access.

You might also be able to get the required permissions through custom roles or other predefined roles.

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.

Upload a public key for a service account

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.

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 more information, see Avoid disclosing confidential information in uploaded X.509 certificates.

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.

Console

1. In the Google Cloud console, go to the Service accounts page.

   Go to Service accounts

   The remaining steps will appear automatically in the Google Cloud console.

2. Select a project.
3. On the Service accounts page, 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.

gcloud

Execute the gcloud iam service-accounts keys upload command to upload a public key for signing service account keys.

Replace the following values:

• KEY_FILE: The path to the file containing the key data to upload—for example, ./public_key.pem.
• SA_NAME: The name of the service account to upload a key for.
• PROJECT_ID: Your Google Cloud project ID.

gcloud iam service-accounts keys upload KEY_FILE \
    --iam-account=SA_NAME@PROJECT_ID.iam.gserviceaccount.com

The output contains a unique identifier for the uploaded key:

Name: projects/PROJECT_ID/serviceAccounts/SA_NAME@PROJECT_ID.iam.gserviceaccount.com/keys/c7b74879da78e4cdcbe7e1bf5e129375c0bfa8d0

To determine whether the command was successful, execute the gcloud iam service-accounts keys list command:

gcloud iam service-accounts keys list \
    --iam-account=SA_NAME@PROJECT_ID.iam.gserviceaccount.com

The output will contain the same unique identifier that was returned after the key was created:

KEY_ID	CREATED_AT	EXPIRES_AT	DISABLED
c7b74879da78e4cdcbe7e1bf5e129375c0bfa8d0	2019-06-26T21:01:42Z	9999-12-31T23:59:59Z

REST

The projects.serviceAccounts.keys.upload method uploads the public key from a user-managed key pair, and adds this key to the service account.

Before using any of the request data, make the following replacements:

• PROJECT_ID: Your Google Cloud project ID. Project IDs are alphanumeric strings, like my-project.
• SA_NAME: The name of the service account to associate the key with.
• PUBLIC_KEY_DATA: The public key data for the key pair. Must be an RSA public key that is wrapped in an X.509 v3 certificate. Encode the public key data in base64, including the first line, -----BEGIN CERTIFICATE-----, and the last line, -----END CERTIFICATE-----.

HTTP method and URL:

POST https://iam.googleapis.com/v1/projects/PROJECT_ID/serviceAccounts/SA_NAME@PROJECT_ID.iam.gserviceaccount.com/keys:upload

Request JSON body:

{
  "publicKeyData": "PUBLIC_KEY_DATA"
}

To send your request, expand one of these options:

curl (Linux, macOS, or Cloud Shell)

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login , or by using Cloud Shell, which automatically logs you into the gcloud CLI . You can check the currently active account by running gcloud auth list.

Save the request body in a file named request.json, and execute the following command:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://iam.googleapis.com/v1/projects/PROJECT_ID/serviceAccounts/SA_NAME@PROJECT_ID.iam.gserviceaccount.com/keys:upload"

PowerShell (Windows)

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login . You can check the currently active account by running gcloud auth list.

Save the request body in a file named request.json, and execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://iam.googleapis.com/v1/projects/PROJECT_ID/serviceAccounts/SA_NAME@PROJECT_ID.iam.gserviceaccount.com/keys:upload" | Select-Object -Expand Content

APIs Explorer (browser)

Copy the request body and open the method reference page. The APIs Explorer panel opens on the right side of the page. You can interact with this tool to send requests. Paste the request body in this tool, complete any other required fields, and click Execute.

You should receive a JSON response similar to the following:

{
  "name": "projects/my-project/serviceAccounts/[e-mail]/keys/c7b74879da78e4cdcbe7e1bf5e129375c0bfa8d0",
  "validAfterTime": "2020-05-17T19:31:19Z",
  "validBeforeTime": "2021-05-17T19:31:19Z",
  "keyAlgorithm": "KEY_ALG_RSA_2048",
  "keyOrigin": "USER_PROVIDED",
  "keyType": "USER_MANAGED"
}

Disable public key uploads

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

What's next

• Learn how to create and delete service account keys.
• Learn how to list and get service account keys.
• Learn about alternatives to service account keys for authentication.
• Learn how to use service account keys to authenticate as a service account.
• Understand the best practices for managing service account keys.

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