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
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
.
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:
For more information about granting roles, see
Manage access
.
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:
Required permissions
The following permissions are required to allow service account keys to be uploaded in a project:
-
orgpolicy.constraints.list
-
orgpolicy.customConstraints.create
-
orgpolicy.customConstraints.delete
-
orgpolicy.customConstraints.get
-
orgpolicy.customConstraints.list
-
orgpolicy.customConstraints.update
-
orgpolicy.policies.create
-
orgpolicy.policies.delete
-
orgpolicy.policies.list
-
orgpolicy.policies.update
-
orgpolicy.policy.get
-
orgpolicy.policy.set
-
resourcemanager.organizations.get
-
resourcemanager.projects.listTagBindings
-
resourcemanager.projects.listEffectiveTags
-
resourcemanager.tagKeys.get
-
resourcemanager.tagKeys.list
-
resourcemanager.tagValues.list
-
resourcemanager.tagValues.get
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:
-
At the organization level, create a tag key and tag value that you will use to define whether
a project or folder 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
.
-
Attach the
disableServiceAccountKeyUpload
tag to the organization and set its value to
enforced
. All projects or folders 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
.
-
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.
-
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.
To learn how to create organization policies with tag conditions, see
Setting an
organization policy with tags
.
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
- In the Google Cloud console, go to the
Service accounts
page.
Go to Service accounts
school
The remaining steps will appear
automatically in the Google Cloud console.
- Select a project.
- On the
Service accounts
page, click the email address of the service account that you want
to upload a key for.
- Click the
Keys
tab.
- Click the
Add key
drop-down menu, then select
Upload existing key
.
- 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.
- 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)
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)
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/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, see
Restricting service account key upload
.
What's next
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