This page explains how to upload a public key for a service account. After youupload the public key, you can use the private key from the key pair toauthenticate 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 usingWorkload 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.

  Roles required to enable APIs

  To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains theserviceusage.services.enable permission.Learn how to grant roles.

  Enable the API

• Understandservice account credentials.

Required roles

To get the permissions that you need to upload service account keys, ask your administrator to grant you theService Account Key Admin (roles/iam.serviceAccountKeyAdmin) IAM role on the project, or the service account whose keys you wantto manage. For more information about granting roles, seeManage access to projects, folders, and organizations.

You might also be able to get the required permissions throughcustom roles or otherpredefined roles.

For more information, seeService Accounts roles.

Depending on your organization policy configuration, you might also need toallow service account keys to be uploaded in your projectbefore uploading a key.

To get the permissions that you need to allow service account keys to be uploaded in a project, ask your administrator to grant you the following IAM roles on your organization:

• Organization Policy Administrator (roles/orgpolicy.policyAdmin)
• Organization Viewer (roles/resourcemanager.organizationViewer)
• Tag Administrator (roles/resourcemanager.tagAdmin)

For more information about granting roles, seeManage access to projects, folders, and organizations.

These predefined roles contain the permissions required to allow service account keys to be uploaded in a project. To see the exact permissions that are required, expand theRequired permissions section:

You might also be able to get these permissions withcustom roles or otherpredefined roles.

Allow service account key upload

Before you create a service account key, make sure that theiam.disableServiceAccountKeyUpload organization policy constraint isn'tenforced for your project. If this constraint is enforced for your project,you can't upload service account keys in that project.

Note: If your organization was created on or after May 3, 2024, this constraint is enforced by default.

We recommend enforcing this constraint for most projects and only exemptingprojects that truly require service account keys. For more information aboutalternative authentication methods, seeChoose the right authentication methodfor your use case.

To exempt a project from theiam.disableServiceAccountKeyUpload organizationpolicy constraint, ask an organization policy administrator to do the following:

1. At the organization level, create a tag key and tag value that you will use to define whether a resource should be exempt from the organization policy. We recommend creating a tag with the keydisableServiceAccountKeyUpload and the valuesenforced andnot_enforced.

   To learn how to create tag keys and tag values, seeCreating and defining a new tag.

2. Attach thedisableServiceAccountKeyUpload tag to the organization and set its value toenforced. All resources in the organization inherit this tag value, unless it's overwritten with a different tag value.

   To learn how to attach tags to resources, seeAttaching tags to resources.

3. For each project or folder that you want to exempt from the organization policy, attach thedisableServiceAccountKeyUpload tag and set its value tonot_enforced. Setting a tag value for a project or folder in this way overrides the tag value inherited from the organization.

4. Create or update the organization policy that prevents uploading service account keys so that it doesn't enforce the constraint for exempt resources. This policy should have the following rules:

   • Configure theiam.disableServiceAccountKeyUpload constraint to not be enforced on any resources with thedisableServiceAccountKeyUpload: not_enforced tag. The condition in this rule should look like the following:

     "resource.matchTag('ORGANIZATION_ID/disableServiceAccountKeyUpload', 'not_enforced')"

   • Configure theiam.disableServiceAccountKeyUpload constraint to be enforced on all other resources.

Upload a public key for a service account

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

The key you upload must be an RSA public key that is wrapped in anX.509 v3 certificate and encoded in base64. You canuse tools such asOpenSSL to generate a key andcertificate 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 isvisible to anyone who retrieves the certificate. For more information,seeAvoid disclosing confidential information in uploaded X.509certificates.

If theiam.serviceAccountKeyExpiryHoursorganization policy constraint is enforced for your project, then the key thatyou upload needs to expire within the time period specified in the constraint.To set the expiry time of the key, use the-days value in the command that youuse to generate the X.509 certificate. If the-days value is greater than thetime period specified in the constraint, then the command will fail.

For example, the following command generates a 2048-bit RSA key pair and wrapsthe 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 thepublic_key.pem file as the public key for a serviceaccount.

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

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

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

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

{  "publicKeyData": "PUBLIC_KEY_DATA"}

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"

$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

{  "name": "projects/my-project/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com/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, seeRestricting service account key upload.

Note: If your organization was created on or after May 3, 2024, this constraint is enforced by default.

What's next

• Learn how tocreate and delete service account keys.
• Learn how tolist and get service account keys.
• Learn aboutalternatives to service account keys for authentication.
• Learn how to use service account keys toauthenticate as a serviceaccount.
• Understand thebest practices for managing service accountkeys.