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:alex@example.com
Service account

serviceAccount:SA_EMAIL_ADDRESS

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

serviceAccount:PROJECT_ID.svc.id.goog[NAMESPACE/KUBERNETES_SA]

Example: serviceAccount:my-project.svc.id.goog[my-namespace/my-kubernetes-sa]
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
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 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 Do not 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/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
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

1 Learn how to find your Cloud Identity customer ID.

2 Do not add deleted principals when creating or modifying policies.