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 allow policies, also known as IAM policies. An allow policy is attached to a Google Cloud resource. Each allow 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 allow policy is attached to and on all of that resource's descendants. For more information about allow policies, see Understanding allow 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 Google Cloud CLI, and the REST API. You can also manage access using the IAM client libraries.

Before you begin

Required roles

To get the permissions that you need to manage access to a service account, ask your administrator to grant you the Service Account Admin (roles/iam.serviceAccountAdmin) IAM role on the service account or the project that owns the service account. For more information about granting roles, see Manage access.

This predefined role contains the permissions required to manage access to a service account. To see the exact permissions that are required, expand the Required permissions section:

Required permissions

The following permissions are required to manage access to a service account:

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

You might also be able to get these permissions with custom roles or other predefined roles.

View current access

The following section shows you how to use the Google Cloud console, the gcloud CLI, 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 allow policy.

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 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 allow policy for the service account. To learn how to interpret allow policies, see Understanding allow policies.

To get the allow 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 SA_NAME@PROJECT_ID.iam.gserviceaccount.com, or the service account's unique numeric ID.

  • 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 allow policy for the service account. To learn how to interpret allow policies, see Understanding allow policies.

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.
  • 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 allow 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 Google Cloud console and the gcloud CLI to quickly grant or revoke a single role for a single principal, without editing the service account's allow 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.

If you need help identifying the most appropriate predefined role, see Choose predefined roles.

Grant a single role

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

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 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 a row containing the principal, 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 role to a principal who doesn't have any existing roles on the service account, click Grant access, then enter the principal's email address or other identifier.

  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_NAME \
    --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_NAME: The name of the role that you want to grant. Use one of the following formats:

    • Predefined roles: roles/SERVICE.IDENTIFIER
    • Project-level custom roles: projects/PROJECT_ID/roles/IDENTIFIER
    • Organization-level custom roles: organizations/ORG_ID/roles/IDENTIFIER

    For a list of predefined 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 Google 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 the role that 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_NAME

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_NAME: The name of the role that you want to revoke. Use one of the following formats:

    • Predefined roles: roles/SERVICE.IDENTIFIER
    • Project-level custom roles: projects/PROJECT_ID/roles/IDENTIFIER
    • Organization-level custom roles: organizations/ORG_ID/roles/IDENTIFIER

    For a list of predefined 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 using the Google Cloud console

You can use the Google Cloud console to grant and revoke multiple roles for a single principal:

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

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

  5. Select the principal whose roles you want to modify:

    • To modify roles for a principal who already has roles on the service account, find a row containing the principal, then click Edit principal in that row, then click Add another role.

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

    • To grant roles to a principal who doesn't have any existing roles on the service account, click Grant access, then enter the principal's email address or other identifier.

  6. Modify the principal's roles:

    • To grant a role to a principal who doesn't have any existing roles on the resource, click Select a role, then select a role to grant from the drop-down list.
    • To grant an additional role to the principal, click Add another role, then select a role to grant from the drop-down list.
    • To replace one of the principal's roles with a different role, click the existing role, then choose a different role to grant from the drop-down list.
    • To revoke one of the principal's roles, click the Delete button for each role that you want to revoke.

    You can also add a condition to a role, modify a role's condition, or remove a role's condition.

  7. Click Save.

Grant or revoke multiple roles programmatically

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

  1. Read the current allow policy by calling getIamPolicy().
  2. Edit the allow policy, either by using a text editor or programmatically, to add or remove any principals or role bindings.
  3. Write the updated allow policy by calling setIamPolicy().

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

Get the current allow policy

gcloud

To get the allow 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 SA_NAME@PROJECT_ID.iam.gserviceaccount.com, or the service account's unique numeric ID.

  • FORMAT: The desired format for the allow policy. Use json or yaml.

  • PATH: The path to a new output file for the allow policy.

For example, the following command gets the allow 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 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.
  • 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 allow 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 allow policy

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

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

To edit the roles that an allow policy grants, you need to edit the role bindings in the allow policy. Role bindings have the following format:

{
  "role": "ROLE_NAME",
  "members": [
    "PRINCIPAL_1",
    "PRINCIPAL_2",
    ...
    "PRINCIPAL_N"
  ],
  "conditions:" {
    CONDITIONS
  }
}

The placeholders have the following values:

  • ROLE_NAME: The name of the role that you want to grant. Use one of the following formats:

    • Predefined roles: roles/SERVICE.IDENTIFIER
    • Project-level custom roles: projects/PROJECT_ID/roles/IDENTIFIER
    • Organization-level custom roles: organizations/ORG_ID/roles/IDENTIFIER

    For a list of predefined roles, see Understanding roles.

  • PRINCIPAL_1, PRINCIPAL_2, ...PRINCIPAL_N: Identifiers for the principals that you want to grant the role to.

    Principal identifiers usually have 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.

  • CONDITIONS: Optional. Any conditions that specify when access will be granted.

Grant a role

To grant roles to your principals, modify the role bindings in the allow policy. To learn what roles you can grant, see Understanding roles, or view grantable roles for the service account. If you need help identifying the most appropriate predefined roles, see Choose predefined roles.

Optionally, you can use conditions to grant roles only when certain requirements are met.

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

gcloud

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

For example, imagine the allow 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 allow policy by adding the principal to an existing role binding. Note that this change will not take effect until you set the updated allow policy.

For example, imagine the allow 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 allow policy, add a new role binding:

gcloud

Edit the allow policy by adding a new role binding that grants the role to the principal. This change will not take effect until you set the updated allow 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 allow policy:

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

REST

Edit the allow policy by adding a new role binding that grants the role to the principal. This change will not take effect until you set the updated allow 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 allow 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 allow policy.

gcloud

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

For example, imagine the allow 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 allow policy.

REST

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

For example, imagine the allow 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 allow policy.

Set the allow policy

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

gcloud

To set the allow 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 allow policy.

The response contains the updated allow policy.

For example, the following command sets the allow policy stored in policy.json as the allow 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 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.
  • 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 allow 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 allow 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