Granting roles to service accounts

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.

Note: In order to grant a custom role to a service account, the role must include at least one permission which is applicable to the service account. To determine what permissions can be applied to a given resource, see Creating custom roles.

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.

1. Open the IAM & Admin page in the GCP Console.

   Open the IAM & Admin page

2. Select your project and click Continue.

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

4. Select one or more roles to apply to the service account.

5. 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:[e-mail] \
  --role roles/editor

The command outputs the updated policy:

bindings:
- members:
  - user:[e-mail]
  role: roles/owner
- members:
  - serviceAccount:[e-mail]
  - serviceAccount:[e-mail]
  - serviceAccount:[e-mail]
  - user:[e-mail]
  role: roles/editor
- members:
  - user:[e-mail]
  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/v1beta1/projects/my-project-123:setIamPolicy

{
    "policy":
    {
        "version": 1,
        "etag": "BwUqMvZQGfo=",
        "bindings": [
        {
            "role": "roles/editor",
            "members": [
                "serviceAccount:[e-mail]",
                "user:[e-mail]"
            ]
        },
        {
            "role":"roles/owner",
            "members":
            [
                "user:[e-mail]",
            ]
        },
        {
            "role":"roles/viewer",
            "members":
            [
                "user:[e-mail]",
            ]
        },
        {
            "role":"roles/iam.serviceAccountUser",
            "members":
            [
                "user:[e-mail]"
            ]
        },
        ]
    },
}

The response contains the new policy:

{
    "version": 1,
    "etag": "BwUqMvZQGfo=",
    "bindings": [
    {
        "role": "roles/editor",
        "members": [
            "serviceAccount:[e-mail]",
            "user:[e-mail]"
        ]
    },
    {
        "role":"roles/owner",
        "members":
        [
            "user:[e-mail]",
        ]
    },
    {
        "role":"roles/viewer",
        "members":
        [
            "user:[e-mail]",
        ]
    },
    {
        "role":"roles/iam.serviceAccountUser",
        "members":
        [
            "user:[e-mail]"
        ]
    },
    ]
}

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

1. Open the IAM & Admin page in the GCP Console.

   Open the IAM & Admin page

2. Select your project and click Continue.

3. In the left nav, click Service accounts.

4. Select a service account, then open the Info Panel. All users who can access that service account are displayed.

5. Add the email address of a project member.

6. Select a role for the member to define what actions that member can take against the service account.

7. 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 \
  [e-mail] \
  --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:[e-mail]"
      ],
      "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 [e-mail], you would change the example shown above as follows:

{
    "bindings": [
    {
        "role": "roles/iam.serviceAccountUser",
        "members": [
            "user:[e-mail]"
        ]
    },
    {
        "role": "roles/owner",
        "members": [
            "user:[e-mail]"
        ]
    }
    ],
    "etag": "BwUqLaVeua8=",
}

Third, update the policy by running the following command:

gcloud iam service-accounts set-iam-policy \
  [e-mail] policy.json

The command outputs the updated policy:

bindings:
- members:
  - user:[e-mail]
  role: roles/iam.serviceAccountUser
- members:
  - [e-mail]
  role: roles/owner
etag: BwUjMhXbSPU=
version: 1

Adding a single binding:

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 \
  [e-mail] \
  --member='user:[e-mail]' --role='roles/editor'

The command outputs the updated policy:

bindings:
- members:
  - user:[e-mail]
  role: roles/iam.serviceAccountUser
- members:
  - user:[e-mail]
  role: roles/owner
- members:
  - user:[e-mail]
  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 \
    [e-mail] \
    --member='user:[e-mail]' --role='roles/editor'

The command outputs the updated policy:

bindings:
- members:
  - user:[e-mail]
  role: roles/iam.serviceAccountUser
- members:
  - user:[e-mail]
  role: roles/owner
etag: BwUqNkVeua8=
version: 1

API

Request:

POST https://iam.googleapis.com/v1/projects/my-project-123/serviceAccounts/[e-mail]:setIamPolicy

The request body must contain the policy to be granted:

{
    "policy":
    {
        "etag": "BwUqLaVeua8=",
        "bindings": [
        {
            "role": "roles/iam.serviceAccountUser",
            "members": [
                "user:[e-mail]"
            ]
        },
        {
            "role": "roles/owner",
            "members": [
                "user:[e-mail]"
            ]
        },
        ]
    },
}

The response contains the updated policy:

{
    "etag": "BwUqMqbViM8=",
    "bindings": [
    {
        "role": "roles/iam.serviceAccountUser",
        "members": [
            "user:[e-mail]"
        ]
    },
    {
        "role": "roles/owner",
        "members": [
        "user:[e-mail]"
        ]
    }
    ]
}

Viewing existing roles on a service account

You can get an IAM policy of a service account using the serviceAccounts.getIamPolicy() method, the GCP Console, and the gcloud tool.

Console

1. Open the IAM & Admin page in the GCP Console.

   Open the IAM & Admin page

2. Select your project and click Continue. This page lists all the users and their corresponding roles for this project.

3. In the left nav, click Service accounts.

4. Select a service account, and then click Show Info Panel on the top right of the page. All roles for the service account are displayed in the info panel.

gcloud

To get a policy for a service account, run the following command:

gcloud iam service-accounts get-iam-policy \
    [e-mail]

The output will be the policy, similar to the following:

bindings:
- members:
  - user:[e-mail]
  role: roles/owner
- members:
  - user:[e-mail]
  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 [e-mail].

Request:

POST https://iam.googleapis.com/v1/projects/my-project-123/serviceAccounts/[e-mail]:getIamPolicy

Response:

{
    "etag": "BwUqLaVeua8=",
    "bindings": [
    {
        "role": "roles/iam.serviceAccountUser",
        "members": [
            "user:[e-mail]"
        ]
    }
    ]
}

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.