When you refer to a principal in an Identity and Access Management (IAM) policy, you need
to use the correct identifier for the principal. The format of the identifier
depends on the type of principal you want to refer to and
the type of policy you're writing.
This page lists the identifier formats for each policy type's supported
principal types.
Principal identifiers for allow policies
The following table describes the principal identifiers for allow
policies, which use the IAM v1 API.
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
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 value
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
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
All service agents associated with a project, folder, or organization
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
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 value
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 you
can use in principal access boundary (PAB) policy bindings.
Principal access boundary policy bindings which use the IAM v3
API.
To learn which principals are included in each of these principal sets, see
Supported principal sets.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-08-28 UTC."],[[["\u003cp\u003eThis document provides the correct identifier formats for principals used in Identity and Access Management (IAM) policies, varying based on the principal type and policy in question.\u003c/p\u003e\n"],["\u003cp\u003eThe identifiers for principals in allow policies (IAM \u003ccode\u003ev1\u003c/code\u003e API) are used for Privileged Access Manager entitlements and VPC Service Controls ingress and egress rules, including users, service accounts, groups, domains, and different workforce or workload identities.\u003c/p\u003e\n"],["\u003cp\u003eDeny policies (IAM \u003ccode\u003ev2\u003c/code\u003e API) use distinct principal identifiers, which cover users, service accounts, groups, all principals, domain-wide principals, and various workforce and workload identities, as well as deleted entities.\u003c/p\u003e\n"],["\u003cp\u003ePrincipal access boundary (PAB) policy bindings (IAM \u003ccode\u003ev3\u003c/code\u003e API) define identifiers for principal sets like workforce identity pools, workload identity pools, Google Workspace domains, and project, folder, or organization-level principal sets.\u003c/p\u003e\n"],["\u003cp\u003eDeleted principals, including users, service accounts, and groups, have a specific identifier format with a unique ID suffix, but should not be added when creating or modifying policies.\u003c/p\u003e\n"]]],[],null,["# Principal identifiers\n\nWhen you refer to a principal in an Identity and Access Management (IAM) policy, you need\nto use the correct identifier for the principal. The format of the identifier\ndepends on the [type of principal](/iam/docs/principals-overview#principal-types) you want to refer to and\nthe type of policy you're writing.\n\nThis page lists the identifier formats for each policy type's supported\nprincipal types.\n\nPrincipal identifiers for allow policies\n----------------------------------------\n\nThe following table describes the principal identifiers for [allow\npolicies](/iam/docs/allow-policies), which use the IAM `v1` API.\n\nThese identifiers are also used for [Privileged Access Manager entitlements](/iam/docs/pam-overview).\n\n\n| **Preview\n| --- Principal identifiers for all service accounts in a project, folder, or organization**\n|\n|\n| This feature is subject to the \"Pre-GA Offerings Terms\" in the General Service Terms section\n| of the [Service Specific Terms](/terms/service-terms#1).\n|\n| Pre-GA features are available \"as is\" and might have limited support.\n|\n| For more information, see the\n| [launch stage descriptions](/products#product-launch-stages).\n\n\u003cbr /\u003e\n\n^1^ Don't add deleted principals when creating or modifying policies.\n\nPrincipal identifiers for deny policies\n---------------------------------------\n\nThe following table describes the principal identifiers for [deny\npolicies](/iam/docs/deny-overview), which use the IAM `v2` API.\n\n\n| **Preview\n| --- Principal identifiers for all service accounts in a project, folder, or organization**\n|\n|\n| This feature is subject to the \"Pre-GA Offerings Terms\" in the General Service Terms section\n| of the [Service Specific Terms](/terms/service-terms#1).\n|\n| Pre-GA features are available \"as is\" and might have limited support.\n|\n| For more information, see the\n| [launch stage descriptions](/products#product-launch-stages).\n|\n| **Preview\n| --- Principal identifiers for all service agents associated with a project, folder, or organization**\n|\n|\n| This feature is subject to the \"Pre-GA Offerings Terms\" in the General Service Terms section\n| of the [Service Specific Terms](/terms/service-terms#1).\n|\n| Pre-GA features are available \"as is\" and might have limited support.\n|\n| For more information, see the\n| [launch stage descriptions](/products#product-launch-stages).\n\n\u003cbr /\u003e\n\n^1^ [Learn how to find your Cloud Identity customer\nID](https://support.google.com/cloudidentity/answer/10070793).\n\n^2^ Don't add deleted principals when creating or modifying policies.\n\nPrincipal identifiers for principal access boundary policy bindings\n-------------------------------------------------------------------\n\nThe following table describes the identifiers for the principal sets that you\ncan use in [principal access boundary (PAB) policy bindings](/iam/docs/principal-access-boundary-policies).\nPrincipal access boundary policy bindings which use the IAM `v3`\nAPI.\n\nTo learn which principals are included in each of these principal sets, see\n[Supported principal sets](/iam/docs/principal-access-boundary-policies#principal-sets).\n\n^1^ [Learn how to find your Cloud Identity customer\nID](https://support.google.com/cloudidentity/answer/10070793)."]]
