When granting IAM roles, you can treat a service account either as a resource or as an identity.
Your application uses a service account as an identity to authenticate to Google Cloud Platform services. For example, if you have a Compute Engine Virtual Machine (VM) running as a service account, you can grant the editor role to the service account (the identity) for a project (the resource).
At the same time, you might also want to control who can start the VM. You can
do this by granting a user (the identity) the
serviceAccountUser
role for the service account (the resource).
For information on service accounts and more examples on using service accounts as a resource and an identity see Service Accounts.
Prerequisites for this guide
Install the
gcloud
command-line tool if you want to use the command-line examples in this guide.Read Understanding Roles to see a list of predefined roles you can grant to a service account.
Granting roles to a service account for specific resources
You grant roles to a service account so that the service account has
permission to complete specific actions on the resources in your Cloud Platform
project. For example, you might grant the storage.admin
role to a service
account so that it has control over objects and buckets in Google Cloud Storage.
To grant roles to a service account, use one of the methods below:
Console
You can manage roles on service accounts the same way you manage roles on users in your project.
Open the IAM & Admin page in the Cloud Console.
Select your project and click Continue.
Identify the service account to which you want to add a role.
- If the service account isn't already on the members list, it doesn't have any roles assigned to it. Click Add and enter the email address of the service account.
- If the service account is already on the members list, it has existing roles. Click the drop-down list under Role(s) for the service account that you want to edit.
Select one or more roles to apply to the service account.
Click Add or Save to apply the roles to the service account.
gcloud
Add a role to a single service account.
gcloud projects add-iam-policy-binding my-project-123 \
--member serviceAccount:my-sa-123@my-project-123.iam.gserviceaccount.com \
--role roles/editor
The command outputs the updated policy:
bindings:
- members:
- user:email1@example.com
role: roles/owner
- members:
- serviceAccount:our-project-123@appspot.gserviceaccount.com
- serviceAccount:123456789012-compute@developer.gserviceaccount.com
- serviceAccount:my-sa-123@my-project-123.iam.gserviceaccount.com
- user:email3@example.com
role: roles/editor
- members:
- user:email2@example.com
role: roles/viewer
etag: BwUm38GGAQk=
version: 1
For instructions on granting access to service accounts as identities for projects see Granting, Changing, Revoking Access to Project Members.
API
The following POST
request uses the projects.setIamPolicy()
method to
grant editor access to a service account my-sa-123
for the project
my-project-123
. The request body must contain the new policy that grants
permissions to the service account. Each role can have multiple members.
POST https://cloudresourcemanager.googleapis.com/v1/projects/my-project-123:setIamPolicy
{
"policy":
{
"version": 1,
"etag": "BwUqMvZQGfo=",
"bindings": [
{
"role": "roles/editor",
"members": [
"serviceAccount:my-sa-123@my-project-123.iam.gserviceaccount.com",
"user:alice@example.com"
]
},
{
"role":"roles/owner",
"members":
[
"user:bob@example.com",
]
},
{
"role":"roles/viewer",
"members":
[
"user:john@example.com",
]
},
{
"role":"roles/iam.serviceAccountUser",
"members":
[
"user:alice@example.com"
]
},
]
},
}
The response contains the new policy:
{
"version": 1,
"etag": "BwUqMvZQGfo=",
"bindings": [
{
"role": "roles/editor",
"members": [
"serviceAccount:my-sa-123@my-project-123.iam.gserviceaccount.com",
"user:alice@example.com"
]
},
{
"role":"roles/owner",
"members":
[
"user:bob@example.com",
]
},
{
"role":"roles/viewer",
"members":
[
"user:john@example.com",
]
},
{
"role":"roles/iam.serviceAccountUser",
"members":
[
"user:alice@example.com"
]
},
]
}
Configuring ownership and access to a service account
You can allow specific users to have ownership and access to service accounts by treating them as a resource instead of an identity. The steps in this section treat service accounts as a resource. For more information on the differences between each usage type, see the Service Accounts topic.
Users with primitive project owner and project editor roles can already modify service accounts, but you might want to restrict access for some users so that they can take only specific actions against service account resources.
To grant a user permissions for a service account, use one of the methods below:
Console
Open the IAM & Admin page in the Cloud Console.
Select your project and click Continue.
In the left nav, click Service accounts.
Select a service account, then open the Info Panel. All users who can access that service account are displayed.
Add the email address of a project member.
Select a role for the member to define what actions that member can take against the service account.
Click Add to apply the role to the project member.
gcloud
Updating the whole policy:
First, Get the policy you want to modify, and write it to a JSON file. You can
use the --format
flag to choose the output formats (the
available output formats are JSON, YAML, and text). The other examples on
this page use the default text output formats, but this example writes the
output into a JSON file (policy.json) to modify the existing policy
before setting it.
gcloud iam service-accounts get-iam-policy \
my-sa-123@my-project-123.iam.gserviceaccount.com \
--format json > policy.json
Note that this command only returns a policy that has been set on the service account itself. If there is no existing policy set on the service account, the contents of the JSON file will look similar to the following:
{
"etag": "ACAB"
}
When no existing policy exists, you can either set a new policy with a single binding using the steps below, or manually create the policy using the JSON in the following steps as a template.
If a policy is already in effect, the contents of the outputted policy.json file will look similar to the following:
{
"bindings": [
{
"members": [
"user:bob@example.com"
],
"role": "roles/owner"
}
],
"etag": "BwUqLaVeua8="
}
Second, in a text editor, modify the policy.json file by adding a new
object to the bindings
array that defines the group members and
their roles. Create the bindings
array if it doesn't already
exist. To grant the serviceAccountUser
role to
alice@example.com
, you would change the example shown above as
follows:
{
"bindings": [
{
"role": "roles/iam.serviceAccountUser",
"members": [
"user:alice@example.com"
]
},
{
"role": "roles/owner",
"members": [
"user:bob@example.com"
]
}
],
"etag": "BwUqLaVeua8=",
}
Third, update the policy by running the following command:
gcloud iam service-accounts set-iam-policy \
my-sa-123@my-project-123.iam.gserviceaccount.com policy.json
The command outputs the updated policy:
bindings:
- members:
- user:alice@example.com
role: roles/iam.serviceAccountUser
- members:
- bob@example.com
role: roles/owner
etag: BwUjMhXbSPU=
version: 1
You can add a single binding to an new or existing policy by running the following command:
gcloud iam service-accounts add-iam-policy-binding \
my-sa-123@my-project-123.iam.gserviceaccount.com \
--member='user:jane@example.com' --role='roles/editor'
The command outputs the updated policy:
bindings:
- members:
- user:alice@example.com
role: roles/iam.serviceAccountUser
- members:
- user:bob@example.com
role: roles/owner
- members:
- user:jane@example.com
role: roles/editor
etag: BwUqKjVeua8=
version: 1
Removing a single binding:
You can remove a single binding from an existing policy by running the following command:
gcloud iam service-accounts remove-iam-policy-binding \
my-sa-123@my-project-123.iam.gserviceaccount.com \
--member='user:jane@example.com' --role='roles/editor'
The command outputs the updated policy:
bindings:
- members:
- user:alice@example.com
role: roles/iam.serviceAccountUser
- members:
- user:bob@example.com
role: roles/owner
etag: BwUqNkVeua8=
version: 1
API
Request:
POST https://iam.googleapis.com/v1/projects/my-project-123/serviceAccounts/my-sa-123@my-project-123.iam.gserviceaccount.com:setIamPolicy
The request body must contain the policy to be granted:
{
"policy":
{
"etag": "BwUqLaVeua8=",
"bindings": [
{
"role": "roles/iam.serviceAccountUser",
"members": [
"user:alice@example.com"
]
},
{
"role": "roles/owner",
"members": [
"user:bob@example.com"
]
}
]
},
}
The response contains the updated policy:
{
"etag": "BwUqMqbViM8=",
"bindings": [
{
"role": "roles/iam.serviceAccountUser",
"members": [
"user:alice@example.com"
]
},
{
"role": "roles/owner",
"members": [
"user:bob@example.com"
]
}
]
}
Viewing existing roles on a service account
Since a service account can be
treated as a resource, they have
Cloud IAM policies like other Google Cloud resources. Therefore,
to view the members who have been granted a role on a given service account,
get the Cloud IAM policy for a service account using the
serviceAccounts.getIamPolicy()
method, the Cloud Console, or the
gcloud
tool.
Console
Open the IAM & Admin page in the Cloud Console.
Select your project and click Continue. This page lists all the users and their corresponding roles for this project.
In the left nav, click Service accounts.
Select the checkbox next to the desired service account, and then click Show Info Panel on the top right of the page. A list of roles that have been granted on the service account are displayed. Expand each role to view the members that have been granted that role on the service account.
gcloud
To get a policy for a service account, run the following command:
gcloud iam service-accounts get-iam-policy \
my-sa-123@my-project-123.iam.gserviceaccount.com
The output will be the policy, similar to the following:
bindings:
- members:
- user:bob@example.com
role: roles/owner
- members:
- user:alice@example.com
role: roles/iam.serviceAccountUser
etag: BwUqLaVeua8=
version: 1
If you have not assigned a role to the service account, the output will show only an etag value:
etag: ACAB
API
The following code snippets gets the IAM policy for the service account
my-sa-123@my-project-123.iam.gserviceaccount.com
.
Request:
POST https://iam.googleapis.com/v1/projects/my-project-123/serviceAccounts/my-sa-123@my-project-123.iam.gserviceaccount.com:getIamPolicy
Response:
{
"etag": "BwUqLaVeua8=",
"bindings": [
{
"role": "roles/iam.serviceAccountUser",
"members": [
"user:alice@example.com"
]
}
]
}
If you have not assigned a role to the service account, the response will contain only an etag value:
{
"etag": "ACAB"
}
For more information about IAM policies, see Policy.