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: single-member role grants, multi-member role bindings, and complete policy replacement.

These resources reference existing workforce pools and IAM principals. They differ in how they manage role assignments: WorkforcePoolIamMember adds members incrementally, WorkforcePoolIamBinding replaces all members for a role, and WorkforcePoolIamPolicy replaces the entire policy. The examples are intentionally small. Combine them with your own workforce pool configuration and identity management.

Grant a role to a single member

Most IAM configurations start by granting a specific role to one user or service account, preserving other members who already have the same role.

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 one identity in the format “user:email@example.com” or “serviceAccount:name@project.iam.gserviceaccount.com”. The role property sets which permissions to grant. This non-authoritative resource adds the member without affecting others who already have the role.

Grant a role to multiple members at once

When multiple users or service accounts need the same permissions, binding them together ensures they’re managed as a group.

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 a list of identities, replacing any existing members for the specified role. This authoritative approach for the role means you control the complete member list. Other roles in the workforce pool’s IAM policy remain unchanged.

Replace the entire IAM policy

Some deployments require complete control over all roles and members, replacing any existing policy.

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 accepts a complete IAM policy document, typically from the getIAMPolicy data source. This authoritative resource replaces the entire policy, affecting all roles and members. It cannot be used alongside WorkforcePoolIamBinding or WorkforcePoolIamMember resources; they will conflict over policy state.

Beyond these examples

These snippets focus on specific IAM management approaches: single-member grants, multi-member role bindings, and complete policy replacement. They’re intentionally minimal rather than full identity federation deployments.

The examples reference pre-existing infrastructure such as workforce pools (by workforcePoolId) and IAM principals (users, service accounts, groups). They focus on granting permissions rather than creating the underlying identity infrastructure.

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

Conditional IAM bindings (condition property)
Custom role definitions
Federated identity principals
Policy data source for read-only access

These omissions are intentional: the goal is to illustrate how each IAM resource type manages permissions, not provide drop-in identity 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, preserving other roles in the policy. WorkforcePoolIamMember is non-authoritative, adding a single member to a role while preserving other members.

Which IAM resources can I use together?

WorkforcePoolIamPolicy cannot be used with WorkforcePoolIamBinding or WorkforcePoolIamMember as they will conflict. However, WorkforcePoolIamBinding and WorkforcePoolIamMember can be used together if they don’t grant privileges to the same role.

When should I use WorkforcePoolIamMember vs WorkforcePoolIamBinding?

Use WorkforcePoolIamMember to add a single member to a role without affecting other members. Use WorkforcePoolIamBinding when you want to authoritatively manage all members for a specific role.

Member Identity Formats

What member identity formats are supported?

Supported formats include allUsers, allAuthenticatedUsers, user:{email}, serviceAccount:{email}, group:{email}, domain:{domain}, projectOwner:{projectid}, projectEditor:{projectid}, projectViewer:{projectid}, and federated identities like principal://iam.googleapis.com/locations/global/workforcePools/example-contractors/subject/joe@example.com.

How do I grant access to all authenticated users?

Use the special identifier allAuthenticatedUsers as the member value to grant access to anyone authenticated with a Google account or service account.

How do I grant access to federated identities?

Use the principal identifier format: principal://iam.googleapis.com/locations/global/workforcePools/{pool-id}/subject/{subject-id}. Refer to the Principal identifiers documentation for valid configuration examples.

Custom Roles & Configuration

How do I specify a custom role?

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

Are location and workforcePoolId required?

Yes, both location and workforcePoolId are required and immutable. The location is used to find the parent resource to bind the IAM policy to.

Using a different cloud?

Explore security guides for other cloud providers:

AWS Guides Azure Guides