Upload service account keys

Stay organized with collections Save and categorize content based on your preferences.

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.

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 to projects, folders, and organizations.

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

For more information, see Service Accounts roles.

Depending on your organization policy configuration, you might also need to allow service account keys to be uploaded in your project before 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, see Manage 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 the Required permissions section:

You might also be able to get these permissions with custom roles or other predefined roles.

Allow service account key upload

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

We recommend enforcing this constraint for most projects and only exempting projects that truly require service account keys. For more information about alternative authentication methods, see Choose the right authentication method for your use case.

To exempt a project from the iam.disableServiceAccountKeyUpload organization policy 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 key disableServiceAccountKeyUpload and the values enforced and not_enforced.

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

2. Attach the disableServiceAccountKeyUpload tag to the organization and set its value to enforced. 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, see Attaching tags to resources.

3. For each project or folder that you want to exempt from the organization policy, attach the disableServiceAccountKeyUpload tag and set its value to not_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 the iam.disableServiceAccountKeyUpload constraint to not be enforced on any resources with the disableServiceAccountKeyUpload: not_enforced tag. The condition in this rule should look like the following:

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

   • Configure the iam.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 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 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.

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.