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.

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:[email protected]
Service account

serviceAccount:SA_EMAIL_ADDRESS

Example: serviceAccount:[email protected]
Group

group:GROUP_EMAIL_ADDRESS

Example: group:[email protected]
Domain

domain:DOMAIN

Example: domain:example.com
All users allUsers
All authenticated users allAuthenticatedUsers
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 user1

deleted:user:USER_EMAIL_ADDRESS?uid=UNIQUE_ID

Example: deleted:user:[email protected]?uid=123456789012345678901
Deleted service account1

deleted:serviceAccount:SA_EMAIL_ADDRESS?uid=UNIQUE_ID

Example: deleted:serviceAccount:[email protected]?uid=123456789012345678901
Deleted group1

deleted:group:GROUP_EMAIL_ADDRESS?uid=UNIQUE_ID

Example: deleted:group:[email protected]?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.

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/[email protected]
Service account

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

Example: principal://iam.googleapis.com/projects/-/serviceAccounts/[email protected]
Group

principalSet://goog/group/GROUP_EMAIL_ADDRESS

Example: principalSet://goog/group/[email protected]
All principals principalSet://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
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 user2

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

Example: deleted:principal://goog/subject/[email protected]?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/[email protected]?uid=123456789012345678901
Deleted group2

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

Example: deleted:principalSet://goog/group/[email protected]?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

1 Learn how to find your Cloud Identity customer ID.

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