Manage GCP Service Account IAM Bindings

The gcp:serviceaccount/iAMBinding:IAMBinding resource, part of the Pulumi GCP provider, grants a specific IAM role to a list of members on a service account, replacing any previous member list for that role. This guide focuses on three capabilities: authoritative role binding, conditional access with time constraints, and service account impersonation patterns.

IAMBinding is authoritative for a given role: it replaces the entire member list. Use IAMMember for non-authoritative grants, or IAMPolicy to manage the complete policy. The examples are intentionally small. Combine them with your own service accounts and access policies.

Grant a role to multiple members

Teams managing service account access typically need to grant a specific role to a list of users or service accounts.

import * as pulumi from "@pulumi/pulumi";
import * as gcp from "@pulumi/gcp";

const sa = new gcp.serviceaccount.Account("sa", {
    accountId: "my-service-account",
    displayName: "A service account that only Jane can use",
});
const admin_account_iam = new gcp.serviceaccount.IAMBinding("admin-account-iam", {
    serviceAccountId: sa.name,
    role: "roles/iam.serviceAccountUser",
    members: ["user:jane@example.com"],
});

import pulumi
import pulumi_gcp as gcp

sa = gcp.serviceaccount.Account("sa",
    account_id="my-service-account",
    display_name="A service account that only Jane can use")
admin_account_iam = gcp.serviceaccount.IAMBinding("admin-account-iam",
    service_account_id=sa.name,
    role="roles/iam.serviceAccountUser",
    members=["user:jane@example.com"])

package main

import (
	"github.com/pulumi/pulumi-gcp/sdk/v9/go/gcp/serviceaccount"
	"github.com/pulumi/pulumi/sdk/v3/go/pulumi"
)

func main() {
	pulumi.Run(func(ctx *pulumi.Context) error {
		sa, err := serviceaccount.NewAccount(ctx, "sa", &serviceaccount.AccountArgs{
			AccountId:   pulumi.String("my-service-account"),
			DisplayName: pulumi.String("A service account that only Jane can use"),
		})
		if err != nil {
			return err
		}
		_, err = serviceaccount.NewIAMBinding(ctx, "admin-account-iam", &serviceaccount.IAMBindingArgs{
			ServiceAccountId: sa.Name,
			Role:             pulumi.String("roles/iam.serviceAccountUser"),
			Members: pulumi.StringArray{
				pulumi.String("user:jane@example.com"),
			},
		})
		if err != nil {
			return err
		}
		return nil
	})
}

using System.Collections.Generic;
using System.Linq;
using Pulumi;
using Gcp = Pulumi.Gcp;

return await Deployment.RunAsync(() => 
{
    var sa = new Gcp.ServiceAccount.Account("sa", new()
    {
        AccountId = "my-service-account",
        DisplayName = "A service account that only Jane can use",
    });

    var admin_account_iam = new Gcp.ServiceAccount.IAMBinding("admin-account-iam", new()
    {
        ServiceAccountId = sa.Name,
        Role = "roles/iam.serviceAccountUser",
        Members = new[]
        {
            "user:jane@example.com",
        },
    });

});

package generated_program;

import com.pulumi.Context;
import com.pulumi.Pulumi;
import com.pulumi.core.Output;
import com.pulumi.gcp.serviceaccount.Account;
import com.pulumi.gcp.serviceaccount.AccountArgs;
import com.pulumi.gcp.serviceaccount.IAMBinding;
import com.pulumi.gcp.serviceaccount.IAMBindingArgs;
import java.util.List;
import java.util.ArrayList;
import java.util.Map;
import java.io.File;
import java.nio.file.Files;
import java.nio.file.Paths;

public class App {
    public static void main(String[] args) {
        Pulumi.run(App::stack);
    }

    public static void stack(Context ctx) {
        var sa = new Account("sa", AccountArgs.builder()
            .accountId("my-service-account")
            .displayName("A service account that only Jane can use")
            .build());

        var admin_account_iam = new IAMBinding("admin-account-iam", IAMBindingArgs.builder()
            .serviceAccountId(sa.name())
            .role("roles/iam.serviceAccountUser")
            .members("user:jane@example.com")
            .build());

    }
}

resources:
  sa:
    type: gcp:serviceaccount:Account
    properties:
      accountId: my-service-account
      displayName: A service account that only Jane can use
  admin-account-iam:
    type: gcp:serviceaccount:IAMBinding
    properties:
      serviceAccountId: ${sa.name}
      role: roles/iam.serviceAccountUser
      members:
        - user:jane@example.com

The serviceAccountId identifies the target service account. The role property specifies which permission set to grant (here, roles/iam.serviceAccountUser allows impersonation). The members array lists who receives the role; IAMBinding replaces any previous member list for this role, ensuring only the specified identities have access.

Add time-based access with IAM conditions

Access grants sometimes need expiration dates or other constraints.

import * as pulumi from "@pulumi/pulumi";
import * as gcp from "@pulumi/gcp";

const sa = new gcp.serviceaccount.Account("sa", {
    accountId: "my-service-account",
    displayName: "A service account that only Jane can use",
});
const admin_account_iam = new gcp.serviceaccount.IAMBinding("admin-account-iam", {
    serviceAccountId: sa.name,
    role: "roles/iam.serviceAccountUser",
    members: ["user:jane@example.com"],
    condition: {
        title: "expires_after_2019_12_31",
        description: "Expiring at midnight of 2019-12-31",
        expression: "request.time < timestamp(\"2020-01-01T00:00:00Z\")",
    },
});

import pulumi
import pulumi_gcp as gcp

sa = gcp.serviceaccount.Account("sa",
    account_id="my-service-account",
    display_name="A service account that only Jane can use")
admin_account_iam = gcp.serviceaccount.IAMBinding("admin-account-iam",
    service_account_id=sa.name,
    role="roles/iam.serviceAccountUser",
    members=["user:jane@example.com"],
    condition={
        "title": "expires_after_2019_12_31",
        "description": "Expiring at midnight of 2019-12-31",
        "expression": "request.time < timestamp(\"2020-01-01T00:00:00Z\")",
    })

package main

import (
	"github.com/pulumi/pulumi-gcp/sdk/v9/go/gcp/serviceaccount"
	"github.com/pulumi/pulumi/sdk/v3/go/pulumi"
)

func main() {
	pulumi.Run(func(ctx *pulumi.Context) error {
		sa, err := serviceaccount.NewAccount(ctx, "sa", &serviceaccount.AccountArgs{
			AccountId:   pulumi.String("my-service-account"),
			DisplayName: pulumi.String("A service account that only Jane can use"),
		})
		if err != nil {
			return err
		}
		_, err = serviceaccount.NewIAMBinding(ctx, "admin-account-iam", &serviceaccount.IAMBindingArgs{
			ServiceAccountId: sa.Name,
			Role:             pulumi.String("roles/iam.serviceAccountUser"),
			Members: pulumi.StringArray{
				pulumi.String("user:jane@example.com"),
			},
			Condition: &serviceaccount.IAMBindingConditionArgs{
				Title:       pulumi.String("expires_after_2019_12_31"),
				Description: pulumi.String("Expiring at midnight of 2019-12-31"),
				Expression:  pulumi.String("request.time < timestamp(\"2020-01-01T00:00:00Z\")"),
			},
		})
		if err != nil {
			return err
		}
		return nil
	})
}

using System.Collections.Generic;
using System.Linq;
using Pulumi;
using Gcp = Pulumi.Gcp;

return await Deployment.RunAsync(() => 
{
    var sa = new Gcp.ServiceAccount.Account("sa", new()
    {
        AccountId = "my-service-account",
        DisplayName = "A service account that only Jane can use",
    });

    var admin_account_iam = new Gcp.ServiceAccount.IAMBinding("admin-account-iam", new()
    {
        ServiceAccountId = sa.Name,
        Role = "roles/iam.serviceAccountUser",
        Members = new[]
        {
            "user:jane@example.com",
        },
        Condition = new Gcp.ServiceAccount.Inputs.IAMBindingConditionArgs
        {
            Title = "expires_after_2019_12_31",
            Description = "Expiring at midnight of 2019-12-31",
            Expression = "request.time < timestamp(\"2020-01-01T00:00:00Z\")",
        },
    });

});

package generated_program;

import com.pulumi.Context;
import com.pulumi.Pulumi;
import com.pulumi.core.Output;
import com.pulumi.gcp.serviceaccount.Account;
import com.pulumi.gcp.serviceaccount.AccountArgs;
import com.pulumi.gcp.serviceaccount.IAMBinding;
import com.pulumi.gcp.serviceaccount.IAMBindingArgs;
import com.pulumi.gcp.serviceaccount.inputs.IAMBindingConditionArgs;
import java.util.List;
import java.util.ArrayList;
import java.util.Map;
import java.io.File;
import java.nio.file.Files;
import java.nio.file.Paths;

public class App {
    public static void main(String[] args) {
        Pulumi.run(App::stack);
    }

    public static void stack(Context ctx) {
        var sa = new Account("sa", AccountArgs.builder()
            .accountId("my-service-account")
            .displayName("A service account that only Jane can use")
            .build());

        var admin_account_iam = new IAMBinding("admin-account-iam", IAMBindingArgs.builder()
            .serviceAccountId(sa.name())
            .role("roles/iam.serviceAccountUser")
            .members("user:jane@example.com")
            .condition(IAMBindingConditionArgs.builder()
                .title("expires_after_2019_12_31")
                .description("Expiring at midnight of 2019-12-31")
                .expression("request.time < timestamp(\"2020-01-01T00:00:00Z\")")
                .build())
            .build());

    }
}

resources:
  sa:
    type: gcp:serviceaccount:Account
    properties:
      accountId: my-service-account
      displayName: A service account that only Jane can use
  admin-account-iam:
    type: gcp:serviceaccount:IAMBinding
    properties:
      serviceAccountId: ${sa.name}
      role: roles/iam.serviceAccountUser
      members:
        - user:jane@example.com
      condition:
        title: expires_after_2019_12_31
        description: Expiring at midnight of 2019-12-31
        expression: request.time < timestamp("2020-01-01T00:00:00Z")

The condition block attaches temporal or attribute-based restrictions to the binding. The expression uses CEL (Common Expression Language) to define when access is valid; here, access expires at midnight on 2020-01-01. The title and description provide human-readable context for audit logs and the console.

Allow service account impersonation

Service accounts often need to impersonate other service accounts to perform operations on their behalf.

import * as pulumi from "@pulumi/pulumi";
import * as gcp from "@pulumi/gcp";

const _default = gcp.compute.getDefaultServiceAccount({});
const sa = new gcp.serviceaccount.Account("sa", {
    accountId: "my-service-account",
    displayName: "A service account that Jane can use",
});
const admin_account_iam = new gcp.serviceaccount.IAMMember("admin-account-iam", {
    serviceAccountId: sa.name,
    role: "roles/iam.serviceAccountUser",
    member: "user:jane@example.com",
});
// Allow SA service account use the default GCE account
const gce_default_account_iam = new gcp.serviceaccount.IAMMember("gce-default-account-iam", {
    serviceAccountId: _default.then(_default => _default.name),
    role: "roles/iam.serviceAccountUser",
    member: pulumi.interpolate`serviceAccount:${sa.email}`,
});

import pulumi
import pulumi_gcp as gcp

default = gcp.compute.get_default_service_account()
sa = gcp.serviceaccount.Account("sa",
    account_id="my-service-account",
    display_name="A service account that Jane can use")
admin_account_iam = gcp.serviceaccount.IAMMember("admin-account-iam",
    service_account_id=sa.name,
    role="roles/iam.serviceAccountUser",
    member="user:jane@example.com")
# Allow SA service account use the default GCE account
gce_default_account_iam = gcp.serviceaccount.IAMMember("gce-default-account-iam",
    service_account_id=default.name,
    role="roles/iam.serviceAccountUser",
    member=sa.email.apply(lambda email: f"serviceAccount:{email}"))

package main

import (
	"fmt"

	"github.com/pulumi/pulumi-gcp/sdk/v9/go/gcp/compute"
	"github.com/pulumi/pulumi-gcp/sdk/v9/go/gcp/serviceaccount"
	"github.com/pulumi/pulumi/sdk/v3/go/pulumi"
)

func main() {
	pulumi.Run(func(ctx *pulumi.Context) error {
		_default, err := compute.GetDefaultServiceAccount(ctx, &compute.GetDefaultServiceAccountArgs{}, nil)
		if err != nil {
			return err
		}
		sa, err := serviceaccount.NewAccount(ctx, "sa", &serviceaccount.AccountArgs{
			AccountId:   pulumi.String("my-service-account"),
			DisplayName: pulumi.String("A service account that Jane can use"),
		})
		if err != nil {
			return err
		}
		_, err = serviceaccount.NewIAMMember(ctx, "admin-account-iam", &serviceaccount.IAMMemberArgs{
			ServiceAccountId: sa.Name,
			Role:             pulumi.String("roles/iam.serviceAccountUser"),
			Member:           pulumi.String("user:jane@example.com"),
		})
		if err != nil {
			return err
		}
		// Allow SA service account use the default GCE account
		_, err = serviceaccount.NewIAMMember(ctx, "gce-default-account-iam", &serviceaccount.IAMMemberArgs{
			ServiceAccountId: pulumi.String(_default.Name),
			Role:             pulumi.String("roles/iam.serviceAccountUser"),
			Member: sa.Email.ApplyT(func(email string) (string, error) {
				return fmt.Sprintf("serviceAccount:%v", email), nil
			}).(pulumi.StringOutput),
		})
		if err != nil {
			return err
		}
		return nil
	})
}

using System.Collections.Generic;
using System.Linq;
using Pulumi;
using Gcp = Pulumi.Gcp;

return await Deployment.RunAsync(() => 
{
    var @default = Gcp.Compute.GetDefaultServiceAccount.Invoke();

    var sa = new Gcp.ServiceAccount.Account("sa", new()
    {
        AccountId = "my-service-account",
        DisplayName = "A service account that Jane can use",
    });

    var admin_account_iam = new Gcp.ServiceAccount.IAMMember("admin-account-iam", new()
    {
        ServiceAccountId = sa.Name,
        Role = "roles/iam.serviceAccountUser",
        Member = "user:jane@example.com",
    });

    // Allow SA service account use the default GCE account
    var gce_default_account_iam = new Gcp.ServiceAccount.IAMMember("gce-default-account-iam", new()
    {
        ServiceAccountId = @default.Apply(@default => @default.Apply(getDefaultServiceAccountResult => getDefaultServiceAccountResult.Name)),
        Role = "roles/iam.serviceAccountUser",
        Member = sa.Email.Apply(email => $"serviceAccount:{email}"),
    });

});

package generated_program;

import com.pulumi.Context;
import com.pulumi.Pulumi;
import com.pulumi.core.Output;
import com.pulumi.gcp.compute.ComputeFunctions;
import com.pulumi.gcp.compute.inputs.GetDefaultServiceAccountArgs;
import com.pulumi.gcp.serviceaccount.Account;
import com.pulumi.gcp.serviceaccount.AccountArgs;
import com.pulumi.gcp.serviceaccount.IAMMember;
import com.pulumi.gcp.serviceaccount.IAMMemberArgs;
import java.util.List;
import java.util.ArrayList;
import java.util.Map;
import java.io.File;
import java.nio.file.Files;
import java.nio.file.Paths;

public class App {
    public static void main(String[] args) {
        Pulumi.run(App::stack);
    }

    public static void stack(Context ctx) {
        final var default = ComputeFunctions.getDefaultServiceAccount(GetDefaultServiceAccountArgs.builder()
            .build());

        var sa = new Account("sa", AccountArgs.builder()
            .accountId("my-service-account")
            .displayName("A service account that Jane can use")
            .build());

        var admin_account_iam = new IAMMember("admin-account-iam", IAMMemberArgs.builder()
            .serviceAccountId(sa.name())
            .role("roles/iam.serviceAccountUser")
            .member("user:jane@example.com")
            .build());

        // Allow SA service account use the default GCE account
        var gce_default_account_iam = new IAMMember("gce-default-account-iam", IAMMemberArgs.builder()
            .serviceAccountId(default_.name())
            .role("roles/iam.serviceAccountUser")
            .member(sa.email().applyValue(_email -> String.format("serviceAccount:%s", _email)))
            .build());

    }
}

resources:
  sa:
    type: gcp:serviceaccount:Account
    properties:
      accountId: my-service-account
      displayName: A service account that Jane can use
  admin-account-iam:
    type: gcp:serviceaccount:IAMMember
    properties:
      serviceAccountId: ${sa.name}
      role: roles/iam.serviceAccountUser
      member: user:jane@example.com
  # Allow SA service account use the default GCE account
  gce-default-account-iam:
    type: gcp:serviceaccount:IAMMember
    properties:
      serviceAccountId: ${default.name}
      role: roles/iam.serviceAccountUser
      member: serviceAccount:${sa.email}
variables:
  default:
    fn::invoke:
      function: gcp:compute:getDefaultServiceAccount
      arguments: {}

The member property uses the serviceAccount: prefix followed by the email address of the impersonating service account. This grants one service account permission to use another, enabling service-to-service delegation. The example shows both user-based access and service account impersonation for the same role.

Beyond these examples

These snippets focus on specific IAM binding features: role binding with member lists, conditional access with time constraints, and service account impersonation. They’re intentionally minimal rather than full access control systems.

The examples reference pre-existing infrastructure such as service accounts created in examples or referenced via data sources. They focus on configuring role bindings rather than provisioning the complete IAM hierarchy.

To keep things focused, common IAM patterns are omitted, including:

IAMPolicy for full policy replacement
IAMMember for single-member grants
Custom role definitions
Audit logging configuration

These omissions are intentional: the goal is to illustrate how each binding feature is wired, not provide drop-in access control modules. See the Service Account IAMBinding resource reference for all available configuration options.

Let's manage GCP Service Account IAM Bindings

Get started with Pulumi Cloud, then follow our quick setup guide to deploy this infrastructure.

Try Pulumi Cloud for FREE

Frequently Asked Questions

Resource Conflicts & Compatibility

What are the conflicts between IAM resource types?

You cannot use gcp.serviceaccount.IAMPolicy with gcp.serviceaccount.IAMBinding or gcp.serviceaccount.IAMMember, as they will conflict over policy management. Additionally, gcp.serviceaccount.IAMBinding and gcp.serviceaccount.IAMMember can only be used together if they target different roles.

Can I create multiple IAMBinding resources for the same role?

No, only one gcp.serviceaccount.IAMBinding can be used per role. If you need to add more members to a role, either include them in the existing IAMBinding or use gcp.serviceaccount.IAMMember resources instead.

What's the difference between IAMBinding and IAMMember?

IAMBinding is authoritative for a given role (replaces all members for that role), while IAMMember is non-authoritative (adds a single member without affecting others). Use IAMBinding to manage all members for a role, or IAMMember to add individual members.

Role & Member Configuration

What member identity formats are supported?

Six formats are supported:

allUsers - Anyone on the internet
allAuthenticatedUsers - Anyone with a Google account
user:{email} - Specific Google account (e.g., user:alice@gmail.com)
serviceAccount:{email} - Service account (e.g., serviceAccount:my-app@appspot.gserviceaccount.com)
group:{email} - Google group (e.g., group:admins@example.com)
domain:{domain} - G Suite domain (e.g., domain:example.com)

How do I reference a service account as a member?

Use the format serviceAccount:{email}, for example: member: pulumi.interpolate\serviceAccount:${sa.email}`` to grant a service account access to another service account.

What format do custom roles require?

Custom roles must use the format [projects|organizations]/{parent-name}/roles/{role-name}, for example: projects/my-project/roles/customRole or organizations/my-org/roles/customRole.

IAM Conditions

How do I add time-based access restrictions?

Use the condition property with title, description, and expression fields. For example, to expire access at a specific time: expression: "request.time < timestamp(\"2020-01-01T00:00:00Z\")".

Immutability & Updates

What properties are immutable after creation?

The role, serviceAccountId, and condition properties are immutable. Changing any of these will force resource replacement (destroy and recreate).

Using a different cloud?

Explore iam guides for other cloud providers:

AWS Guides Azure Guides