The Service Account Credentials API creates short-lived credentials for Identity and Access Management (IAM) service accounts. You can also use this API to sign JSON Web Tokens (JWTs), as well as blobs of binary data that contain other types of tokens.
The IAM API also contains methods for signing JWTs and binary blobs. As of July 1, 2020, these methods are deprecated in the REST API and in all client libraries for the IAM API. Also, if you use the Google Cloud CLI to sign JWTs, you might need to add a new claim to the JWT Claims Set. You can still use the deprecated methods, but they don't support advanced features like HTTP request batching. We encourage you to migrate to the Service Account Credentials API instead.
Compared to the IAM API, the Service Account Credentials API provides more flexibility for the expiration time of signed JWTs. In addition, the Service Account Credentials API adds multiple new API methods to generate impersonation tokens.
This page explains how to update your existing code to use the Service Account Credentials API. If you have feedback on this change, you can complete the feedback form. You can also use the email address iam-sign-deprecation-public@google.com to request support and provide detailed feedback.
Before you begin
-
Enable the Service Account Credentials API.
Enabling audit logs
If you want to receive audit logs for requests to sign JWTs and blobs, you must enable Data Access audit logs for the IAM API. Enabling Data Access audit logs for the IAM API also enables these audit logs for the Service Account Credentials API.
There are a few notable differences between the log entries that each API generates:
Differences for audit log entries | |
---|---|
Method name |
IAM API
The method name (
Service Account Credentials API The method name is one of the following:
|
Request type |
IAM API
The request type (
Service Account Credentials API The request type is one of the following:
|
Service name |
IAM API
The service name ( Service Account Credentials API
The service name is |
Data Access audit logs count toward your free monthly allotment of logging data ingestion. If you exceed this allotment, you will be charged for log ingestion. For details, see Pricing for Google Cloud Observability.
Migrating code for signing JWTs
This section describes how to migrate code that signs JWTs to the Service Account Credentials API.
Signing JWTs with the REST API
The following table shows the differences between signing a JWT with the IAM REST API and signing a JWT with the Service Account Credentials API. Update your code to reflect these differences:
Differences for signing a JWT | |
---|---|
HTTP endpoints |
IAM API The IAM API uses the following HTTP methods and endpoints:
Service Account Credentials API Use the following HTTP method and endpoint. Do not replace the wildcard character with the project ID:
In this URL, |
Request body |
IAM API The request body includes a If you provide an expiration time ( Service Account Credentials API The request body includes a
|
Response body |
Both APIs use the same fields in the response body. |
Signing JWTs with a client library
The client libraries for the Service Account Credentials API are separate from the client libraries for the IAM API.
To use the Service Account Credentials API, add its client library to your application, and update your code to use the new client library:
C#
Add the Service Account Credentials client library
for C# to your application. Use the
SignJwt()
method
to generate a signature.
The name of the service account must use the wildcard character -
to represent the
project ID:
Valid: Name with wildcard character
projects/-/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com
Invalid: Name with project ID
projects/my-project/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com
If you no longer use the IAM client library for C#, you can remove it from your application.
Go
Add the Service Account Credentials client library
for Go to your application. Use the
IamCredentialsClient.SignJwt() function
to generate a signature.
The name of the service account must use the wildcard character -
to represent the
project ID:
Valid: Name with wildcard character
projects/-/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com
Invalid: Name with project ID
projects/my-project/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com
If you no longer use the IAM client library for Go, you can remove it from your application.
Java
Add the Service Account Credentials client library
for Java to your application. Use the
IamCredentialsClient#signJwt()
method
to generate a signature.
The name of the service account must use the wildcard character -
to represent the
project ID:
Valid: Name with wildcard character
projects/-/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com
Invalid: Name with project ID
projects/my-project/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com
If you no longer use the IAM client library for Java, you can remove it from your application.
Node.js
Add the Service Account Credentials client library
for Node.js to your application. Use the
signJwt()
method
to generate a signature.
The name of the service account must use the wildcard character -
to represent the
project ID:
Valid: Name with wildcard character
projects/-/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com
Invalid: Name with project ID
projects/my-project/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com
If you no longer use the IAM client library for Node.js, you can remove it from your application.
PHP
Add the Service Account Credentials client library
for PHP to your application. Use the
signJwt()
method
to generate a signature.
The name of the service account must use the wildcard character -
to represent the
project ID:
Valid: Name with wildcard character
projects/-/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com
Invalid: Name with project ID
projects/my-project/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com
If you no longer use the IAM client library for PHP, you can remove it from your application.
Python
Add the Service Account Credentials client library
for Python to your application. Use the
sign_jwt()
method
to generate a signature.
The name of the service account must use the wildcard character -
to represent the
project ID:
Valid: Name with wildcard character
projects/-/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com
Invalid: Name with project ID
projects/my-project/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com
If you no longer use the
iam_credentials
client library, you can remove it from your application.
Ruby
Add the Service Account Credentials client library
for Ruby to your application. Use the
sign_service_account_jwt()
method
to generate a signature.
The name of the service account must use the wildcard character -
to represent the
project ID:
Valid: Name with wildcard character
projects/-/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com
Invalid: Name with project ID
projects/my-project/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com
If you no longer use the IAM client library for Ruby, you can remove it from your application.
Migrating code for signing binary blobs
This section describes how to migrate code that signs binary blobs to the Service Account Credentials API.
Signing binary blobs with the REST API
The following table shows the differences between signing a binary blob with the IAM REST API and signing a binary blob with the Service Account Credentials API. Update your code to reflect these differences:
Differences for signing a binary blob | |
---|---|
HTTP endpoints |
IAM API The IAM API uses the following HTTP methods and endpoints:
Service Account Credentials API Use the following HTTP method and endpoint. Do not replace the wildcard character with the project ID:
In this URL, |
Request body |
IAM API The request body includes a Service Account Credentials API The request body includes a |
Response body |
IAM API The response body contains a Service Account Credentials API The response body contains a |
Signing binary blobs with a client library
The client libraries for the Service Account Credentials API are separate from the client libraries for the IAM API.
To use the Service Account Credentials API, add its client library to your application, and update your code to use the new client library:
C++
If you use the Cloud Storage C++ client library to sign blobs, either directly or as a dependency of another client library:
Upgrade to version 0.9.0 or later of
google-cloud-cpp
.
If you use another client library to sign blobs:
Contact iam-sign-deprecation-public@google.com
for support.
C#
If you use the IAM client library for C#, either directly or as a dependency of another client library:
Add the Service Account Credentials client library
for C# to your application. Use the
SignBlob()
method
to generate a signature.
The name of the service account must use the wildcard character -
to represent the
project ID:
Valid: Name with wildcard character
projects/-/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com
Invalid: Name with project ID
projects/my-project/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com
If you no longer use the IAM client library for C#, you can remove it from your application.
If you use the Firebase Admin DotNet SDK, either directly or as a dependency of another client library:
Upgrade to version 1.17.1 or later of firebase-admin-dotnet
.
If you use another client library to sign blobs:
Contact iam-sign-deprecation-public@google.com
for support.
Go
If you use the IAM client library for Go, either directly or as a dependency of another client library:
Add the Service Account Credentials client library
for Go to your application. Use the
IamCredentialsClient.SignBlob() function
to generate a signature.
The name of the service account must use the wildcard character -
to represent the
project ID:
Valid: Name with wildcard character
projects/-/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com
Invalid: Name with project ID
projects/my-project/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com
If you no longer use the IAM client library for Go, you can remove it from your application.
If you use the Firebase Admin Go SDK, either directly or as a dependency of another client library:
Upgrade to version 4.1.0 or later of firebase-admin-go
.
If you use another client library to sign blobs:
Contact iam-sign-deprecation-public@google.com
for support.
Java
If you use the IAM client library for Java, either directly or as a dependency of another client library:
Add the Service Account Credentials client library
for Java to your application. Use the
IamCredentialsClient#signBlob()
method
to generate a signature.
The name of the service account must use the wildcard character -
to represent the
project ID:
Valid: Name with wildcard character
projects/-/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com
Invalid: Name with project ID
projects/my-project/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com
If you no longer use the IAM client library for Java, you can remove it from your application.
If you use the Google Auth Library for Java, either directly or as a dependency of another client library:
Upgrade to version 0.14.0 or later of google-auth-library-java
.
If you use the Firebase Admin Java SDK, either directly or as a dependency of another client library:
Upgrade to version 7.0.1 or later of firebase-admin-java
.
If you use another client library to sign blobs:
Contact iam-sign-deprecation-public@google.com
for support.
Node.js
If you use the IAM client library for Node.js, either directly or as a dependency of another client library:
Add the Service Account Credentials client library
for Node.js to your application. Use the
signBlob()
method
to generate a signature.
The name of the service account must use the wildcard character -
to represent the
project ID:
Valid: Name with wildcard character
projects/-/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com
Invalid: Name with project ID
projects/my-project/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com
If you no longer use the IAM client library for Node.js, you can remove it from your application.
If you use the Google Auth Library for Node.js, either directly or as a dependency of another client library:
Upgrade to version 6.0.0 or later of google-auth-library-nodejs
.
If you use the Firebase Admin Node.js SDK, either directly or as a dependency of another client library:
Upgrade to version 8.13.0 or later of firebase-admin-node
.
If you use another client library to sign blobs:
Contact iam-sign-deprecation-public@google.com
for support.
PHP
If you use the IAM client library for PHP, either directly or as a dependency of another client library:
Add the Service Account Credentials client library
for PHP to your application. Use the
signBlob()
method
to generate a signature.
The name of the service account must use the wildcard character -
to represent the
project ID:
Valid: Name with wildcard character
projects/-/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com
Invalid: Name with project ID
projects/my-project/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com
If you no longer use the IAM client library for PHP, you can remove it from your application.
If you use the Google Auth Library for PHP, either directly or as a dependency of another client library:
Upgrade to version 1.5.0 or later of google-auth-library-php
.
If you use another client library to sign blobs:
Contact iam-sign-deprecation-public@google.com
for support.
Python
If you use the IAM client library for Python, either directly or as a dependency of another client library:
Add the Service Account Credentials client library
for Python to your application. Use the
sign_blob()
method
to generate a signature.
The name of the service account must use the wildcard character -
to represent the
project ID:
Valid: Name with wildcard character
projects/-/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com
Invalid: Name with project ID
projects/my-project/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com
If you no longer use the
iam_credentials
client library, you can remove it from your application.
If you use the Google Auth Library for Python, either directly or as a dependency of another client library:
Upgrade to version 1.21.2 or later of google-auth-library-python
.
If you use the Python client for Cloud Storage, either directly or as a dependency of another client library:
Upgrade to version 1.30.0 or later of python-storage
.
If you use another client library to sign blobs:
Contact iam-sign-deprecation-public@google.com
for support.
Ruby
If you use the IAM client library for Ruby, either directly or as a dependency of another client library:
Add the Service Account Credentials client library
for Ruby to your application. Use the
sign_service_account_blob()
method
to generate a signature.
The name of the service account must use the wildcard character -
to represent the
project ID:
Valid: Name with wildcard character
projects/-/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com
Invalid: Name with project ID
projects/my-project/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com
If you no longer use the IAM client library for Ruby, you can remove it from your application.
If you use another client library to sign blobs:
Contact iam-sign-deprecation-public@google.com
for support.
Migrating code that uses the gcloud CLI
The Google Cloud CLI provides commands that use the IAM API to sign JWTs and binary blobs, including the following:
On or after July 1, 2021, we will update these commands to use the Service Account Credentials API. This change will not affect commands to sign blobs.
If you use the gcloud CLI to sign JWTs, you must follow these steps before July 1, 2021:
Check whether you include the expiration time (
exp
) claim in the JWT Claims Set.If you already include this claim, you do not need to make any changes. You can skip the remaining steps.
If you do not include this claim, continue to the next step.
Check whether you use the signed JWT to authenticate with Google APIs, or with another API that requires the
exp
claim.If you omit this claim, the IAM API automatically sets it to 1 hour in the future. In contrast, the Service Account Credentials API does not set this field automatically.
If you are sure that you do not need the
exp
claim, you do not need to make any changes. You can skip the remaining steps.If you know that you need the
exp
claim, or if you aren't sure, continue to the next step.Update your code for creating JWTs so that it adds the
exp
claim to the JWT Claims Set.You can set the
exp
claim up to 1 hour in the future.
Checking quotas
Quota for the Service Account Credentials API is separate from quota for the IAM API. If you have received a quota increase to sign JWTs and blobs with the IAM API, you might also need to request an increase for the Service Account Credentials API.
To view your quota and actual usage for both APIs, and to request a quota increase if necessary, do the following:
In the Google Cloud console, go to the Quotas page.
Select a project. You can click a recent project, or you can click Select project to search all of your projects.
In the Filter table text box above the table, enter
Sign requests per minute
, then select the value that appears.In the Filter table text box, select OR from the drop-down list.
In the Filter table text box, enter
Generate credentials
, then select the value that appears.The Google Cloud console shows your current usage for signing JWTs and blobs over the past minute; your peak usage per minute over the past 7 days; and your current quota, which appears in the Limit column.
Compare the quotas for each row in the table, and ensure that your quota for the Service Account Credentials API is higher than your 7-day peak usage of the IAM API.
Optional: If your quota for the Service Account Credentials API is too low, select the checkbox for the Service Account Credentials API, then click Edit quotas. Complete the form to request a quota increase.
Repeat these steps for each project where you use the IAM API to sign JWTs and blobs.
What's next
- Find out how to create a signed JWT or create a signed binary blob with the Service Account Credentials REST API.
- Get details about the REST API for the Service Account Credentials API.
- Understand quotas and limits for IAM.