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 serviceAccountActor 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:

API

The following POST request uses the projects.setIamPolicy() method to grant editor access to a service account my-sa 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.serviceAccountActor",
            "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.serviceAccountActor",
        "members":
        [
            "user:[e-mail]"
        ]
    },
    ]
}

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 Cloud Platform 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 member 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 current role drop-down list 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.

Configuring ownership and access to a service account

You can allow specific users to have ownership and access to service accounts and their settings. 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 permission for a service account, use one of the methods below:

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.serviceAccountActor",
            "members": [
                "user:[e-mail]"
            ]
        },
        {
            "role": "roles/owner",
            "members": [
                "user:[e-mail]"
            ]
        },
        ]
    },
}

The response contains the updated policy:

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

Console

1. Open the IAM & Admin page in the Cloud Platform 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 and click Permissions. 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:

1. 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 to modify the existing policy before setting it.

       gcloud iam service-accounts get-iam-policy \
   [e-mail] \
   --format json > policy.json
   

   The contents of the JSON file will look similar to the following:

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

2. Using a text editor, add a new object to the bindings array that defines the group members and the role for those members. To grant the serviceAccountActor role to [e-mail], you would change the example shown above as follows:

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

3. 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.serviceAccountActor
     - members:
   - [e-mail]
     role: roles/owner
     etag: BwUjMhXbSPU=
     version: 1
     

Adding a single binding:

You can add a single binding to an 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.serviceAccountActor
- 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.serviceAccountActor
- members:
  - user:[e-mail]
    role: roles/owner
    etag: BwUqNkVeua8=
version: 1

Viewing existing roles on a service account

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

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.serviceAccountActor",
        "members": [
            "user:[e-mail]"
        ]
    }
    ]
}

Console

1. Open the AM & Admin page in the Cloud Platform 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 click Permissions. All service accounts for the project are displayed.

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.serviceAccountActor
etag: BwUqLaVeua8=
version: 1