Create short-lived credentials for a service account

This page explains how to use service account impersonation to create short-lived credentials for a service account. Depending on the type of token you create, the short-lived token provides the identity (for ID tokens) or permissions (for access tokens) associated with the impersonated service account.

If your system architecture requires you to use a series of token generation calls, you can use a delegation chain consisting of several service accounts. In most cases, the direct method, as explained on this page, is sufficient.

About service account impersonation

Users and workloads need Identity and Access Management (IAM) roles to access resources. Sometimes, it makes sense to grant roles to each user account and service account that needs them. But if that is not feasible, or if you want more centralized control, you can use service account impersonation.

With direct service account impersonation, there are two principals involved:

  • The caller

    The caller can be either a user account or a service account. The caller needs to access the target resource, but lacks the required permissions to do so.

  • The privilege-bearing service account

    This service account has the permissions required to access the target resource.

When the caller impersonates the privilege-bearing service account, it receives a short-lived token with the permissions of the privilege-bearing service account. Until the token expires, the caller can use the token to access the target resource.

Using service account impersonation to create short-lived tokens has the following advantages:

  • Short-lived credentials have a limited lifetime, with durations of just a few hours or shorter, and are not automatically refreshed. They create less risk than long-lived credentials, such as service account keys.

  • The privilege-bearing service account can be centrally managed and controlled, preventing the need for wide-scale updates if the required permissions change.

Before you begin

Create a short-lived access token

Access tokens are accepted for authentication by most Google APIs. When you generate an access token by using service account impersonation, the access token comes without a refresh token, which means that when the token expires, you must repeat the impersonation process to generate a new one.

For more information, see Access tokens.

To create a short-lived access token, complete these tasks:

Provide required permissions

A direct request involves two identities: the caller, and the privilege-bearing service account for which the credential is created. How you set up the permissions depends on whether the caller is using a service account or user credentials.

If you want to run a REST or gcloud CLI command on this page in a local development environment, the caller can be represented by user credentials. For automated workloads, such as an application running on Compute Engine, the caller must be represented by a service account.

Service account

When the calling application uses a service account as its identity, the following principals are involved:

  • Caller service account (CALLER_SA)

    This service account represents the calling application, which issues the request for the short-lived credentials.

  • Privilege-bearing service account (PRIV_SA)

    This service account is granted the IAM roles needed for the short-lived token. This is the service account for which the short-lived token is created.

To give CALLER_SA permissions to create short-lived credentials for PRIV_SA, you grant CALLER_SA the Service Account Token Creator role (roles/iam.serviceAccountTokenCreator) on PRIV_SA.

Grant the required role on PRIV_SA:

Console

  1. In the Google Cloud console, go to the Service Accounts page.

    Go to Service Accounts

  2. Select a project.
  3. Click the email address of the privilege-bearing service account, PRIV_SA.
  4. Click the Permissions tab.
  5. Under Principals with access to this service account, click Grant Access.

  6. Enter the email address of the caller service account, CALLER_SA.

    For example, demo@my-project.iam.gserviceaccount.com.

  7. Select the Service Account Token Creator role (roles/iam.serviceAccountTokenCreator).
  8. Click Save to grant the role to the service account.

gcloud

The gcloud iam service-accounts add-iam-policy-binding command grants a role on a service account.

Before using any of the command data below, make the following replacements:

  • PRIV_SA: The email address of the privilege-bearing service account for which the token is generated.
  • CALLER_SA: The email address of the service account representing the application that is requesting the short-lived token.

Execute the following command:

Linux, macOS, or Cloud Shell

gcloud iam service-accounts add-iam-policy-binding PRIV_SA \
    --member=serviceAccount:CALLER_SA --role=roles/iam.serviceAccountTokenCreator --format=json

Windows (PowerShell)

gcloud iam service-accounts add-iam-policy-binding PRIV_SA `
    --member=serviceAccount:CALLER_SA --role=roles/iam.serviceAccountTokenCreator --format=json

Windows (cmd.exe)

gcloud iam service-accounts add-iam-policy-binding PRIV_SA ^
    --member=serviceAccount:CALLER_SA --role=roles/iam.serviceAccountTokenCreator --format=json

You should receive a response similar to the following:

Updated IAM policy for serviceAccount [PRIV_SA].
{
  "bindings": [
    {
      "members": [
        "serviceAccount:CALLER_SA"
      ],
      "role": "roles/iam.serviceAccountTokenCreator"
    }
  ],
  "etag": "BwXhCB4eyjY=",
  "version": 1
}

REST

  1. Read the allow policy for PRIV_SA:

    The serviceAccounts.getIamPolicy method gets a service account's allow policy.

    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.
    • PRIV_SA: The email address of the privilege-bearing service account for which the short-lived token is created.
    • POLICY_VERSION: The policy version to be returned. Requests should specify the most recent policy version, which is policy version 3. See Specifying a policy version when getting a policy for details.

    HTTP method and URL: 

    POST https://iam.googleapis.com/v1/projects/PROJECT_ID/serviceAccounts/PRIV_SA:getIamPolicy

    Request JSON body: 

    {
  "options": {
    "requestedPolicyVersion": POLICY_VERSION
  }
}

    To send your request, expand one of these options:

    You should receive a JSON response similar to the following:

    {
  "version": 1,
  "etag": "BwWKmjvelug=",
  "bindings": [
    {
      "role": "roles/serviceAccountAdmin",
      "members": [
        "user:admin@example.com"
      ]
    }
  ]
}

    If you have not granted any roles on the service account, the response contains only an etag value. Include that etag value in the next step.

  2. Modify the allow policy to grant CALLER_SA the Service Account Token Creator role (roles/iam.serviceAccountTokenCreator).

    For example, to modify the sample response from the previous step, add the following: 

      {
    "version": 1,
    "etag": "BwWKmjvelug=",
    "bindings": [
      {
        "role": "roles/serviceAccountAdmin",
        "members": [
          "user:admin@example.com"
        ]
      },
      {
        "role": "roles/iam.serviceAccountTokenCreator",
        "members": [
          "serviceAccount:CALLER_SA"
        ]
      }
    ]
  }

  3. Write the updated allow policy:

    The serviceAccounts.setIamPolicy method sets an updated allow policy for 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.
    • PRIV_SA: The email address of the privilege-bearing service account for which the short-lived token is created.
    • POLICY_VERSION: The policy version to be returned. Requests should specify the most recent policy version, which is policy version 3. See Specifying a policy version when getting a policy for details.

    • POLICY: A JSON representation of the policy that you want to set. For more information about the format of a policy, see the Policy reference.

      For example, to set the allow policy shown in the previous step, replace POLICY with the following, where CALLER_SA is the service account creating the short-lived token:

      {
  "version": 1,
  "etag": "BwWKmjvelug=",
  "bindings": [
    {
      "role": "roles/serviceAccountAdmin",
      "members": [
        "user:admin@example.com"
      ]
    },
    {
      "role": "roles/iam.serviceAccountTokenCreator",
      "members": [
        "serviceAccount:CALLER_SA"
      ]
    }
  ]
}

    HTTP method and URL: 

    POST https://iam.googleapis.com/v1/projects/PROJECT_ID/serviceAccounts/PRIV_SA

    Request JSON body: 

    {
  "policy": POLICY
}

    To send your request, expand one of these options:

    The response contains the updated allow policy.

User credentials

When you want to use the Google Cloud CLI to generate short-lived tokens, or you want to generate short-lived tokens from a local development environment, you can use a user account to generate the tokens. Often, you can use your own Google Account.

When you use a user account to generate short-lived tokens, the following identities are involved:

  • Caller Google Account (CALLER_ACCOUNT)

    This user account is used to generate short-lived credentials for the privilege-bearing service account.

  • Privilege-bearing service account (PRIV_SA)

    This service account is granted the IAM roles needed for the short-lived token. This is the service account for which the short-lived token is created.

To enable CALLER_ACCOUNT to create short-lived credentials for PRIV_SA, you grant CALLER_ACCOUNT the Service Account Token Creator role (roles/iam.serviceAccountTokenCreator) on PRIV_SA.

Grant the required role on PRIV_SA:

Console

  1. In the Google Cloud console, go to the Service Accounts page.

    Go to Service Accounts

  2. Select a project.
  3. Click the email address of the privilege-bearing service account, PRIV_SA.
  4. Click the Permissions tab.
  5. Under Principals with access to this service account, click Grant Access.

  6. Enter the email address of the caller Google Account, CALLER_ACCOUNT.

    For example, username@google.com.

  7. Select the Service Account Token Creator role (roles/iam.serviceAccountTokenCreator).
  8. Click Save to grant the role to the user account.

gcloud

The gcloud iam service-accounts add-iam-policy-binding command grants a role on a service account.

Before using any of the command data below, make the following replacements:

  • PRIV_SA: The email address of the privilege-bearing service account for which the token is generated.
  • CALLER_ACCOUNT: The email address of the user account being used to request the short-lived token.

Execute the following command:

Linux, macOS, or Cloud Shell

gcloud iam service-accounts add-iam-policy-binding PRIV_SA \
    --member=user:CALLER_ACCOUNT --role=roles/iam.serviceAccountTokenCreator --format=json

Windows (PowerShell)

gcloud iam service-accounts add-iam-policy-binding PRIV_SA `
    --member=user:CALLER_ACCOUNT --role=roles/iam.serviceAccountTokenCreator --format=json

Windows (cmd.exe)

gcloud iam service-accounts add-iam-policy-binding PRIV_SA ^
    --member=user:CALLER_ACCOUNT --role=roles/iam.serviceAccountTokenCreator --format=json

You should receive a response similar to the following:

Updated IAM policy for serviceAccount [PRIV_SA].
{
  "bindings": [
    {
      "members": [
        "user:CALLER_ACCOUNT"
      ],
      "role": "roles/iam.serviceAccountTokenCreator"
    }
  ],
  "etag": "BwX1ZbefjXU=",
  "version": 1
}

REST

  1. Read the allow policy for PRIV_SA:

    The serviceAccounts.getIamPolicy method gets a service account's allow policy.

    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.
    • PRIV_SA: The email address of the privilege-bearing service account for which the short-lived token is created.
    • POLICY_VERSION: The policy version to be returned. Requests should specify the most recent policy version, which is policy version 3. See Specifying a policy version when getting a policy for details.

    HTTP method and URL: 

    POST https://iam.googleapis.com/v1/projects/PROJECT_ID/serviceAccounts/PRIV_SA:getIamPolicy

    Request JSON body: 

    {
  "options": {
    "requestedPolicyVersion": POLICY_VERSION
  }
}

    To send your request, expand one of these options:

    You should receive a JSON response similar to the following:

    {
  "version": 1,
  "etag": "BwWKmjvelug=",
  "bindings": [
    {
      "role": "roles/serviceAccountAdmin",
      "members": [
        "user:admin@example.com"
      ]
    }
  ]
}

    If you have not granted any roles on the service account, the response contains only an etag value. Include that etag value in the next step.

  2. Modify the allow policy to grant CALLER_ACCOUNT the Service Account Token Creator role ( roles/iam.serviceAccountTokenCreator).

    For example, to modify the sample response from the previous step, add the following: 

    {
  "version": 1,
  "etag": "BwWKmjvelug=",
  "bindings": [
    {
      "role": "roles/serviceAccountAdmin",
      "members": [
        "user:admin@example.com"
      ]
    },
    {
      "role": "roles/iam.serviceAccountTokenCreator",
      "members": [
        "user:CALLER_ACCOUNT"
      ]
    }
  ]
}

  3. Write the updated allow policy:

    The serviceAccounts.setIamPolicy method sets an updated allow policy for 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.
    • PRIV_SA: The email address of the privilege-bearing service account for which the short-lived token is created.
    • POLICY_VERSION: The policy version to be returned. Requests should specify the most recent policy version, which is policy version 3. See Specifying a policy version when getting a policy for details.

    • POLICY: A JSON representation of the policy that you want to set. For more information about the format of a policy, see the Policy reference.

      For example, to set the allow policy shown in the previous step, replace POLICY with the following, where CALLER_ACCOUNT is the user account creating the short-lived token:

      {
  "version": 1,
  "etag": "BwWKmjvelug=",
  "bindings": [
    {
      "role": "roles/serviceAccountAdmin",
      "members": [
        "user:admin@example.com"
      ]
    },
    {
      "role": "roles/iam.serviceAccountTokenCreator",
      "members": [
        "user:CALLER_ACCOUNT"
      ]
    }
  ]
}

    HTTP method and URL: 

    POST https://iam.googleapis.com/v1/projects/PROJECT_ID/serviceAccounts/PRIV_SA

    Request JSON body: 

    {
  "policy": POLICY
}

    To send your request, expand one of these options:

    The response contains the updated allow policy.

Generate the access token

You can generate an OAuth 2.0 access token by using the gcloud CLI, the REST API, or the Cloud Client Libraries and Google API Client Libraries.

If you use the REST API, and your system is configured to allow extended token lifetimes, you can create a token with a lifetime longer than the default. The Google Cloud CLI does not support setting a lifetime for the token.

The samples below are designed to be used in a local development environment; the caller must be represented by a user account, rather than a service account.

Generate an OAuth 2.0 access token for the privilege-bearing service account:

gcloud

  1. Log in to the Google Cloud CLI as the caller Google Account.

    gcloud auth login CALLER_ACCOUNT

  2. Impersonate the privilege-bearing service account to generate the token.

    The gcloud auth print-access-token command generates an OAuth 2.0 access token for a service account.

    Before using any of the command data below, make the following replacements:

    • PRIV_SA: The email address of the privilege-bearing service account for which the short-lived token is created.

      • Execute the following command:

      Linux, macOS, or Cloud Shell

      gcloud auth print-access-token --impersonate-service-account=PRIV_SA

      Windows (PowerShell)

      gcloud auth print-access-token --impersonate-service-account=PRIV_SA

      Windows (cmd.exe)

      gcloud auth print-access-token --impersonate-service-account=PRIV_SA

      You should receive a response similar to the following:

      WARNING: This command is using service account impersonation. All API calls will be executed as
[my-sa@my-project.iam.gserviceaccount.com].
ya29.c.b0AXv0zTPnzTnDV8F8Aj5Fgy46Yf2v_v8eZIoKq7xGpfbpXuy23aQ1693m3gAuE8AZga7w6kdagN7a9bfdDYbdeoGY0CMHOClsCwIdutL7k_RFC672lOCbUgF5hS8Iu2nCA8hle-11LJXBLmaxFmH08ZTBJLuDrWSNd8cYqGYFunSC1K1qLIPBF18tsa0hxVgKPucI8b1A9L8_MK1JGLGcr0n7-zY77_lmbcdODG3NmIbLOGWOutjJgqSO_YoeCKK2QTUZIp5PG7RkKlXWnmYJA9pEahzNoQrs5sWZctc2bia9af_ITzqqlXC9h1Kj5-me6e8rd734MJvpagqYazRk0gGWpMb03XmMGpgPc_FBp4pnX9rGOzW83SNpcDz8zeFO1Q0Bo3N7CuZougjRce0y8I2_4rtw5ME_nV3wrCWa..................................................................................................................................................................................................................................................................................................

REST

The Service Account Credentials API's serviceAccounts.generateAccessToken method generates an OAuth 2.0 access token for a service account.

Before using any of the request data, make the following replacements:

  • PRIV_SA: The email address of the privilege-bearing service account for which the short-lived token is created.

  • LIFETIME: The amount of time until the access token expires, in seconds. For example, 300s.

    By default, the maximum token lifetime is 1 hour (3,600 seconds). To extend the maximum lifetime for these tokens to 12 hours (43,200 seconds), add the service account to an organization policy that includes the constraints/iam.allowServiceAccountCredentialLifetimeExtension list constraint.

HTTP method and URL: 

POST https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/PRIV_SA:generateAccessToken

Request JSON body: 

{
  "scope": [
    "https://www.googleapis.com/auth/cloud-platform"
  ],
  "lifetime": "LIFETIME"
}

To send your request, expand one of these options:

If the generateAccessToken request was successful, the response body contains an OAuth 2.0 access token and an expiration time. The accessToken can then be used to authenticate a request on behalf of the service account until the expireTime has been reached: 

{
  "accessToken": "eyJ0eXAi...NiJ9",
  "expireTime": "2020-04-07T15:01:23.045123456Z"
}

Create an OpenID Connect (OIDC) ID token

ID tokens follow the OpenID Connect (OIDC) specification. ID tokens are accepted by a limited number of services and applications.

For more information, see ID tokens and Authentication for applications hosted on Cloud Run or Cloud Functions.

To create an ID token, complete these tasks:

Provide required permissions

A direct request involves two identities: the caller, and the privilege-bearing service account for which the credential is created. How you set up the permissions depends on whether the caller is using a service account or user credentials.

If you want to run a REST or gcloud CLI command on this page in a local development environment, the caller can be represented by user credentials. For automated workloads, such as an application running on Compute Engine, the caller must be represented by a service account.

Service account

When the calling application uses a service account as its identity, the following principals are involved:

  • Caller service account (CALLER_SA)

    This service account represents the calling application, which issues the request for the short-lived credentials.

  • Privilege-bearing service account (PRIV_SA)

    This service account is granted the IAM roles needed for the short-lived token. This is the service account for which the short-lived token is created.

To give CALLER_SA permissions to create short-lived credentials for PRIV_SA, you grant CALLER_SA the Service Account OpenID Connect Identity Token Creator role (roles/iam.serviceAccountOpenIdTokenCreator) on PRIV_SA.

Grant the required role on PRIV_SA:

Console

  1. In the Google Cloud console, go to the Service Accounts page.

    Go to Service Accounts

  2. Select a project.
  3. Click the email address of the privilege-bearing service account, PRIV_SA.
  4. Click the Permissions tab.
  5. Under Principals with access to this service account, click Grant Access.

  6. Enter the email address of the caller service account, CALLER_SA.

    For example, demo@my-project.iam.gserviceaccount.com.

  7. Select the Service Account OpenID Connect Identity Token Creator role (roles/iam.serviceAccountOpenIdTokenCreator).
  8. Click Save to grant the role to the service account.

gcloud

The gcloud iam service-accounts add-iam-policy-binding command grants a role on a service account.

Before using any of the command data below, make the following replacements:

  • PRIV_SA: The email address of the privilege-bearing service account for which the token is generated.
  • CALLER_SA: The email address of the service account representing the application that is requesting the short-lived token.

Execute the following command:

Linux, macOS, or Cloud Shell

gcloud iam service-accounts add-iam-policy-binding PRIV_SA \
    --member=serviceAccount:CALLER_SA --role=roles/iam.serviceAccountOpenIdTokenCreator --format=json

Windows (PowerShell)

gcloud iam service-accounts add-iam-policy-binding PRIV_SA `
    --member=serviceAccount:CALLER_SA --role=roles/iam.serviceAccountOpenIdTokenCreator --format=json

Windows (cmd.exe)

gcloud iam service-accounts add-iam-policy-binding PRIV_SA ^
    --member=serviceAccount:CALLER_SA --role=roles/iam.serviceAccountOpenIdTokenCreator --format=json

You should receive a response similar to the following:

Updated IAM policy for serviceAccount [PRIV_SA].
{
  "bindings": [
    {
      "members": [
        "serviceAccount:CALLER_SA"
      ],
      "role": "roles/iam.serviceAccountOpenIdTokenCreator"
    }
  ],
  "etag": "BwXhCB4eyjY=",
  "version": 1
}

REST

  1. Read the allow policy for PRIV_SA:

    The serviceAccounts.getIamPolicy method gets a service account's allow policy.

    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.
    • PRIV_SA: The email address of the privilege-bearing service account for which the short-lived token is created.
    • POLICY_VERSION: The policy version to be returned. Requests should specify the most recent policy version, which is policy version 3. See Specifying a policy version when getting a policy for details.

    HTTP method and URL: 

    POST https://iam.googleapis.com/v1/projects/PROJECT_ID/serviceAccounts/PRIV_SA:getIamPolicy

    Request JSON body: 

    {
  "options": {
    "requestedPolicyVersion": POLICY_VERSION
  }
}

    To send your request, expand one of these options:

    You should receive a JSON response similar to the following:

    {
  "version": 1,
  "etag": "BwWKmjvelug=",
  "bindings": [
    {
      "role": "roles/serviceAccountAdmin",
      "members": [
        "user:admin@example.com"
      ]
    }
  ]
}

    If you have not granted any roles on the service account, the response contains only an etag value. Include that etag value in the next step.

  2. Modify the allow policy to grant CALLER_SA the Service Account OpenID Connect Identity Token Creator role (roles/iam.serviceAccountOpenIdTokenCreator).

    For example, to modify the sample response from the previous step, add the following: 

      {
    "version": 1,
    "etag": "BwWKmjvelug=",
    "bindings": [
      {
        "role": "roles/serviceAccountAdmin",
        "members": [
          "user:admin@example.com"
        ]
      },
      {
        "role": "roles/iam.serviceAccountOpenIdTokenCreator",
        "members": [
          "serviceAccount:CALLER_SA"
        ]
      }
    ]
  }

  3. Write the updated allow policy:

    The serviceAccounts.setIamPolicy method sets an updated allow policy for 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.
    • PRIV_SA: The email address of the privilege-bearing service account for which the short-lived token is created.
    • POLICY_VERSION: The policy version to be returned. Requests should specify the most recent policy version, which is policy version 3. See Specifying a policy version when getting a policy for details.

    • POLICY: A JSON representation of the policy that you want to set. For more information about the format of a policy, see the Policy reference.

      For example, to set the allow policy shown in the previous step, replace POLICY with the following, where CALLER_SA is the service account creating the short-lived token:

      {
  "version": 1,
  "etag": "BwWKmjvelug=",
  "bindings": [
    {
      "role": "roles/serviceAccountAdmin",
      "members": [
        "user:admin@example.com"
      ]
    },
    {
      "role": "roles/iam.serviceAccountOpenIdTokenCreator",
      "members": [
        "serviceAccount:CALLER_SA"
      ]
    }
  ]
}

    HTTP method and URL: 

    POST https://iam.googleapis.com/v1/projects/PROJECT_ID/serviceAccounts/PRIV_SA

    Request JSON body: 

    {
  "policy": POLICY
}

    To send your request, expand one of these options:

    The response contains the updated allow policy.

User credentials

When you want to use the Google Cloud CLI to generate short-lived tokens, or you want to generate short-lived tokens from a local development environment, you can use a user account to generate the tokens. Often, you can use your own Google Account.

When you use a user account to generate short-lived tokens, the following identities are involved:

  • Caller Google Account (CALLER_ACCOUNT)

    This user account is used to generate short-lived credentials for the privilege-bearing service account.

  • Privilege-bearing service account (PRIV_SA)

    This service account is granted the IAM roles needed for the short-lived token. This is the service account for which the short-lived token is created.

To enable CALLER_ACCOUNT to create short-lived credentials for PRIV_SA, you grant CALLER_ACCOUNT the Service Account OpenID Connect Identity Token Creator role (roles/iam.serviceAccountOpenIdTokenCreator) on PRIV_SA.

Grant the required role on PRIV_SA:

Console

  1. In the Google Cloud console, go to the Service Accounts page.

    Go to Service Accounts

  2. Select a project.
  3. Click the email address of the privilege-bearing service account, PRIV_SA.
  4. Click the Permissions tab.
  5. Under Principals with access to this service account, click Grant Access.

  6. Enter the email address of the caller Google Account, CALLER_ACCOUNT.

    For example, username@google.com.

  7. Select the Service Account OpenID Connect Identity Token Creator role (roles/iam.serviceAccountOpenIdTokenCreator).
  8. Click Save to grant the role to the user account.

gcloud

The gcloud iam service-accounts add-iam-policy-binding command grants a role on a service account.

Before using any of the command data below, make the following replacements:

  • PRIV_SA: The email address of the privilege-bearing service account for which the token is generated.
  • CALLER_ACCOUNT: The email address of the user account being used to request the short-lived token.

Execute the following command:

Linux, macOS, or Cloud Shell

gcloud iam service-accounts add-iam-policy-binding PRIV_SA \
    --member=user:CALLER_ACCOUNT --role=roles/iam.serviceAccountOpenIdTokenCreator --format=json

Windows (PowerShell)

gcloud iam service-accounts add-iam-policy-binding PRIV_SA `
    --member=user:CALLER_ACCOUNT --role=roles/iam.serviceAccountOpenIdTokenCreator --format=json

Windows (cmd.exe)

gcloud iam service-accounts add-iam-policy-binding PRIV_SA ^
    --member=user:CALLER_ACCOUNT --role=roles/iam.serviceAccountOpenIdTokenCreator --format=json

You should receive a response similar to the following:

Updated IAM policy for serviceAccount [PRIV_SA].
{
  "bindings": [
    {
      "members": [
        "user:CALLER_ACCOUNT"
      ],
      "role": "roles/iam.serviceAccountOpenIdTokenCreator"
    }
  ],
  "etag": "BwX1ZbefjXU=",
  "version": 1
}

REST

  1. Read the allow policy for PRIV_SA:

    The serviceAccounts.getIamPolicy method gets a service account's allow policy.

    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.
    • PRIV_SA: The email address of the privilege-bearing service account for which the short-lived token is created.
    • POLICY_VERSION: The policy version to be returned. Requests should specify the most recent policy version, which is policy version 3. See Specifying a policy version when getting a policy for details.

    HTTP method and URL: 

    POST https://iam.googleapis.com/v1/projects/PROJECT_ID/serviceAccounts/PRIV_SA:getIamPolicy

    Request JSON body: 

    {
  "options": {
    "requestedPolicyVersion": POLICY_VERSION
  }
}

    To send your request, expand one of these options:

    You should receive a JSON response similar to the following:

    {
  "version": 1,
  "etag": "BwWKmjvelug=",
  "bindings": [
    {
      "role": "roles/serviceAccountAdmin",
      "members": [
        "user:admin@example.com"
      ]
    }
  ]
}

    If you have not granted any roles on the service account, the response contains only an etag value. Include that etag value in the next step.

  2. Modify the allow policy to grant CALLER_ACCOUNT the Service Account OpenID Connect Identity Token Creator role ( roles/iam.serviceAccountOpenIdTokenCreator).

    For example, to modify the sample response from the previous step, add the following: 

    {
  "version": 1,
  "etag": "BwWKmjvelug=",
  "bindings": [
    {
      "role": "roles/serviceAccountAdmin",
      "members": [
        "user:admin@example.com"
      ]
    },
    {
      "role": "roles/iam.serviceAccountOpenIdTokenCreator",
      "members": [
        "user:CALLER_ACCOUNT"
      ]
    }
  ]
}

  3. Write the updated allow policy:

    The serviceAccounts.setIamPolicy method sets an updated allow policy for 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.
    • PRIV_SA: The email address of the privilege-bearing service account for which the short-lived token is created.
    • POLICY_VERSION: The policy version to be returned. Requests should specify the most recent policy version, which is policy version 3. See Specifying a policy version when getting a policy for details.

    • POLICY: A JSON representation of the policy that you want to set. For more information about the format of a policy, see the Policy reference.

      For example, to set the allow policy shown in the previous step, replace POLICY with the following, where CALLER_ACCOUNT is the user account creating the short-lived token:

      {
  "version": 1,
  "etag": "BwWKmjvelug=",
  "bindings": [
    {
      "role": "roles/serviceAccountAdmin",
      "members": [
        "user:admin@example.com"
      ]
    },
    {
      "role": "roles/iam.serviceAccountOpenIdTokenCreator",
      "members": [
        "user:CALLER_ACCOUNT"
      ]
    }
  ]
}

    HTTP method and URL: 

    POST https://iam.googleapis.com/v1/projects/PROJECT_ID/serviceAccounts/PRIV_SA

    Request JSON body: 

    {
  "policy": POLICY
}

    To send your request, expand one of these options:

    The response contains the updated allow policy.

Generate the ID token

You can generate an OpenID Connect (OIDC) ID token by using the gcloud CLI, the REST API, or the Cloud Client Libraries and Google API Client Libraries.

The samples below are designed to be used in a local development environment; the caller must be represented by a user account, rather than a service account.

OIDC ID tokens are valid for 1 hour (3,600 seconds).

Generate a Google-signed OIDC ID token for the privilege-bearing service account:

gcloud

  1. Log in to the Google Cloud CLI as the caller Google Account.

    gcloud auth login CALLER_ACCOUNT

  2. Impersonate the privilege-bearing service account to generate the token.

    The gcloud auth print-identity-token command generates an OIDC ID token for a service account.

    Before using any of the command data below, make the following replacements:

    • PRIV_SA: The email address of the privilege-bearing service account for which the short-lived token is created.
    • AUDIENCE_NAME: The audience for the token, usually the URL of the application or service that the token will be used to access.

        • Execute the following command:

        Linux, macOS, or Cloud Shell

        gcloud auth print-identity-token --impersonate-service-account=PRIV_SA --audiences="AUDIENCE_NAME"

        Windows (PowerShell)

        gcloud auth print-identity-token --impersonate-service-account=PRIV_SA --audiences="AUDIENCE_NAME"

        Windows (cmd.exe)

        gcloud auth print-identity-token --impersonate-service-account=PRIV_SA --audiences="AUDIENCE_NAME"

        You should receive a response similar to the following:

        WARNING: This command is using service account impersonation. All API calls will be executed as
[my-sa@my-project.iam.gserviceaccount.com].
eyJhbGciOiJSUzI1NiIsImtpZDNhMDg4ZDRmZmMjJkYTVmZTM5MDZjY2MiLCJ0eXAiOiJKV1QifQ.eyJhdWQiOiJ3d3cuZXhhbXBsJhenAiOiIxMTYzwNDYyMDk0ODIiLCJleHAiOjE2NTQ4ODU0MzEsImlhdCI6MTY1NDg4MTgzMSwiaXN6Ly9hY2NvdW50cy5nb29nbGUuY29tIiwic3ViIMDQ2MjA5NDgyIn0.F7mu8IHj5VQdu7ItFrnYAKyGd7YqXuOP_rFLc98q8BaFBycAF1zAQnSnwqnSUXba0UK9PDT_-IOry68qLwBObz4XlX9lk0ehpN0O0W9FcFToKLB6wefXXPd4h7xtuPe5KzmpSOqj2Qqv34HriGw00Nqd-oGSgNY_lZ4wGEf4rT4oQa_kEcrY57Q2G6pwd769BhgeFwoLi5aK_Cv2kvf_zfMszC-xlkP9zwWQ8XinJBwe-qcQBa4NTgrbueNtXsEjccBS366zmw

REST

The Service Account Credentials API's serviceAccounts.generateIdToken method generates an OIDC ID token for a service account.

Before using any of the request data, make the following replacements:

  • PRIV_SA: The email address of the privilege-bearing service account for which the short-lived token is created.
  • AUDIENCE_NAME: The audience for the token, usually the URL of the application or service that the token will be used to access.

HTTP method and URL: 

POST https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/PRIV_SA:generateIdToken

Request JSON body: 

{
  "audience": "AUDIENCE_NAME",
  "includeEmail": "true"
}

To send your request, expand one of these options:

If the generateId request was successful, the response body contains an ID token that is valid for 1 hour. The token can then be used to authenticate a request on behalf of the service account: 

{
  "token": "eyJ0eXAi...NiJ9"
}

Create a self-signed JSON Web Token (JWT)

Self-signed JSON Web Tokens (JWTs) are useful in a variety of scenarios:

  • Authenticating to an API deployed with API Gateway.
  • Authenticating a call to a Google API as described in Google's Authentication Guide.
  • Securely communicating between your own applications. In this scenario, one application can sign a token that can be verified by another application for authentication purposes.
  • Treating a service account as an identity provider by signing a JWT that contains arbitrary claims about a user, account, or device.

To create a JWT, complete these tasks:

Provide required permissions

A direct request involves two identities: the caller, and the privilege-bearing service account for which the credential is created. How you set up the permissions depends on whether the caller is using a service account or user credentials.

If you want to run a REST or gcloud CLI command on this page in a local development environment, the caller can be represented by user credentials. For automated workloads, such as an application running on Compute Engine, the caller must be represented by a service account.

Service account

When the calling application uses a service account as its identity, the following principals are involved:

  • Caller service account (CALLER_SA)

    This service account represents the calling application, which issues the request for the short-lived credentials.

  • Privilege-bearing service account (PRIV_SA)

    This service account is granted the IAM roles needed for the short-lived token. This is the service account for which the short-lived token is created.

To give CALLER_SA permissions to create short-lived credentials for PRIV_SA, you grant CALLER_SA the Service Account Token Creator role (roles/iam.serviceAccountTokenCreator) on PRIV_SA.

Grant the required role on PRIV_SA:

Console

  1. In the Google Cloud console, go to the Service Accounts page.

    Go to Service Accounts

  2. Select a project.
  3. Click the email address of the privilege-bearing service account, PRIV_SA.
  4. Click the Permissions tab.
  5. Under Principals with access to this service account, click Grant Access.

  6. Enter the email address of the caller service account, CALLER_SA.

    For example, demo@my-project.iam.gserviceaccount.com.

  7. Select the Service Account Token Creator role (roles/iam.serviceAccountTokenCreator).
  8. Click Save to grant the role to the service account.

gcloud

The gcloud iam service-accounts add-iam-policy-binding command grants a role on a service account.

Before using any of the command data below, make the following replacements:

  • PRIV_SA: The email address of the privilege-bearing service account for which the token is generated.
  • CALLER_SA: The email address of the service account representing the application that is requesting the short-lived token.

Execute the following command:

Linux, macOS, or Cloud Shell

gcloud iam service-accounts add-iam-policy-binding PRIV_SA \
    --member=serviceAccount:CALLER_SA --role=roles/iam.serviceAccountTokenCreator --format=json

Windows (PowerShell)

gcloud iam service-accounts add-iam-policy-binding PRIV_SA `
    --member=serviceAccount:CALLER_SA --role=roles/iam.serviceAccountTokenCreator --format=json

Windows (cmd.exe)

gcloud iam service-accounts add-iam-policy-binding PRIV_SA ^
    --member=serviceAccount:CALLER_SA --role=roles/iam.serviceAccountTokenCreator --format=json

You should receive a response similar to the following:

Updated IAM policy for serviceAccount [PRIV_SA].
{
  "bindings": [
    {
      "members": [
        "serviceAccount:CALLER_SA"
      ],
      "role": "roles/iam.serviceAccountTokenCreator"
    }
  ],
  "etag": "BwXhCB4eyjY=",
  "version": 1
}

REST

  1. Read the allow policy for PRIV_SA:

    The serviceAccounts.getIamPolicy method gets a service account's allow policy.

    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.
    • PRIV_SA: The email address of the privilege-bearing service account for which the short-lived token is created.
    • POLICY_VERSION: The policy version to be returned. Requests should specify the most recent policy version, which is policy version 3. See Specifying a policy version when getting a policy for details.

    HTTP method and URL: 

    POST https://iam.googleapis.com/v1/projects/PROJECT_ID/serviceAccounts/PRIV_SA:getIamPolicy

    Request JSON body: 

    {
  "options": {
    "requestedPolicyVersion": POLICY_VERSION
  }
}

    To send your request, expand one of these options:

    You should receive a JSON response similar to the following:

    {
  "version": 1,
  "etag": "BwWKmjvelug=",
  "bindings": [
    {
      "role": "roles/serviceAccountAdmin",
      "members": [
        "user:admin@example.com"
      ]
    }
  ]
}

    If you have not granted any roles on the service account, the response contains only an etag value. Include that etag value in the next step.

  2. Modify the allow policy to grant CALLER_SA the Service Account Token Creator role (roles/iam.serviceAccountTokenCreator).

    For example, to modify the sample response from the previous step, add the following: 

      {
    "version": 1,
    "etag": "BwWKmjvelug=",
    "bindings": [
      {
        "role": "roles/serviceAccountAdmin",
        "members": [
          "user:admin@example.com"
        ]
      },
      {
        "role": "roles/iam.serviceAccountTokenCreator",
        "members": [
          "serviceAccount:CALLER_SA"
        ]
      }
    ]
  }

  3. Write the updated allow policy:

    The serviceAccounts.setIamPolicy method sets an updated allow policy for 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.
    • PRIV_SA: The email address of the privilege-bearing service account for which the short-lived token is created.
    • POLICY_VERSION: The policy version to be returned. Requests should specify the most recent policy version, which is policy version 3. See Specifying a policy version when getting a policy for details.

    • POLICY: A JSON representation of the policy that you want to set. For more information about the format of a policy, see the Policy reference.

      For example, to set the allow policy shown in the previous step, replace POLICY with the following, where CALLER_SA is the service account creating the short-lived token:

      {
  "version": 1,
  "etag": "BwWKmjvelug=",
  "bindings": [
    {
      "role": "roles/serviceAccountAdmin",
      "members": [
        "user:admin@example.com"
      ]
    },
    {
      "role": "roles/iam.serviceAccountTokenCreator",
      "members": [
        "serviceAccount:CALLER_SA"
      ]
    }
  ]
}

    HTTP method and URL: 

    POST https://iam.googleapis.com/v1/projects/PROJECT_ID/serviceAccounts/PRIV_SA

    Request JSON body: 

    {
  "policy": POLICY
}

    To send your request, expand one of these options:

    The response contains the updated allow policy.

User credentials

When you want to use the Google Cloud CLI to generate short-lived tokens, or you want to generate short-lived tokens from a local development environment, you can use a user account to generate the tokens. Often, you can use your own Google Account.

When you use a user account to generate short-lived tokens, the following identities are involved:

  • Caller Google Account (CALLER_ACCOUNT)

    This user account is used to generate short-lived credentials for the privilege-bearing service account.

  • Privilege-bearing service account (PRIV_SA)

    This service account is granted the IAM roles needed for the short-lived token. This is the service account for which the short-lived token is created.

To enable CALLER_ACCOUNT to create short-lived credentials for PRIV_SA, you grant CALLER_ACCOUNT the Service Account Token Creator role (roles/iam.serviceAccountTokenCreator) on PRIV_SA.

Grant the required role on PRIV_SA:

Console

  1. In the Google Cloud console, go to the Service Accounts page.

    Go to Service Accounts

  2. Select a project.
  3. Click the email address of the privilege-bearing service account, PRIV_SA.
  4. Click the Permissions tab.
  5. Under Principals with access to this service account, click Grant Access.

  6. Enter the email address of the caller Google Account, CALLER_ACCOUNT.

    For example, username@google.com.

  7. Select the Service Account Token Creator role (roles/iam.serviceAccountTokenCreator).
  8. Click Save to grant the role to the user account.

gcloud

The gcloud iam service-accounts add-iam-policy-binding command grants a role on a service account.

Before using any of the command data below, make the following replacements:

  • PRIV_SA: The email address of the privilege-bearing service account for which the token is generated.
  • CALLER_ACCOUNT: The email address of the user account being used to request the short-lived token.

Execute the following command:

Linux, macOS, or Cloud Shell

gcloud iam service-accounts add-iam-policy-binding PRIV_SA \
    --member=user:CALLER_ACCOUNT --role=roles/iam.serviceAccountTokenCreator --format=json

Windows (PowerShell)

gcloud iam service-accounts add-iam-policy-binding PRIV_SA `
    --member=user:CALLER_ACCOUNT --role=roles/iam.serviceAccountTokenCreator --format=json

Windows (cmd.exe)

gcloud iam service-accounts add-iam-policy-binding PRIV_SA ^
    --member=user:CALLER_ACCOUNT --role=roles/iam.serviceAccountTokenCreator --format=json

You should receive a response similar to the following:

Updated IAM policy for serviceAccount [PRIV_SA].
{
  "bindings": [
    {
      "members": [
        "user:CALLER_ACCOUNT"
      ],
      "role": "roles/iam.serviceAccountTokenCreator"
    }
  ],
  "etag": "BwX1ZbefjXU=",
  "version": 1
}

REST

  1. Read the allow policy for PRIV_SA:

    The serviceAccounts.getIamPolicy method gets a service account's allow policy.

    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.
    • PRIV_SA: The email address of the privilege-bearing service account for which the short-lived token is created.
    • POLICY_VERSION: The policy version to be returned. Requests should specify the most recent policy version, which is policy version 3. See Specifying a policy version when getting a policy for details.

    HTTP method and URL: 

    POST https://iam.googleapis.com/v1/projects/PROJECT_ID/serviceAccounts/PRIV_SA:getIamPolicy

    Request JSON body: 

    {
  "options": {
    "requestedPolicyVersion": POLICY_VERSION
  }
}

    To send your request, expand one of these options:

    You should receive a JSON response similar to the following:

    {
  "version": 1,
  "etag": "BwWKmjvelug=",
  "bindings": [
    {
      "role": "roles/serviceAccountAdmin",
      "members": [
        "user:admin@example.com"
      ]
    }
  ]
}

    If you have not granted any roles on the service account, the response contains only an etag value. Include that etag value in the next step.

  2. Modify the allow policy to grant CALLER_ACCOUNT the Service Account Token Creator role ( roles/iam.serviceAccountTokenCreator).

    For example, to modify the sample response from the previous step, add the following: 

    {
  "version": 1,
  "etag": "BwWKmjvelug=",
  "bindings": [
    {
      "role": "roles/serviceAccountAdmin",
      "members": [
        "user:admin@example.com"
      ]
    },
    {
      "role": "roles/iam.serviceAccountTokenCreator",
      "members": [
        "user:CALLER_ACCOUNT"
      ]
    }
  ]
}

  3. Write the updated allow policy:

    The serviceAccounts.setIamPolicy method sets an updated allow policy for 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.
    • PRIV_SA: The email address of the privilege-bearing service account for which the short-lived token is created.
    • POLICY_VERSION: The policy version to be returned. Requests should specify the most recent policy version, which is policy version 3. See Specifying a policy version when getting a policy for details.

    • POLICY: A JSON representation of the policy that you want to set. For more information about the format of a policy, see the Policy reference.

      For example, to set the allow policy shown in the previous step, replace POLICY with the following, where CALLER_ACCOUNT is the user account creating the short-lived token:

      {
  "version": 1,
  "etag": "BwWKmjvelug=",
  "bindings": [
    {
      "role": "roles/serviceAccountAdmin",
      "members": [
        "user:admin@example.com"
      ]
    },
    {
      "role": "roles/iam.serviceAccountTokenCreator",
      "members": [
        "user:CALLER_ACCOUNT"
      ]
    }
  ]
}

    HTTP method and URL: 

    POST https://iam.googleapis.com/v1/projects/PROJECT_ID/serviceAccounts/PRIV_SA

    Request JSON body: 

    {
  "policy": POLICY
}

    To send your request, expand one of these options:

    The response contains the updated allow policy.

Generate the JWT

Generate a self-signed JWT:

REST

The Service Account Credentials API's serviceAccounts.signJwt method signs a JWT using a service account's system-managed private key.

Before using any of the request data, make the following replacements:

  • PRIV_SA: The email address of the privilege-bearing service account for which the short-lived token is created.

  • JWT_PAYLOAD: The JWT payload to sign, which is a JSON object that contains a JWT Claims Set. Include the claims that are necessary for your desired use case and to meet the validation requirements for the service you are calling. If you are calling a Google API, see Google's Authentication Guide for claim requirements.

    The exp (expiration time) claim must be no more than 12 hours in the future. If you are calling a Google API, the exp claim must be set no more than 1 hour in the future.

    The following example payload contains claims to call a Google API, where EXP is an integer timestamp representing the expiration time: 

    { \"iss\": \"PRIV_SA", \"sub\": \"PRIV_SA\", \"aud\": \"https://firestore.googleapis.com/\", \"iat\": 1529350000, \"exp\": EXP }

HTTP method and URL: 

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

Request JSON body: 

{
  "payload": "JWT_PAYLOAD"
}

To send your request, expand one of these options:

If the signJwt request was successful, the response body contains a signed JWT and the signing key ID that was used to sign the JWT. You can use the signedJwt value as a bearer token to directly authenticate a request on behalf of the service account. The token is valid up to the expiration time specified in the request: 

{
  "keyId": "42ba1e...fc0a",
  "signedJwt": "eyJ0eXAi...NiJ9"
}

Create a self-signed binary object (blob)

Self-signed binary objects, or blobs, are used to transmit binary data in such a way that the originator of the data is known (because the blob is self-signed). Blobs can be used to create signatures, a Cloud Storage object required for various authentication flows including signed URLs. For information about signatures, see the Cloud Storage documentation.

To create a self-signed binary object, complete these tasks:

Provide required permissions

A direct request involves two identities: the caller, and the privilege-bearing service account for which the credential is created. How you set up the permissions depends on whether the caller is using a service account or user credentials.

If you want to run a REST or gcloud CLI command on this page in a local development environment, the caller can be represented by user credentials. For automated workloads, such as an application running on Compute Engine, the caller must be represented by a service account.

Service account

When the calling application uses a service account as its identity, the following principals are involved:

  • Caller service account (CALLER_SA)

    This service account represents the calling application, which issues the request for the short-lived credentials.

  • Privilege-bearing service account (PRIV_SA)

    This service account is granted the IAM roles needed for the short-lived token. This is the service account for which the short-lived token is created.

To give CALLER_SA permissions to create short-lived credentials for PRIV_SA, you grant CALLER_SA the Service Account Token Creator role (roles/iam.serviceAccountTokenCreator) on PRIV_SA.

Grant the required role on PRIV_SA:

Console

  1. In the Google Cloud console, go to the Service Accounts page.

    Go to Service Accounts

  2. Select a project.
  3. Click the email address of the privilege-bearing service account, PRIV_SA.
  4. Click the Permissions tab.
  5. Under Principals with access to this service account, click Grant Access.

  6. Enter the email address of the caller service account, CALLER_SA.

    For example, demo@my-project.iam.gserviceaccount.com.

  7. Select the Service Account Token Creator role (roles/iam.serviceAccountTokenCreator).
  8. Click Save to grant the role to the service account.

gcloud

The gcloud iam service-accounts add-iam-policy-binding command grants a role on a service account.

Before using any of the command data below, make the following replacements:

  • PRIV_SA: The email address of the privilege-bearing service account for which the token is generated.
  • CALLER_SA: The email address of the service account representing the application that is requesting the short-lived token.

Execute the following command:

Linux, macOS, or Cloud Shell

gcloud iam service-accounts add-iam-policy-binding PRIV_SA \
    --member=serviceAccount:CALLER_SA --role=roles/iam.serviceAccountTokenCreator --format=json

Windows (PowerShell)

gcloud iam service-accounts add-iam-policy-binding PRIV_SA `
    --member=serviceAccount:CALLER_SA --role=roles/iam.serviceAccountTokenCreator --format=json

Windows (cmd.exe)

gcloud iam service-accounts add-iam-policy-binding PRIV_SA ^
    --member=serviceAccount:CALLER_SA --role=roles/iam.serviceAccountTokenCreator --format=json

You should receive a response similar to the following:

Updated IAM policy for serviceAccount [PRIV_SA].
{
  "bindings": [
    {
      "members": [
        "serviceAccount:CALLER_SA"
      ],
      "role": "roles/iam.serviceAccountTokenCreator"
    }
  ],
  "etag": "BwXhCB4eyjY=",
  "version": 1
}

REST

  1. Read the allow policy for PRIV_SA:

    The serviceAccounts.getIamPolicy method gets a service account's allow policy.

    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.
    • PRIV_SA: The email address of the privilege-bearing service account for which the short-lived token is created.
    • POLICY_VERSION: The policy version to be returned. Requests should specify the most recent policy version, which is policy version 3. See Specifying a policy version when getting a policy for details.

    HTTP method and URL: 

    POST https://iam.googleapis.com/v1/projects/PROJECT_ID/serviceAccounts/PRIV_SA:getIamPolicy

    Request JSON body: 

    {
  "options": {
    "requestedPolicyVersion": POLICY_VERSION
  }
}

    To send your request, expand one of these options:

    You should receive a JSON response similar to the following:

    {
  "version": 1,
  "etag": "BwWKmjvelug=",
  "bindings": [
    {
      "role": "roles/serviceAccountAdmin",
      "members": [
        "user:admin@example.com"
      ]
    }
  ]
}

    If you have not granted any roles on the service account, the response contains only an etag value. Include that etag value in the next step.

  2. Modify the allow policy to grant CALLER_SA the Service Account Token Creator role (roles/iam.serviceAccountTokenCreator).

    For example, to modify the sample response from the previous step, add the following: 

      {
    "version": 1,
    "etag": "BwWKmjvelug=",
    "bindings": [
      {
        "role": "roles/serviceAccountAdmin",
        "members": [
          "user:admin@example.com"
        ]
      },
      {
        "role": "roles/iam.serviceAccountTokenCreator",
        "members": [
          "serviceAccount:CALLER_SA"
        ]
      }
    ]
  }

  3. Write the updated allow policy:

    The serviceAccounts.setIamPolicy method sets an updated allow policy for 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.
    • PRIV_SA: The email address of the privilege-bearing service account for which the short-lived token is created.
    • POLICY_VERSION: The policy version to be returned. Requests should specify the most recent policy version, which is policy version 3. See Specifying a policy version when getting a policy for details.

    • POLICY: A JSON representation of the policy that you want to set. For more information about the format of a policy, see the Policy reference.

      For example, to set the allow policy shown in the previous step, replace POLICY with the following, where CALLER_SA is the service account creating the short-lived token:

      {
  "version": 1,
  "etag": "BwWKmjvelug=",
  "bindings": [
    {
      "role": "roles/serviceAccountAdmin",
      "members": [
        "user:admin@example.com"
      ]
    },
    {
      "role": "roles/iam.serviceAccountTokenCreator",
      "members": [
        "serviceAccount:CALLER_SA"
      ]
    }
  ]
}

    HTTP method and URL: 

    POST https://iam.googleapis.com/v1/projects/PROJECT_ID/serviceAccounts/PRIV_SA

    Request JSON body: 

    {
  "policy": POLICY
}

    To send your request, expand one of these options:

    The response contains the updated allow policy.

User credentials

When you want to use the Google Cloud CLI to generate short-lived tokens, or you want to generate short-lived tokens from a local development environment, you can use a user account to generate the tokens. Often, you can use your own Google Account.

When you use a user account to generate short-lived tokens, the following identities are involved:

  • Caller Google Account (CALLER_ACCOUNT)

    This user account is used to generate short-lived credentials for the privilege-bearing service account.

  • Privilege-bearing service account (PRIV_SA)

    This service account is granted the IAM roles needed for the short-lived token. This is the service account for which the short-lived token is created.

To enable CALLER_ACCOUNT to create short-lived credentials for PRIV_SA, you grant CALLER_ACCOUNT the Service Account Token Creator role (roles/iam.serviceAccountTokenCreator) on PRIV_SA.

Grant the required role on PRIV_SA:

Console

  1. In the Google Cloud console, go to the Service Accounts page.

    Go to Service Accounts

  2. Select a project.
  3. Click the email address of the privilege-bearing service account, PRIV_SA.
  4. Click the Permissions tab.
  5. Under Principals with access to this service account, click Grant Access.

  6. Enter the email address of the caller Google Account, CALLER_ACCOUNT.

    For example, username@google.com.

  7. Select the Service Account Token Creator role (roles/iam.serviceAccountTokenCreator).
  8. Click Save to grant the role to the user account.

gcloud

The gcloud iam service-accounts add-iam-policy-binding command grants a role on a service account.

Before using any of the command data below, make the following replacements:

  • PRIV_SA: The email address of the privilege-bearing service account for which the token is generated.
  • CALLER_ACCOUNT: The email address of the user account being used to request the short-lived token.

Execute the following command:

Linux, macOS, or Cloud Shell

gcloud iam service-accounts add-iam-policy-binding PRIV_SA \
    --member=user:CALLER_ACCOUNT --role=roles/iam.serviceAccountTokenCreator --format=json

Windows (PowerShell)

gcloud iam service-accounts add-iam-policy-binding PRIV_SA `
    --member=user:CALLER_ACCOUNT --role=roles/iam.serviceAccountTokenCreator --format=json

Windows (cmd.exe)

gcloud iam service-accounts add-iam-policy-binding PRIV_SA ^
    --member=user:CALLER_ACCOUNT --role=roles/iam.serviceAccountTokenCreator --format=json

You should receive a response similar to the following:

Updated IAM policy for serviceAccount [PRIV_SA].
{
  "bindings": [
    {
      "members": [
        "user:CALLER_ACCOUNT"
      ],
      "role": "roles/iam.serviceAccountTokenCreator"
    }
  ],
  "etag": "BwX1ZbefjXU=",
  "version": 1
}

REST

  1. Read the allow policy for PRIV_SA:

    The serviceAccounts.getIamPolicy method gets a service account's allow policy.

    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.
    • PRIV_SA: The email address of the privilege-bearing service account for which the short-lived token is created.
    • POLICY_VERSION: The policy version to be returned. Requests should specify the most recent policy version, which is policy version 3. See Specifying a policy version when getting a policy for details.

    HTTP method and URL: 

    POST https://iam.googleapis.com/v1/projects/PROJECT_ID/serviceAccounts/PRIV_SA:getIamPolicy

    Request JSON body: 

    {
  "options": {
    "requestedPolicyVersion": POLICY_VERSION
  }
}

    To send your request, expand one of these options:

    You should receive a JSON response similar to the following:

    {
  "version": 1,
  "etag": "BwWKmjvelug=",
  "bindings": [
    {
      "role": "roles/serviceAccountAdmin",
      "members": [
        "user:admin@example.com"
      ]
    }
  ]
}

    If you have not granted any roles on the service account, the response contains only an etag value. Include that etag value in the next step.

  2. Modify the allow policy to grant CALLER_ACCOUNT the Service Account Token Creator role ( roles/iam.serviceAccountTokenCreator).

    For example, to modify the sample response from the previous step, add the following: 

    {
  "version": 1,
  "etag": "BwWKmjvelug=",
  "bindings": [
    {
      "role": "roles/serviceAccountAdmin",
      "members": [
        "user:admin@example.com"
      ]
    },
    {
      "role": "roles/iam.serviceAccountTokenCreator",
      "members": [
        "user:CALLER_ACCOUNT"
      ]
    }
  ]
}

  3. Write the updated allow policy:

    The serviceAccounts.setIamPolicy method sets an updated allow policy for 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.
    • PRIV_SA: The email address of the privilege-bearing service account for which the short-lived token is created.
    • POLICY_VERSION: The policy version to be returned. Requests should specify the most recent policy version, which is policy version 3. See Specifying a policy version when getting a policy for details.

    • POLICY: A JSON representation of the policy that you want to set. For more information about the format of a policy, see the Policy reference.

      For example, to set the allow policy shown in the previous step, replace POLICY with the following, where CALLER_ACCOUNT is the user account creating the short-lived token:

      {
  "version": 1,
  "etag": "BwWKmjvelug=",
  "bindings": [
    {
      "role": "roles/serviceAccountAdmin",
      "members": [
        "user:admin@example.com"
      ]
    },
    {
      "role": "roles/iam.serviceAccountTokenCreator",
      "members": [
        "user:CALLER_ACCOUNT"
      ]
    }
  ]
}

    HTTP method and URL: 

    POST https://iam.googleapis.com/v1/projects/PROJECT_ID/serviceAccounts/PRIV_SA

    Request JSON body: 

    {
  "policy": POLICY
}

    To send your request, expand one of these options:

    The response contains the updated allow policy.

Generate the self-signed blob

Generate a self-signed blob for the privilege-bearing service account:

REST

The Service Account Credentials API's serviceAccounts.signBlob method signs a blob using a service account's system-managed private key.

Before using any of the request data, make the following replacements:

  • PRIV_SA: The email address of the privilege-bearing service account for which the short-lived token is created.
  • BLOB_PAYLOAD: A base64-encoded string of bytes. For example, VGhlIHF1aWNrIGJyb3duIGZveCBqdW1wZWQgb3ZlciB0aGUgbGF6eSBkb2cu.

HTTP method and URL: 

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

Request JSON body: 

{
  "payload": "BLOB_PAYLOAD"
}

To send your request, expand one of these options:

If the signBlob request was successful, the response body contains a signed blob and the signing key ID that was used to sign the blob. You can use the signedBlob value as a bearer token to directly authenticate a request on behalf of the service account. The token is valid until the service account's system-managed private key expires. This key's ID is the value of the keyId field in the response. 

{
  "keyId": "42ba1e...fc0a",
  "signedBlob": "eyJ0eXAi...NiJ9"
}