Migrating to the Service Account Credentials API

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. You must migrate to the Service Account Credentials API before July 1, 2021. Also, if you use the gcloud command-line tool to sign JWTs, you might need to add a new claim to the JWT Claims Set.

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 prevents you from authenticating with a self-signed token, then obtaining another self-signed token. As a result, if an attacker obtains a signed token, they cannot use it to refresh the token.

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.

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 (protoPayload.methodName) is one of the following:

  • google.iam.admin.v1.SignBlob
  • google.iam.admin.v1.SignJwt

Service Account Credentials API

The method name is one of the following:

  • SignBlob
  • SignJwt
Request type

IAM API

The request type (protoPayload.request.@type) is one of the following:

  • type.googleapis.com/google.iam.admin.v1.SignBlobRequest
  • type.googleapis.com/google.iam.admin.v1.SignJwtRequest

Service Account Credentials API

The request type is one of the following:

  • type.googleapis.com/google.iam.credentials.v1.SignBlobRequest
  • type.googleapis.com/google.iam.credentials.v1.SignJwtRequest
Service name

IAM API

The service name (protoPayload.serviceName) is iam.googleapis.com.

Service Account Credentials API

The service name is iamcredentials.googleapis.com.

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's operations suite.

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:

  • POST https://iam.googleapis.com/v1/projects/project-id/serviceAccounts/sa-email:signJwt

    In this URL, project-id is the project ID, and sa-email is the email address for the service account.

  • POST https://iam.googleapis.com/v1/projects/-/serviceAccounts/sa-email:signJwt

    In this URL, the wildcard character - takes the place of the project ID, and sa-email is the email address for the service account.

Service Account Credentials API

Use the following HTTP method and endpoint. Do not replace the wildcard character with the project ID:

POST https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/sa-email:signJwt

In this URL, sa-email is the email address for the service account.

Request body

IAM API

The request body includes a payload field. Its value is the JWT payload to sign. The payload must be a JSON object, serialized as a string, that contains a JWT Claims Set.

If you provide an expiration time (exp) claim, it must be no more than 1 hour in the future. If you omit the exp claim, it is added automatically and is set to 1 hour in the future.

Service Account Credentials API

The request body includes a payload field that is identical to the IAM API, except for the behavior of the expiration time (exp) claim:

  • If you provide the exp claim, it must be no more than 12 hours in the future.
  • If you omit the exp claim, it is not added automatically. You must provide this claim if you use the signed JWT to authenticate with Google APIs, or with another API that requires the exp claim.
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 client library for Python, 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:

  • POST https://iam.googleapis.com/v1/projects/project-id/serviceAccounts/sa-email:signBlob

    In this URL, project-id is the project ID, and sa-email is the email address for the service account.

  • POST https://iam.googleapis.com/v1/projects/-/serviceAccounts/sa-email:signBlob

    In this URL, the wildcard character - takes the place of the project ID, and sa-email is the email address for the service account.

Service Account Credentials API

Use the following HTTP method and endpoint. Do not replace the wildcard character with the project ID:

POST https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/sa-email:signBlob

In this URL, sa-email is the email address for the service account.

Request body

IAM API

The request body includes a bytesToSign field. Its value is a base64-encoded string that represents the binary blob to sign.

Service Account Credentials API

The request body includes a payload field that has the same value as the bytesToSign field in the IAM API.

Response body

IAM API

The response body contains a keyId field, which identifies the key that was used to sign the blob, and a signature field, which contains a base64-encoded string that represents the signature.

Service Account Credentials API

The response body contains a keyId field that is identical to the keyId field in the IAM API, as well as a signedBlob field that is identical to the signature field in the IAM API.

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 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 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 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 client library for Python, 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 tool

The gcloud command-line tool 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 tool to sign JWTs, you must follow these steps before July 1, 2021:

  1. 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.

  2. 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.

  3. 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:

  1. In the Cloud Console, go to the Quotas page.

    Go to the Quotas page

  2. Select a project. You can click a recent project, or you can click Select project to search all of your projects.

  3. In the Filter table text box above the table, enter Sign requests per minute, then select the value that appears.

  4. In the Filter table text box, select OR from the drop-down list.

  5. In the Filter table text box, enter Generate credentials, then select the value that appears.

    The 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.

  6. 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.

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

  8. Repeat these steps for each project where you use the IAM API to sign JWTs and blobs.

What's next