Principal identifiers

When you refer to a principal in an Identity and Access Management (IAM) policy, you needto use the correct identifier for the principal. The format of the identifierdepends on thetype of principal you want to refer to andthe type of policy you're writing.

This page lists the identifier formats for each policy type's supportedprincipal types.

Principal identifiers for allow policies

The following table describes the principal identifiers forallowpolicies, which use the IAMv1 API.

These identifiers are also used forPrivileged Access Manager entitlements.

Preview — Principal identifiers for all service accounts in a project, folder, or organization

This feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of theService Specific Terms. Pre-GA features are available "as is" and might have limited support. For more information, see thelaunch stage descriptions.

Principal typeIdentifier
Google Account

user:USER_EMAIL_ADDRESS

Example:user:alex@example.com

Service account

serviceAccount:SA_EMAIL_ADDRESS

Example:serviceAccount:my-service-account@my-project.iam.gserviceaccount.com

All service accounts in a project, folder, or organization

principalSet://cloudresourcemanager.googleapis.com/RESOURCE_TYPE/RESOURCE_NUMBER/type/ServiceAccount

Example for all service accounts in a project:principalSet://cloudresourcemanager.googleapis.com/projects/123456789012/type/ServiceAccount

Example for all service accounts in all projects in a folder:principalSet://cloudresourcemanager.googleapis.com/folders/123456789012/type/ServiceAccount

Example for all service accounts in all projects in an organization:principalSet://cloudresourcemanager.googleapis.com/organizations/123456789012/type/ServiceAccount

Note: Moving projects into or out of a folder or organization changes the service accounts included in this principal set. For example, if you move a project out of a folder or organization, then this principal set no longer includes that project's service accounts.
Google group

group:GROUP_EMAIL_ADDRESS

Example:group:my-group@example.com

Google domain

domain:DOMAIN

Example:domain:example.com

All usersallUsers
All authenticated usersallAuthenticatedUsers
Built-in resource identities Only available for supported resources. The format varies depending on the resource. SeeResources with built-in identities for details.
Single identity in a workforce identity pool principal://iam.googleapis.com/locations/global/workforcePools/POOL_ID/subject/SUBJECT_ATTRIBUTE_VALUE

Example:principal://iam.googleapis.com/locations/global/workforcePools/altostrat-contractors/subject/raha@altostrat.com

All workforce identities in a group principalSet://iam.googleapis.com/locations/global/workforcePools/POOL_ID/group/GROUP_ID

Example using a group email:principalSet://iam.googleapis.com/locations/global/workforcePools/altostrat-contractors/group/administrators-group@altostrat.com

Example using a group UUID:principalSet://iam.googleapis.com/locations/global/workforcePools/altostrat-contractors/group/abcdefgh-0123-0123-abcdef

All workforce identities with a specific attribute valueprincipalSet://iam.googleapis.com/locations/global/workforcePools/POOL_ID/attribute.ATTRIBUTE_NAME/ATTRIBUTE_VALUE

Example:principalSet://iam.googleapis.com/locations/global/workforcePools/altostrat-contractors/attribute.department/administration

All identities in a workforce identity poolprincipalSet://iam.googleapis.com/locations/global/workforcePools/POOL_ID/*

Example:principalSet://iam.googleapis.com/locations/global/workforcePools/altostrat-contractors/*

Single identity in a workload identity poolprincipal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/SUBJECT_ATTRIBUTE_VALUE
Workload identity pool groupprincipalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/group/GROUP_ID
All identities in a workload identity pool with a certain attributeprincipalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.ATTRIBUTE_NAME/ATTRIBUTE_VALUE
All identities in a workload identity poolprincipalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/*
All GKE Pods that use a specific Kubernetes service account

By service account name:principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/subject/ns/NAMESPACE/sa/KUBERNETES_SERVICE_ACCOUNT

By service account ID:principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/kubernetes.serviceaccount.uid/SERVICEACCOUNT_ID

Legacy format:serviceAccount:PROJECT_ID.svc.id.goog[NAMESPACE/KUBERNETES_SERVICE_ACCOUNT]

All GKE Pods in a Kubernetes namespace, regardless of service account or clusterprincipalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/namespace/NAMESPACE
All GKE Pods in a specific clusterprincipalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/kubernetes.cluster/https://container.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/clusters/CLUSTER_NAME
Deleted Google Account1

deleted:user:USER_EMAIL_ADDRESS?uid=UNIQUE_ID

Example:deleted:user:alex@example.com?uid=123456789012345678901

Deleted service account1

deleted:serviceAccount:SA_EMAIL_ADDRESS?uid=UNIQUE_ID

Example:deleted:serviceAccount:my-service-account@my-project.iam.gserviceaccount.com?uid=123456789012345678901

Deleted Google group1

deleted:group:GROUP_EMAIL_ADDRESS?uid=UNIQUE_ID

Example:deleted:group:my-group@example.com?uid=123456789012345678901

Deleted single identity in a workforce identity pool1

deleted:principal://iam.googleapis.com/locations/global/workforcePools/POOL_ID/subject/SUBJECT_ATTRIBUTE_VALUE

Example:deleted:principal://iam.googleapis.com/locations/global/workforcePools/my-pool-id/subject/my-subject-attribute-value

1 Don't add deleted principals when creating or modifying policies.

Principal identifiers for deny policies

The following table describes the principal identifiers fordenypolicies, which use the IAMv2 API.

Preview — Principal identifiers for all service accounts in a project, folder, or organization

This feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of theService Specific Terms. Pre-GA features are available "as is" and might have limited support. For more information, see thelaunch stage descriptions.

Preview — Principal identifiers for all service agents associated with a project, folder, or organization

This feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of theService Specific Terms. Pre-GA features are available "as is" and might have limited support. For more information, see thelaunch stage descriptions.

Principal typeIdentifier
Google Account

principal://goog/subject/USER_EMAIL_ADDRESS

Example:principal://goog/subject/alex@example.com

Service account

principal://iam.googleapis.com/projects/-/serviceAccounts/SA_EMAIL_ADDRESS

Example:principal://iam.googleapis.com/projects/-/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com

All service accounts in a project, folder, or organization

principalSet://cloudresourcemanager.googleapis.com/RESOURCE_TYPE/RESOURCE_NUMBER/type/ServiceAccount

Example for all service accounts in a project:principalSet://cloudresourcemanager.googleapis.com/projects/123456789012/type/ServiceAccount

Example for all service accounts in all projects in a folder:principalSet://cloudresourcemanager.googleapis.com/folders/123456789012/type/ServiceAccount

Example for all service accounts in all projects in an organization:principalSet://cloudresourcemanager.googleapis.com/organizations/123456789012/type/ServiceAccount

Note: Moving projects into or out of a folder or organization changes the service accounts included in this principal set. For example, if you move a project out of a folder or organization, then this principal set no longer includes that project's service accounts.
Allservice agents associated with a project, folder, or organization

principalSet://cloudresourcemanager.googleapis.com/RESOURCE_TYPE/RESOURCE_NUMBER/type/ServiceAgent

Example for all service agents associated with a project or its descendants:principalSet://cloudresourcemanager.googleapis.com/projects/123456789012/type/ServiceAgent

Example for all service agents associated with a folder or its descendants:principalSet://cloudresourcemanager.googleapis.com/folders/123456789012/type/ServiceAgent

Example for all service agents associated with an organization or its descendants:principalSet://cloudresourcemanager.googleapis.com/organizations/123456789012/type/ServiceAgent

Warning: Don't deny permissions for service agents—doing so might cause some Google Cloud services to stop working properly. Instead, use these principal sets to exempt service agents from deny rules.Note: Moving projects into or out of a folder or organization changes the service agents included in this principal set. For example, if you move a project out of a folder or organization, then this principal set no longer includes that project's service agents.
Google group

principalSet://goog/group/GROUP_EMAIL_ADDRESS

Example:principalSet://goog/group/my-group@example.com

All principalsprincipalSet://goog/public:all
All principals in a Cloud Identity account (domain)

principalSet://goog/cloudIdentityCustomerId/CLOUD_IDENTITY_CUSTOMER_ID1

Example:principalSet://goog/cloudIdentityCustomerId/C01Abc35

Single identity in a workforce identity pool principal://iam.googleapis.com/locations/global/workforcePools/POOL_ID/subject/SUBJECT_ATTRIBUTE_VALUE

Example:principal://iam.googleapis.com/locations/global/workforcePools/altostrat-contractors/subject/raha@altostrat.com

All workforce identities in a group principalSet://iam.googleapis.com/locations/global/workforcePools/POOL_ID/group/GROUP_ID

Example using a group email:principalSet://iam.googleapis.com/locations/global/workforcePools/altostrat-contractors/group/administrators-group@altostrat.com

Example using a group UUID:principalSet://iam.googleapis.com/locations/global/workforcePools/altostrat-contractors/group/abcdefgh-0123-0123-abcdef

All workforce identities with a specific attribute valueprincipalSet://iam.googleapis.com/locations/global/workforcePools/POOL_ID/attribute.ATTRIBUTE_NAME/ATTRIBUTE_VALUE

Example:principalSet://iam.googleapis.com/locations/global/workforcePools/altostrat-contractors/attribute.department/administration

All identities in a workforce identity poolprincipalSet://iam.googleapis.com/locations/global/workforcePools/POOL_ID/*

Example:principalSet://iam.googleapis.com/locations/global/workforcePools/altostrat-contractors/*

Single identity in a workload identity poolprincipal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/SUBJECT_ATTRIBUTE_VALUE
Workload identity pool groupprincipalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/group/GROUP_ID
All identities in a workload identity pool with a certain attributeprincipalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.ATTRIBUTE_NAME/ATTRIBUTE_VALUE
All identities in a workload identity poolprincipalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/*
Deleted Google Account2

deleted:principal://goog/subject/USER_EMAIL_ADDRESS?uid=UNIQUE_ID

Example:deleted:principal://goog/subject/alex@example.com?uid=123456789012345678901

Deleted service account2

deleted:principal://iam.googleapis.com/projects/-/serviceAccounts/SA_EMAIL_ADDRESS?uid=UNIQUE_ID

Example:deleted:principal://iam.googleapis.com/projects/-/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com?uid=123456789012345678901

Deleted Google group2

deleted:principalSet://goog/group/GROUP_EMAIL_ADDRESS?uid=UNIQUE_ID

Example:deleted:principalSet://goog/group/my-group@example.com?uid=123456789012345678901

Deleted single identity in a workforce identity pool2

deleted:principal://iam.googleapis.com/locations/global/workforcePools/POOL_ID/subject/SUBJECT_ATTRIBUTE_VALUE

Example:deleted:principal://iam.googleapis.com/locations/global/workforcePools/my-pool-id/subject/my-subject-attribute-value

1Learn how to find your Cloud Identity customerID.

2 Don't add deleted principals when creating or modifying policies.

Principal identifiers for principal access boundary policy bindings

The following table describes the identifiers for the principal sets that youcan use inprincipal access boundary (PAB) policy bindings.Principal access boundary policy bindings which use the IAMv3API.

To learn which principals are included in each of these principal sets, seeSupported principal sets.

Principal typeIdentifier
Workforce identity pool

//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID

Example://iam.googleapis.com/locations/global/workforcePools/example-workforce-pool

Workload identity pool

//iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/WORKLOAD_POOL_ID

Example://iam.googleapis.com/projects/123456789012/locations/global/workloadIdentityPools/example-workload-pool

Google Workspace domain

//iam.googleapis.com/locations/global/workspace/CUSTOMER_ID1

Example://iam.googleapis.com/locations/global/workspace/C01Abc35

Project's principal set

//cloudresourcemanager.googleapis.com/projects/PROJECT_ID

Example://cloudresourcemanager.googleapis.com/projects/example-project

Folder's principal set

//cloudresourcemanager.googleapis.com/folders/FOLDER_ID

Example://cloudresourcemanager.googleapis.com/folders/0123456789012

Organization's principal set

//cloudresourcemanager.googleapis.com/organizations/ORGANIZATION_ID

Example://cloudresourcemanager.googleapis.com/organizations/0123456789012

1Learn how to find your Cloud Identity customerID.

Principal types for access policies

The following table describes the principal identifiers that you can use inaccess policies. You can use access policies to control access toEventarc resources. For more information, see theEventarcdocumentation.

Preview — Principal identifiers for all service accounts in a project, folder, or organization

This feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of theService Specific Terms. Pre-GA features are available "as is" and might have limited support. For more information, see thelaunch stage descriptions.

Principal typeIdentifier
User

principal://goog/subject/USER_EMAIL_ADDRESS

Example:principal://goog/subject/alex@example.com

Service account

principal://iam.googleapis.com/projects/-/serviceAccounts/SA_EMAIL_ADDRESS

Example:principal://iam.googleapis.com/projects/-/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com

All service accounts in a project, folder, or organization

principalSet://cloudresourcemanager.googleapis.com/RESOURCE_TYPE/RESOURCE_NUMBER/type/ServiceAccount

Example for all service accounts in a project:principalSet://cloudresourcemanager.googleapis.com/projects/123456789012/type/ServiceAccount

Example for all service accounts in all projects in a folder:principalSet://cloudresourcemanager.googleapis.com/folders/123456789012/type/ServiceAccount

Example for all service accounts in all projects in an organization:principalSet://cloudresourcemanager.googleapis.com/organizations/123456789012/type/ServiceAccount

Note: Moving projects into or out of a folder or organization changes the service accounts included in this principal set. For example, if you move a project out of a folder or organization, then this principal set no longer includes that project's service accounts.
Group

principalSet://goog/group/GROUP_EMAIL_ADDRESS

Example:principalSet://goog/group/my-group@example.com

All principals1principalSet://goog/public:all
All principals in a Cloud Identity account (domain)

principalSet://goog/cloudIdentityCustomerId/CLOUD_IDENTITY_CUSTOMER_ID1

Example:principalSet://goog/cloudIdentityCustomerId/C01Abc35

1 This value can only be used in access policies with theDENYaction.

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-12-15 UTC.