Principal identifiers

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 which version of the API you're using.

This page lists the identifier formats for each supported principal type for all API versions.

Note: For allow policies, you use the IAM v1 API. For deny policies, you use the IAM v2 API.

IAM v1 API

The following table describes the principal type identifiers for the IAM v1 API.

Principal type	Identifier
User	user:USER_EMAIL_ADDRESS Example: user:[e-mail]
Service account	serviceAccount:SA_EMAIL_ADDRESS Example: serviceAccount:[e-mail]
Group	group:GROUP_EMAIL_ADDRESS Example: group:[e-mail]
Domain	domain:DOMAIN Example: domain:example.com
All users	allUsers
All authenticated users	allAuthenticatedUsers
Built-in resource identities	Only available for supported resources. The format varies depending on the resource. See Resources 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
All workforce identities in a group	principalSet://iam.googleapis.com/locations/global/workforcePools/POOL_ID/group/GROUP_ID
All workforce identities with a specific attribute value	principalSet://iam.googleapis.com/locations/global/workforcePools/POOL_ID/attribute.ATTRIBUTE_NAME/ATTRIBUTE_VALUE
All identities in a workforce identity pool	principalSet://iam.googleapis.com/locations/global/workforcePools/POOL_ID/*
Single identity in a workload identity pool	principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/SUBJECT_ATTRIBUTE_VALUE
Workload identity pool group	principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/group/GROUP_ID
All identities in a workload identity pool with a certain attribute	principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.ATTRIBUTE_NAME/ATTRIBUTE_VALUE
All identities in a workload identity pool	principalSet://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 cluster	principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/namespace/NAMESPACE
All GKE Pods in a specific cluster	principalSet://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 user^1	deleted:user:USER_EMAIL_ADDRESS?uid=UNIQUE_ID Example: deleted:user:[e-mail]?uid=123456789012345678901
Deleted service account^1	deleted:serviceAccount:SA_EMAIL_ADDRESS?uid=UNIQUE_ID Example: deleted:serviceAccount:[e-mail]?uid=123456789012345678901
Deleted group^1	deleted:group:GROUP_EMAIL_ADDRESS?uid=UNIQUE_ID Example: deleted:group:[e-mail]?uid=123456789012345678901
Deleted single identity in a workforce identity pool^1	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

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

IAM v2 API

The following table describes the principal type identifiers for the IAM v2 API.

Principal type	Identifier
User	principal://goog/subject/USER_EMAIL_ADDRESS Example: principal://goog/subject/[e-mail]
Service account	principal://iam.googleapis.com/projects/-/serviceAccounts/SA_EMAIL_ADDRESS Example: principal://iam.googleapis.com/projects/-/serviceAccounts/[e-mail]
Group	principalSet://goog/group/GROUP_EMAIL_ADDRESS Example: principalSet://goog/group/[e-mail]
All principals	principalSet://goog/public:all
All principals in a Cloud Identity account (domain)	principalSet://goog/cloudIdentityCustomerId/CLOUD_IDENTITY_CUSTOMER_ID^1 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
All workforce identities in a group	principalSet://iam.googleapis.com/locations/global/workforcePools/POOL_ID/group/GROUP_ID
All workforce identities with a specific attribute value	principalSet://iam.googleapis.com/locations/global/workforcePools/POOL_ID/attribute.ATTRIBUTE_NAME/ATTRIBUTE_VALUE
All identities in a workforce identity pool	principalSet://iam.googleapis.com/locations/global/workforcePools/POOL_ID/*
Single identity in a workload identity pool	principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/SUBJECT_ATTRIBUTE_VALUE
Workload identity pool group	principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/group/GROUP_ID
All identities in a workload identity pool with a certain attribute	principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.ATTRIBUTE_NAME/ATTRIBUTE_VALUE
All identities in a workload identity pool	principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/*
Deleted user^2	deleted:principal://goog/subject/USER_EMAIL_ADDRESS?uid=UNIQUE_ID Example: deleted:principal://goog/subject/[e-mail]?uid=123456789012345678901
Deleted service account^2	deleted:principal://iam.googleapis.com/projects/-/serviceAccounts/SA_EMAIL_ADDRESS?uid=UNIQUE_ID Example: deleted:principal://iam.googleapis.com/projects/-/serviceAccounts/[e-mail]?uid=123456789012345678901
Deleted group^2	deleted:principalSet://goog/group/GROUP_EMAIL_ADDRESS?uid=UNIQUE_ID Example: deleted:principalSet://goog/group/[e-mail]?uid=123456789012345678901
Deleted single identity in a workforce identity pool^2	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

¹ Learn how to find your Cloud Identity customer ID.

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