Manage GCP Workforce Pool IAM Members

The gcp:iam/workforcePoolIamMember:WorkforcePoolIamMember resource, part of the Pulumi GCP provider, grants IAM roles to members on workforce pools, controlling who can manage or use workforce identity federation. This guide focuses on three capabilities: non-authoritative single-member grants, authoritative multi-member role bindings, and complete policy replacement.

These three resources reference existing workforce pools and differ in how they modify IAM policies. WorkforcePoolIamMember adds members incrementally without affecting others. WorkforcePoolIamBinding replaces all members for one role while preserving other roles. WorkforcePoolIamPolicy replaces the entire IAM policy. The examples are intentionally small. Combine them with your own workforce pool infrastructure and identity management strategy.

Grant a role to a single member non-authoritatively

When you need to add one person or service account without affecting existing permissions, WorkforcePoolIamMember provides incremental access control.

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

const member = new gcp.iam.WorkforcePoolIamMember("member", {
    location: example.location,
    workforcePoolId: example.workforcePoolId,
    role: "roles/iam.workforcePoolAdmin",
    member: "user:jane@example.com",
});

import pulumi
import pulumi_gcp as gcp

member = gcp.iam.WorkforcePoolIamMember("member",
    location=example["location"],
    workforce_pool_id=example["workforcePoolId"],
    role="roles/iam.workforcePoolAdmin",
    member="user:jane@example.com")

package main

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

func main() {
	pulumi.Run(func(ctx *pulumi.Context) error {
		_, err := iam.NewWorkforcePoolIamMember(ctx, "member", &iam.WorkforcePoolIamMemberArgs{
			Location:        pulumi.Any(example.Location),
			WorkforcePoolId: pulumi.Any(example.WorkforcePoolId),
			Role:            pulumi.String("roles/iam.workforcePoolAdmin"),
			Member:          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 member = new Gcp.Iam.WorkforcePoolIamMember("member", new()
    {
        Location = example.Location,
        WorkforcePoolId = example.WorkforcePoolId,
        Role = "roles/iam.workforcePoolAdmin",
        Member = "user:jane@example.com",
    });

});

package generated_program;

import com.pulumi.Context;
import com.pulumi.Pulumi;
import com.pulumi.core.Output;
import com.pulumi.gcp.iam.WorkforcePoolIamMember;
import com.pulumi.gcp.iam.WorkforcePoolIamMemberArgs;
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 member = new WorkforcePoolIamMember("member", WorkforcePoolIamMemberArgs.builder()
            .location(example.location())
            .workforcePoolId(example.workforcePoolId())
            .role("roles/iam.workforcePoolAdmin")
            .member("user:jane@example.com")
            .build());

    }
}

resources:
  member:
    type: gcp:iam:WorkforcePoolIamMember
    properties:
      location: ${example.location}
      workforcePoolId: ${example.workforcePoolId}
      role: roles/iam.workforcePoolAdmin
      member: user:jane@example.com

The member property specifies who receives access using formats like “user:jane@example.com” or “serviceAccount:app@project.iam.gserviceaccount.com”. The role property defines what they can do. This resource adds the member without removing others who already have the same role, making it safe for collaborative management where multiple teams grant access independently.

Grant a role to multiple members authoritatively

When you need to define the complete list of who has a specific role, WorkforcePoolIamBinding replaces all members for that role while preserving other roles.

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

const binding = new gcp.iam.WorkforcePoolIamBinding("binding", {
    location: example.location,
    workforcePoolId: example.workforcePoolId,
    role: "roles/iam.workforcePoolAdmin",
    members: ["user:jane@example.com"],
});

import pulumi
import pulumi_gcp as gcp

binding = gcp.iam.WorkforcePoolIamBinding("binding",
    location=example["location"],
    workforce_pool_id=example["workforcePoolId"],
    role="roles/iam.workforcePoolAdmin",
    members=["user:jane@example.com"])

package main

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

func main() {
	pulumi.Run(func(ctx *pulumi.Context) error {
		_, err := iam.NewWorkforcePoolIamBinding(ctx, "binding", &iam.WorkforcePoolIamBindingArgs{
			Location:        pulumi.Any(example.Location),
			WorkforcePoolId: pulumi.Any(example.WorkforcePoolId),
			Role:            pulumi.String("roles/iam.workforcePoolAdmin"),
			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 binding = new Gcp.Iam.WorkforcePoolIamBinding("binding", new()
    {
        Location = example.Location,
        WorkforcePoolId = example.WorkforcePoolId,
        Role = "roles/iam.workforcePoolAdmin",
        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.iam.WorkforcePoolIamBinding;
import com.pulumi.gcp.iam.WorkforcePoolIamBindingArgs;
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 binding = new WorkforcePoolIamBinding("binding", WorkforcePoolIamBindingArgs.builder()
            .location(example.location())
            .workforcePoolId(example.workforcePoolId())
            .role("roles/iam.workforcePoolAdmin")
            .members("user:jane@example.com")
            .build());

    }
}

resources:
  binding:
    type: gcp:iam:WorkforcePoolIamBinding
    properties:
      location: ${example.location}
      workforcePoolId: ${example.workforcePoolId}
      role: roles/iam.workforcePoolAdmin
      members:
        - user:jane@example.com

The members property takes an array of identities. Unlike WorkforcePoolIamMember, this resource is authoritative for the specified role: it replaces the member list entirely. If another process grants the same role to different members, this binding will remove them on the next update. Other roles on the workforce pool remain untouched.

Replace the entire IAM policy authoritatively

When you need complete control over all roles and members, WorkforcePoolIamPolicy replaces the entire IAM policy in one operation.

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

const admin = gcp.organizations.getIAMPolicy({
    bindings: [{
        role: "roles/iam.workforcePoolAdmin",
        members: ["user:jane@example.com"],
    }],
});
const policy = new gcp.iam.WorkforcePoolIamPolicy("policy", {
    location: example.location,
    workforcePoolId: example.workforcePoolId,
    policyData: admin.then(admin => admin.policyData),
});

import pulumi
import pulumi_gcp as gcp

admin = gcp.organizations.get_iam_policy(bindings=[{
    "role": "roles/iam.workforcePoolAdmin",
    "members": ["user:jane@example.com"],
}])
policy = gcp.iam.WorkforcePoolIamPolicy("policy",
    location=example["location"],
    workforce_pool_id=example["workforcePoolId"],
    policy_data=admin.policy_data)

package main

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

func main() {
	pulumi.Run(func(ctx *pulumi.Context) error {
		admin, err := organizations.LookupIAMPolicy(ctx, &organizations.LookupIAMPolicyArgs{
			Bindings: []organizations.GetIAMPolicyBinding{
				{
					Role: "roles/iam.workforcePoolAdmin",
					Members: []string{
						"user:jane@example.com",
					},
				},
			},
		}, nil)
		if err != nil {
			return err
		}
		_, err = iam.NewWorkforcePoolIamPolicy(ctx, "policy", &iam.WorkforcePoolIamPolicyArgs{
			Location:        pulumi.Any(example.Location),
			WorkforcePoolId: pulumi.Any(example.WorkforcePoolId),
			PolicyData:      pulumi.String(admin.PolicyData),
		})
		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 admin = Gcp.Organizations.GetIAMPolicy.Invoke(new()
    {
        Bindings = new[]
        {
            new Gcp.Organizations.Inputs.GetIAMPolicyBindingInputArgs
            {
                Role = "roles/iam.workforcePoolAdmin",
                Members = new[]
                {
                    "user:jane@example.com",
                },
            },
        },
    });

    var policy = new Gcp.Iam.WorkforcePoolIamPolicy("policy", new()
    {
        Location = example.Location,
        WorkforcePoolId = example.WorkforcePoolId,
        PolicyData = admin.Apply(getIAMPolicyResult => getIAMPolicyResult.PolicyData),
    });

});

package generated_program;

import com.pulumi.Context;
import com.pulumi.Pulumi;
import com.pulumi.core.Output;
import com.pulumi.gcp.organizations.OrganizationsFunctions;
import com.pulumi.gcp.organizations.inputs.GetIAMPolicyArgs;
import com.pulumi.gcp.iam.WorkforcePoolIamPolicy;
import com.pulumi.gcp.iam.WorkforcePoolIamPolicyArgs;
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 admin = OrganizationsFunctions.getIAMPolicy(GetIAMPolicyArgs.builder()
            .bindings(GetIAMPolicyBindingArgs.builder()
                .role("roles/iam.workforcePoolAdmin")
                .members("user:jane@example.com")
                .build())
            .build());

        var policy = new WorkforcePoolIamPolicy("policy", WorkforcePoolIamPolicyArgs.builder()
            .location(example.location())
            .workforcePoolId(example.workforcePoolId())
            .policyData(admin.policyData())
            .build());

    }
}

resources:
  policy:
    type: gcp:iam:WorkforcePoolIamPolicy
    properties:
      location: ${example.location}
      workforcePoolId: ${example.workforcePoolId}
      policyData: ${admin.policyData}
variables:
  admin:
    fn::invoke:
      function: gcp:organizations:getIAMPolicy
      arguments:
        bindings:
          - role: roles/iam.workforcePoolAdmin
            members:
              - user:jane@example.com

The policyData property comes from the getIAMPolicy data source, which constructs a complete policy document from bindings. Each binding specifies a role and its members. This resource is the most authoritative: it replaces every role and member on the workforce pool. It cannot coexist with WorkforcePoolIamBinding or WorkforcePoolIamMember resources on the same pool, as they would conflict over policy ownership.

Beyond these examples

These snippets focus on specific IAM management features: incremental vs authoritative IAM management, single-member and multi-member role grants, and policy-level IAM replacement. They’re intentionally minimal rather than full identity federation deployments.

The examples reference pre-existing infrastructure such as workforce pools created separately. They focus on IAM configuration rather than provisioning the pools themselves.

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

Conditional IAM bindings (condition property)
Custom role definitions and formatting
Federated identity principal formats
Resource compatibility constraints (Policy vs Binding/Member)

These omissions are intentional: the goal is to illustrate how each IAM resource type is wired, not provide drop-in access control modules. See the WorkforcePoolIamMember resource reference for all available configuration options.

Let's manage GCP Workforce Pool IAM Members

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

Try Pulumi Cloud for FREE

Frequently Asked Questions

Resource Selection & Conflicts

What's the difference between WorkforcePoolIamPolicy, WorkforcePoolIamBinding, and WorkforcePoolIamMember?

WorkforcePoolIamPolicy is authoritative and replaces the entire IAM policy. WorkforcePoolIamBinding is authoritative for a specific role, replacing all members for that role while preserving other roles. WorkforcePoolIamMember is non-authoritative, adding a single member to a role without affecting other members.

Can I use WorkforcePoolIamPolicy with WorkforcePoolIamBinding or WorkforcePoolIamMember?

No, WorkforcePoolIamPolicy cannot be used alongside WorkforcePoolIamBinding or WorkforcePoolIamMember because they will conflict over the IAM policy configuration.

Can I use WorkforcePoolIamBinding and WorkforcePoolIamMember together?

Yes, but only if they grant different roles. Using both resources for the same role will cause conflicts.

Configuration & Formats

How do I specify a custom role?

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

What member identity formats are supported?

Supported formats include:

allUsers or allAuthenticatedUsers for public/authenticated access
user:{email}, serviceAccount:{email}, group:{email} for specific identities
domain:{domain} for G Suite domains
projectOwner:{projectid}, projectEditor:{projectid}, projectViewer:{projectid} for project roles
Federated identities like principal://iam.googleapis.com/locations/global/workforcePools/example-contractors/subject/joe@example.com

Immutability & Lifecycle

Can I change the role, member, or location after creation?

No, all properties (location, workforcePoolId, role, member, condition) are immutable and cannot be changed after the resource is created.

Using a different cloud?

Explore security guides for other cloud providers:

AWS Guides Azure Guides