Managing service account impersonation

This page describes how to allow members and resources to impersonate, or act as, an Identity and Access Management (IAM) service account. It also explains how to see which members are able to impersonate a given IAM service account.

Before you begin

Make sure you understand how service accounts work in IAM.

Allowing members to impersonate service accounts

There are several predefined roles that allow a member to impersonate a service account:

  • Service Account User (roles/iam.serviceAccountUser): Allows members to indirectly access all the resources that the service account can access. For example, if a member has the Service Account User role on a service account, and the service account has the Cloud SQL Admin role (roles/cloudsql.admin) on the project, then the member can impersonate the service account to create a Cloud SQL instance.

    This role also allows members to bind a service account to a resource, as explained on this page.

  • Service Account Token Creator (roles/iam.serviceAccountTokenCreator): Allows members to impersonate service accounts to create OAuth 2.0 access tokens, sign JSON Web Tokens (JWTs), and sign binary blobs so that they can be used for authentication. See Creating short-lived service account credentials for details.

  • Workload Identity User (roles/iam.workloadIdentityUser): Allows members to impersonate service accounts from GKE workloads. This role cannot be granted on individual service accounts, but can be granted on a project, folder, or organization.

Alternatively, you can grant a different predefined role, or a custom role, that includes the same permissions as these roles.

The following sections describe how to grant these roles on projects, folders, and organizations, and how to grant them on individual service accounts. Choose the level based on the amount of access that you want to grant:

Allowing a member to impersonate multiple service accounts

To allow a member to impersonate all service accounts created in a project, folder, or organization, grant a role on the project, folder, or organization:

Console

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

    Go to the IAM page

  2. From the project selector at the top of the page, choose the project, folder, or organization on which you want to grant the role.

  3. Click Add.

  4. Enter your member's email address.

  5. Select a role that allows the member to impersonate service accounts. See the list of roles for impersonating service accounts.

  6. Click Save.

gcloud

To grant a member a role that allows them to impersonate a service account, modify the IAM policy for your project, folder, or organization.

  1. Read the IAM policy for the resource:

    gcloud resource get-iam-policy resource-id \
        --format=json > policy.json
    

    Replace the following values:

    • resource: The type of the resource that you want to set the policy on. This value should be one of the following: projects, resource-manager folders, or organizations.
    • resource-id: The ID of the resource that you want to set the policy on.

    The command stores the resource's policy in a policy.json file.

    If a policy is already set on the resource, the policy.json file is similar to the following:

    {
      "bindings": [
        {
          "members": [
            "user:hollis@example.com"
          ],
          "role": "roles/owner"
        }
      ],
      "etag": "BwUqLaVeua8=",
      "version": 1
    }
    

    If there is no policy on the resource, the policy.json file only contains the default etag.

    When there is no existing policy, manually create the policy using the JSON in the following steps as a template.

  2. Modify the policy to grant the appropriate roles to your members. To grant a role, do one of the following:

    • If a binding for the role does not exist, add an object to the bindings array that indicates the role you want to grant and the member you want to grant it to.
    • If a binding already exists for the role, add the new member to the list of existing members. If your policy includes conditional role bindings, also ensure that the binding has the appropriate conditions before adding the member.

    If the bindings array doesn't already exist, you can create it.

    Example

    To grant the Service Account User role (roles/iam.serviceAccountUser) to robin@example.com, change the example shown in the previous step as follows:

    {
      "bindings": [
        {
          "role": "roles/iam.serviceAccountUser",
          "members": [
            "user:robin@example.com"
          ]
        },
        {
          "role": "roles/owner",
          "members": [
            "user:hollis@example.com"
          ]
        }
      ],
      "etag": "BwUqLaVeua8=",
      "version": 1
    }
    
  3. Write the updated policy:

    gcloud resource set-iam-policy resource-id \
        policy-file
    

    Replace the following values:

    • resource: The type of the resource that you want to set the policy on. This value should be one of the following: projects, resource-manager folders, or organizations.
    • resource-id: The ID of the resource that you want to set the policy on.
    • policy-file: The path to the file that contains the updated policy.

    The command prints the updated policy with an updated etag value.

REST API

To grant a role using the Resource Manager REST API, you need to read the current IAM policy for your project, folder, or organization; modify the policy to grant the desired roles; and then write the updated policy.

Read the IAM policy for the resource.

The Resource Manager API's getIamPolicy method gets a project, folder, or organization's IAM policy.

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

  • api-version: The API version to use. For projects and organizations, use v1. For folders, use v2.
  • resource-type: The resource type whose policy you want to manage. Use the value projects, folders, or organizations.
  • resource-id: Your Google Cloud project, organization, or folder ID.
  • 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://cloudresourcemanager.googleapis.com/api-version/resource-type/resource-id: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/owner",
      "members": [
        "user:owner@example.com"
      ]
    }
  ]
}

When there is no existing policy, the response contains only the default etag. If you get this response, add a version field, set to 3, and a bindings field, set to an empty array.

Modify the policy to grant the appropriate roles to your members.

To grant a role, do one of the following:

  • If a binding for the role does not exist, add an object to the bindings array that indicates the role you want to grant and the member you want to grant it to.
  • If a binding already exists for the role, add the new member to the list of existing members.

Example:

To grant the Service Account User role (roles/iam.serviceAccountUser) to robin@example.com, change the example shown in the previous step as follows:

{
  "version": 1,
  "etag": "BwUqLaVeua8=",
  "bindings": [
    {
      "role": "roles/iam.serviceAccountUser",
      "members": [
        "user:robin@example.com"
      ]
    },
    {
      "role": "roles/owner",
      "members": [
        "user:owner@example.com"
      ]
    }
  ]
}

Write the updated policy.

The Resource Manager API's setIamPolicy method sets the policy in the request as the new IAM policy for the project, folder, or organization.

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

  • api-version: The API version to use. For projects and organizations, use v1. For folders, use v2.
  • resource-type: The resource type whose policy you want to manage. Use the value projects, folders, or organizations.
  • resource-id: Your Google Cloud project, organization, or folder ID.
  • 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 policy shown in the previous step, replace policy with the following:

    {
      "version": 1,
      "etag": "BwUqLaVeua8=",
      "bindings": [
        {
          "role": "roles/iam.serviceAccountUser",
          "members": [
            "user:robin@example.com"
          ]
        },
        {
          "role": "roles/owner",
          "members": [
            "user:owner@example.com"
          ]
        }
      ]
    }
    

HTTP method and URL:

POST https://iam.googleapis.com/api-version/resource-type/resource-id:setIamPolicy

Request JSON body:

{
  "policy": policy
}

To send your request, expand one of these options:

The response contains the updated policy.

Allowing a member to impersonate a single service account

To allow a member to impersonate a single service account, grant a role on the service account:

Console

  1. In the Cloud Console, go to the Service Accounts page.

    Go to the Service Accounts page

  2. Click Select a project, choose a project, and click Open.

  3. Select a service account. If the info panel is not already visible, click Show info panel. The panel displays a list of roles that have been granted on the service account.

  4. Click Add member.

  5. Enter your member's email address.

  6. Select a role that gives the member permission to impersonate service accounts. See the list of roles for impersonating service accounts.

  7. Click Add to apply the role to the project member.

To grant roles on multiple service accounts, repeat these steps for each service account.

gcloud

To grant a member a role that allows them to impersonate a service account, modify the IAM policy for your service account.

  1. Use the service-accounts get-iam-policy command to read the current policy:

    gcloud iam service-accounts get-iam-policy sa-id \
        --format=json > policy.json
    

    Replace the following values:

    • sa-id: The ID of your service account. This can either be the service account's email address in the form sa-name@project-id.iam.gserviceaccount.com, or the service account's unique numeric ID.

    The command stores the service account's policy in a policy.json file.

    If a policy is already set on the service account, the policy.json file is similar to the following:

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

    If there is no policy set on the service account, the policy.json file only contains the default etag.

    When there is no existing policy, manually create the policy using the JSON in the following steps as a template.

  2. In a text editor, modify the bindings array in the policy.json file to grant the appropriate roles to your members. To grant a role, do one of the following:

    • If a binding for the role does not exist, add a new object to the bindings array that defines the role you want to grant and the member you want to grant it to.
    • If a binding already exists for the role, add the new member to the list of existing members. If your policy includes conditional role bindings, also ensure that the binding has the appropriate conditions before adding the member.

    If the bindings array doesn't already exist, you can create it.

    Example

    To grant the Service Account User role (roles/iam.serviceAccountUser) to robin@example.com, change the example shown in the previous step as follows:

    {
      "bindings": [
        {
          "role": "roles/iam.serviceAccountUser",
          "members": [
            "user:robin@example.com"
          ]
        },
        {
          "role": "roles/iam.serviceAccountAdmin",
          "members": [
            "user:hollis@example.com"
          ]
        }
      ],
      "etag": "BwUqLaVeua8=",
      "version": 1
    }
    
  3. Use the service-accounts set-iam-policy command to write the updated policy:

    gcloud iam service-accounts set-iam-policy sa-id \
        policy-file
    

    Replace the following values:

    • sa-id: The ID of your service account. This can either be the service account's email address in the form sa-name@project-id.iam.gserviceaccount.com, or the service account's unique numeric ID.
    • policy-file: The path to the file that contains the updated policy.

    The command prints the updated policy with an updated etag value.

REST API

To grant a role using the IAM REST API, you need to read the service account's current IAM policy, modify it to grant the desired roles, and then write the updated policy.

Read the service account's IAM policy.

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

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

  • project-id: Your Google Cloud project ID.
  • sa-id: The ID of your service account. This can either be the service account's email address in the form sa-name@project-id.iam.gserviceaccount.com, or the service account's unique numeric ID.

  • 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/sa-id: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"
      ]
    }
  ]
}

When there is no existing policy, the response contains only the default etag. If you get this response, add a version field, set to 3, and a bindings field, set to an empty array.

Modify the policy to grant the appropriate roles to your members.

In a text editor, modify the bindings array from the response body to grant the appropriate roles to your members. To grant a role, do one of the following:

  • If a binding for the role does not exist, add a new object to the bindings array that defines the role you want to grant and the member you want to grant it to.
  • If a binding already exists for the role, add the new member to the list of existing members.

Example:

To grant the Service Account User role (roles/iam.serviceAccountUser) to robin@example.com, change the example shown in the previous step as follows:

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

Write the updated policy.

The serviceAccounts.setIamPolicy method sets an updated IAM policy for the service account.

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

  • project-id: Your Google Cloud project ID.
  • sa-id: The ID of your service account. This can either be the service account's email address in the form sa-name@project-id.iam.gserviceaccount.com, or the service account's unique numeric ID.

  • 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 policy shown in the previous step, replace policy with the following:

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

HTTP method and URL:

POST https://iam.googleapis.com/v1/projects/project-id/serviceAccounts/sa-id:setIamPolicy

Request JSON body:

{
  "policy": policy
}

To send your request, expand one of these options:

The response contains the updated policy.

Listing members that can access a service account

Use the Cloud Console to view all members that have access to a service account, either because of roles granted on the service account or because of roles granted on the project, folder, or organization:

  1. In the Cloud Console, go to the Service Accounts page.

    Go to the Service Accounts page

  2. Click Select a project, choose a project, and click Open.

  3. Select the checkbox next to the desired service account.

  4. If the info panel isn't already visible, click Show info panel. A list of roles that have been granted on the service account are displayed.

  5. Expand each role to view the members that have been granted that role on the service account.

Attaching a service account to a resource

For some Google Cloud resources, you can specify a user-managed service account that the resource uses as its default identity. This process is known as attaching the service account to the resource, or associating the service account with the resource.

When the resource needs to access other Google Cloud services and resources, it impersonates the service account that is attached to the resource. For example, if you attach a service account to a Compute Engine instance, the applications on the instance automatically use that service account when they call Google Cloud APIs.

In most cases, you must attach a service account to a resource when you create that resource. After the resource is created, you cannot change which service account is attached to the resource. Compute Engine instances are an exception to this rule; you can change which service account is attached to an instance as needed.

See the instructions for the type of resource that you want to create:

Attaching a service account when creating a resource
AI Platform Notebooks Notebook instances
AI Platform Prediction Model versions
AI Platform Training Jobs
Cloud Composer Environments
Cloud Functions Cloud Function
Cloud Life Sciences Pipelines
Cloud Run Services
Cloud Scheduler Jobs
Cloud Source Repositories
Compute Engine
Dataflow Jobs
Datalab Instances
Dataproc Clusters
Google Kubernetes Engine
Pub/Sub Subscriptions

After you have created the resource and attached the service account to that resource, you can grant roles to the service account so it can access the appropriate resources. This process is the same as granting a role to any other member.

To learn how to grant roles, see Granting, changing, and revoking access to resources.

What's next