Manage access to service accounts

This page describes how to grant, change, and revoke a principal's access to a single service account. To manage a principal's access to all service accounts in a project, folder, or organization, manage their access at the project, folder, or organization level.

In Identity and Access Management (IAM), access is managed through IAM policies. An IAM policy is attached to a Google Cloud resource. Each policy contains a collection of role bindings that associate one or more principals, such as users or service accounts, with an IAM role. These role bindings grant the specified roles to the principals, both on the resource that the policy is attached to and on all of that resource's descendants. For more information about IAM policies, see Understanding policies.

Service accounts are both resources that other principals can be granted access to, and principals that can be granted access to other resources. This page treats service accounts as resources and describes how to grant other principals access to them. To learn how to grant a service account access to other resources, the following guides:

This page describes how to manage access to service accounts using the Google Cloud Console, the gcloud command-line tool, and the REST API. You can also manage access using the IAM client libraries.

Before you begin

Learn about service accounts.

Required permissions

To manage access to a service account, you need a role that includes the following permissions:

  • iam.serviceAccounts.get
  • iam.serviceAccounts.list
  • iam.serviceAccounts.getIamPolicy
  • iam.serviceAccounts.setIamPolicy

To gain these permissions while following the principle of least privilege, ask your administrator to grant you one of the following roles:

  • Service Account Admin (roles/iam.serviceAccountAdmin)
  • Security Admin (roles/iam.securityAdmin)

Alternatively, your administrator can grant you a different role with the required permissions, such as a custom role or a more permissive predefined role.

View current access

The following section shows you how to use the Cloud Console, the gcloud tool, and the REST API to view who has access to a service account. You can also view access by using the IAM client libraries to get the service account's IAM policy.

Console

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

    Go to Service Accounts

  2. Select a project.

  3. Click the email address of the service account.

  4. Go to the Permissions tab. The Principals with access to this service account section lists all the principals who have been granted a role on the service account.

    This list includes principals whose access comes from roles that are granted on parent resources. For more information about policy inheritance, see Policy inheritance and the resource hierarchy.

  5. Optional: To view role grants for Google-managed service accounts, select the Include Google-provided role grants checkbox.

gcloud

To see who has access to your service account, get the IAM policy for the service account. To learn how to interpret IAM policies, see Understanding policies.

To get the IAM policy for the service account, run the get-iam-policy command for the service account:

gcloud iam service-accounts get-iam-policy SA_ID --format=FORMAT > PATH

Provide the following values:

  • SA_ID: The ID of your service account. This can either be the service account's email address in the form
  • FORMAT: The desired format for the policy. Use json or yaml.
  • PATH: The path to a new output file for the policy.

For example, the following command gets the policy for the service account my-service-account and saves it to your home directory in JSON format:

gcloud iam service-accounts get-iam-policy my-service-account --format json > ~/policy.json

REST

To see who has access to your service account, get the IAM policy for the service account. To learn how to interpret IAM policies, see Understanding policies.

The serviceAccounts.getIamPolicy method gets a service account's IAM 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.
  • 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:

The response contains the service account's IAM policy. For example:

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

Grant or revoke a single role

You can use the Cloud Console and the gcloud tool to quickly grant or revoke a single role for a single principal, without editing the service account's IAM policy directly. Common types of principals include Google accounts, service accounts, Google groups, and domains. For a list of all principal types, see Concepts related to identity.

Grant a single role

To grant a single role to a principal, do the following:

Console

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

    Go to Service Accounts

  2. Select a project.

  3. Click the email address of the service account.

  4. Go to the Permissions tab and find the section Principals with access to this service account.

  5. Select a principal to grant a role to:

    • To grant a role to a principal who already has other roles on the service account, find the row containing the principal's email address, then click Edit principal in that row, then click Add another role.

      If you want to grant a role to a Google-managed service account, you must select the Include Google-provided role grants checkbox to see its email address.

    • To grant a principal who does not already have other roles on the service account, click Grant access, then enter the principal's email address.

  6. Select a role to grant from the drop-down list. For best security practices, choose a role that includes only the permissions that your principal needs.

  7. Optional: Add a condition to the role.

  8. Click Save. The principal is granted the role on the service account.

gcloud

To quickly grant a role to a principal, run the add-iam-policy-binding command:

gcloud iam service-accounts add-iam-policy-binding SA_ID \
    --member=PRINCIPAL --role=ROLE_ID \
    --condition=CONDITION

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

  • PRINCIPAL: An identifier for the principal, or member, which usually has the following form: PRINCIPAL-TYPE:ID. For example, user:my-user@example.com. For a full list of the values that PRINCIPAL can have, see the Policy Binding reference.

    For the principal type user, the domain name in the identifier must be a Google Workspace domain or a Cloud Identity domain. To learn how to set up a Cloud Identity domain, see the overview of Cloud Identity.

  • ROLE_ID: The name of the role that you want to grant. For example, roles/iam.serviceAccountUser. For a list of roles, see Understanding roles.

  • CONDITION: Optional. The condition to add to the role binding. For more information about conditions, see the conditions overview.

For example, to grant the Service Account User role to the user my-user@example.com for the service account my-service-account@my-project.iam.gserviceaccount.com:

gcloud iam service-accounts add-iam-policy-binding my-service-account@my-project.iam.gserviceaccount.com \
    --member=user:my-user@example.com --role=roles/iam.serviceAccountUser

Revoke a single role

To revoke a single role from a principal, do the following:

Console

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

    Go to Service Accounts

  2. Select a project.

  3. Click the email address of the service account.

  4. Go to the Permissions tab and find the section Principals with access to this service account.

  5. Find the row with the email address of the principal whose access you want to revoke. Then, click Edit principal in that row.

  6. Click the Delete button for each role you want to revoke, and then click Save.

gcloud

To quickly revoke a role from a user, run the remove-iam-policy-binding command:

gcloud iam service-accounts remove-iam-policy-binding SA_ID \
    --member=PRINCIPAL --role=ROLE_ID

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

  • PRINCIPAL: An identifier for the principal, or member, which usually has the following form: PRINCIPAL-TYPE:ID. For example, user:my-user@example.com. For a full list of the values that PRINCIPAL can have, see the Policy Binding reference.

    For the principal type user, the domain name in the identifier must be a Google Workspace domain or a Cloud Identity domain. To learn how to set up a Cloud Identity domain, see the overview of Cloud Identity.

  • ROLE_ID: The name of the role that you want to revoke. For example, roles/iam.serviceAccountUser. For a list of roles, see Understanding roles.

For example, to revoke the Service Account User role from the user my-user@example.com for the service account my-service-account@my-project.iam.gserviceaccount.com:

gcloud iam service-accounts remove-iam-policy-binding my-service-account@my-project.iam.gserviceaccount.com \
    --member=user:my-user@example.com --role=roles/iam.serviceAccountUser

Grant or revoke multiple roles

To make large-scale access changes that involve granting and revoking multiple roles, use the read-modify-write pattern to update the service account's IAM policy:

  1. Reading the current policy by calling getIamPolicy().
  2. Editing the returned policy, either by using a text editor or programmatically, to add or remove any principals or role bindings.
  3. Writing the updated policy by calling setIamPolicy().

This section shows how to use the gcloud tool and the REST API to update the policy. You can also update the policy using the IAM client libraries.

Get the current policy

gcloud

To get the IAM policy for the service account, run the get-iam-policy command for the service account:

gcloud iam service-accounts get-iam-policy SA_ID --format=FORMAT > PATH

Provide the following values:

  • SA_ID: The ID of your service account. This can either be the service account's email address in the form
  • FORMAT: The desired format for the policy. Use json or yaml.
  • PATH: The path to a new output file for the policy.

For example, the following command gets the policy for the service account my-service-account and saves it to your home directory in JSON format:

gcloud iam service-accounts get-iam-policy my-service-account --format json > ~/policy.json

REST

The serviceAccounts.getIamPolicy method gets a service account's IAM 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.
  • 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:

The response contains the service account's IAM policy. For example:

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

Save the response in a file of the appropriate type (json or yaml).

Modify the policy

Programmatically or using a text editor, modify the local copy of your service account's policy to reflect the roles you want to grant or revoke to given users.

To ensure that you do not overwrite other policy changes, do not edit or remove the policy's etag field. The etag field identifies the current policy state. When you set the updated policy, IAM compares the etag value in the request with the existing etag, and only writes the policy if the values match.

Grant a role

To grant roles to your principals, modify the role bindings in the policy. To learn what roles you can grant, see Understanding roles, or view grantable roles for the service account.

To grant a role that is already included in the policy, add the principal to an existing role binding:

gcloud

Edit the returned policy by adding the principal to an existing role binding. Note that this policy change will not take effect until you set the updated policy.

For example, imagine the returned policy contains the following role binding, which grants the Service Account User role (roles/iam.serviceAccountUser) to kai@example.com:

{
  "role": "roles/iam.serviceAccountUser",
  "members": [
    "user:kai@example.com"
  ]
}

To grant that same role to raha@example.com, add raha@example.com to the existing role binding:

{
  "role": "roles/iam.serviceAccountUser",
  "members": [
    "user:kai@example.com",
    "user:raha@example.com"
  ]
}

REST

Edit the returned policy by adding the principal to an existing role binding. Note that this policy change will not take effect until you set the updated policy.

For example, imagine the returned policy contains the following role binding, which grants the Service Account User role (roles/iam.serviceAccountUser) to kai@example.com:

{
  "role": "roles/iam.serviceAccountUser",
  "members": [
    "user:kai@example.com"
  ]
}

To grant that same role to raha@example.com, add raha@example.com to the existing role binding:

{
  "role": "roles/iam.serviceAccountUser",
  "members": [
    "user:kai@example.com",
    "user:raha@example.com"
  ]
}

To grant a role that is not yet included in the policy, add a new role binding:

gcloud

Edit the returned policy by adding a new role binding that grants the role to the principal. This policy change will not take effect until you set the updated policy.

For example, to grant the Service Account Token Creator role (roles/iam.serviceAccountTokenCreator) to raha@example.com, add the following role binding to the bindings array for the policy:

{
  "role": "roles/iam.serviceAccountTokenCreator",
  "members": [
    "user:raha@example.com"
  ]
}

REST

Edit the returned policy by adding a new role binding that grants the role to the principal. This policy change will not take effect until you set the updated policy.

For example, to grant the Service Account Token Creator role (roles/iam.serviceAccountTokenCreator) to raha@example.com, add the following role binding to the bindings array for the policy:

{
  "role": "roles/iam.serviceAccountTokenCreator",
  "members": [
    "user:raha@example.com"
  ]
}

Revoke a role

To revoke a role, remove the principal from the role binding. If there are no other principals in the role binding, remove the entire role binding from the policy.

gcloud

Edit the returned policy by removing the principal or the entire role binding. This policy change will not take effect until you set the updated policy.

For example, imagine the returned policy contains the following role binding, which grants kai@example.com and raha@example.com the Service Account User role (roles/iam.serviceAccountUser):

{
  "role": "roles/iam.serviceAccountUser",
  "members": [
    "user:kai@example.com",
    "user:raha@example.com"
  ]
}

To revoke the role from kai@example.com, remove kai@example.com from the role binding:

{
  "role": "roles/iam.serviceAccountUser",
  "members": [
    "user:raha@example.com"
  ]
}

To revoke the role from both kai@example.com and raha@example.com, remove the role binding from the policy.

REST

Edit the returned policy by removing the principal or the entire role binding. This policy change will not take effect until you set the updated policy.

For example, imagine the returned policy contains the following role binding, which grants kai@example.com and raha@example.com the Service Account User role (roles/iam.serviceAccountUser):

{
  "role": "roles/iam.serviceAccountUser",
  "members": [
    "user:kai@example.com",
    "user:raha@example.com"
  ]
}

To revoke the role from kai@example.com, remove kai@example.com from the role binding:

{
  "role": "roles/iam.serviceAccountUser",
  "members": [
    "user:raha@example.com"
  ]
}

To revoke the role from both kai@example.com and raha@example.com, remove the role binding from the policy.

Set the policy

After you modify the policy to grant and revoke the desired roles, call setIamPolicy() to make the updates.

gcloud

To set the IAM policy for the resource, run the set-iam-policy command for the service account:

gcloud iam service-accounts set-iam-policy SA_ID PATH

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

  • PATH: The path to a file that contains the new policy.

The response contains the updated policy.

For example, the following command sets the policy stored in policy.json as the policy for the service account my-service-account@my- project.iam.gserviceaccount.com:

gcloud iam service-accounts set-iam-policy my-service-account@my-project.iam.gserviceaccount.com \
    ~/policy.json

REST

The serviceAccounts.setIamPolicy method sets an updated IAM 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.
  • 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.

What's next

Try it for yourself

If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

Get started for free