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 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.

These identifiers are also used for the following:

Principal type Identifier
User

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
Group

group:GROUP_EMAIL_ADDRESS

Example: group:my-group@example.com
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 user1

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 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 for deny policies, which use the IAM v2 API.

Principal type Identifier
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
Group

principalSet://goog/group/GROUP_EMAIL_ADDRESS

Example: principalSet://goog/group/my-group@example.com
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/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 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

1 Learn how to find your Cloud Identity customer ID.

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.

Principal type Identifier
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

1 Learn how to find your Cloud Identity customer ID.