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

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 workload identity pool principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/SUBJECT_NAME
Workload identity pool group principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/group/GROUP_NAME
All identities in a workload identity pool with a certain attribute principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.ATTRIBUTE_NAME/ATTRIBUTE_VALUE
All identities in a workload identity pool principal://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

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

IAM v2beta API

The following table describes the principal type identifiers for the IAM v2beta 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 in a Cloud Identity account (domain)

principalSet://goog/cloudIdentityCustomerId/CLOUD_IDENTITY_CUSTOMER_ID1

Example: principalSet://goog/cloudIdentityCustomerId/C01Abc35

All users principalSet://goog/public:all
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.