IAM principals

In Identity and Access Management (IAM) you control access for principals. A principal represent one or more identities that have authenticated to Google Cloud.

Use principals in your policies

To use principals in your policies, do the following:

1. Configure identities that Google Cloud can recognize. Configuring identities is the process of creating identities that Google Cloud can recognize. You can configure identities for users and for workloads.

   To learn how to configure identities, see the following:

   • To learn how to configure identities for users, see Identities for users.
   • To learn how to configure identities for workloads, see Identities for workloads.

2. Determine the principal identifier that you will use. The principal identifier is how you refer to a principal in your policies. This identifier can refer to a single identity or to a group of identities.

   The format that you use for the principal identifier depends on the following:

   • The type of principal
   • The type of the policy that you want to include the principal in

   To see the principal identifier format for each type of principal in each type of policy, see Principal identifiers.

   After you know the format of the identifier, you can determine the principal's unique identifier based on the attributes of the principal, such as the principal's email address.

3. Include the principal's identifier in your policy. Add your principal to your policy, following the format of the policy.

   To learn about the different types of policies in IAM, see Policy types.

Support for principal types

Each IAM policy type supports a subset of the principal types that IAM supports. To see the principal types that are supported for each policy type, see Principal identifiers.

Principal types

The following table briefly describes the different principal types supported by IAM. For a detailed description and examples of how a principal type might look when used in a policy, click the principal type name in the table.

Google Accounts Service accounts Google groups Domains allAuthenticatedUsers allUsers Workforce identity pool Workload identity pool Google Kubernetes Engine Pods Resource Manager principal sets

Principal type	Description	Single principal or principal set	Google-managed or federated	Policy type Support
Google Accounts	User accounts that represent a human who interacts with Google APIs and services.	Single principal	Google-managed	The following policy types support Google Accounts: Allow Deny The following policy types don't support Google Accounts: Principal access boundary
Service accounts	An account that is used by a machine workload rather than a person.	Single principal	Google-managed	The following policy types support service accounts: Allow Deny The following policy types don't support service accounts: Principal access boundary
Google groups	A named collection of human or machine users with Google Accounts.	Principal set that can contain the following: Google Accounts Service accounts	Google-managed	The following policy types support Google groups: Allow Deny The following policy types don't support Google groups: Principal access boundary
Domains	A Google Workspace account or Cloud Identity domain that represents a virtual group. The group can contain both human users and service accounts.	Principal set that can contain the following principal types: Google Accounts Service accounts	Google-managed	The following policy types support domains: Allow Deny Principal access boundary
allAuthenticatedUsers	A special identifier that represents all service accounts and human users on the internet who have authenticated with a Google Account.	Principal set that can contain the following principal types: Google Accounts Service accounts Workforce identities Workload identities	Google-managed	The following policy types support allAuthenticatedUsers for some resources: Allow The following policy types don't support allAuthenticatedUsers: Deny Principal access boundary
allUsers	A special identifier that represents anyone who is on the internet—authenticated and unauthenticated.	Principal set that can contain the following principal types: Google Accounts Service accounts Workforce identities Workload identities	Both	The following policy types support allUsers: Allow (for some resources) Deny The following policy types don't support allUsers: Principal access boundary
A single identity in a workforce identity pool	A human user with an identity that is managed by an external IdP and federated by using Workforce Identity Federation.	Single principal	Federated	The following policy types support a single identity in a workforce identity pool: Allow Deny Principal access boundary
A set of principals in a workforce identity pool	A set of human users with identities that are managed by an external IdP and federated by using Workforce Identity Federation.	Principal set that contains workforce identities.	Federated	The following policy types support a set of principals in a workforce identity pool: Allow Deny Principal access boundary
A single principal in a workload identity pool	A workload (or machine user) with an identity that is managed by an external IdP and federated by using Workload Identity Federation.	Single principal	Federated	The following policy types support a single principal in a workload identity pool: Allow Deny Principal access boundary
A set of principals in a workload identity pool	A set of workloads (or machine users) with identities that are managed by an external IdP and federated by using Workload Identity Federation.	Principal set that contains workload identities	Federated	The following policy types support a set of principals in a workload identity pool: Allow Deny Principal access boundary
A set of Google Kubernetes Engine Pods	A workload (or machine user) running on and federated through GKE.	Principal set that can contain one or more federated workload identities	Federated	The following policy types support GKE pods: Allow The following policy types don't support GKE pods: Deny Principal access boundary
Resource Manager principal sets	A set of human or machine users associated with Google Cloud resources such as projects, folders, and organizations.	Principal set that can contain the following principal types: Google Accounts Service accounts Workforce identities Workload identities	Both	The following policy types support Resource Manager principal sets: Principal access boundary The following policy types don't support Resource Manager principal sets: Allow Deny

The following sections describe these principal types in more detail.

Google Accounts

A Google Account represents a developer, an administrator, or any other person who interacts with Google Cloud by using an account they created with Google. Any email address that's associated with a Google Account, also called a managed user account, can be used as a principal. This includes gmail.com email addresses and email addresses with other domains.

The following examples show how you might identify a Google Account in different types of policies:

• Allow policies: user:[e-mail]
• Deny policies: principal://goog/subject/[e-mail]

To learn more about principal identifier formats, see Principal identifiers.

In your allow and deny policies, email aliases associated with a Google Account or a managed user account are automatically replaced with the primary email address. This means that the policy displays the user's primary email address when you grant access to an email alias.

For more information about setting up Google Accounts, see Cloud Identity or Google Workspace accounts.

Service accounts

A service account is an account for an application or compute workload instead of an individual end user. When you run code that's hosted on Google Cloud, you specify a service account to use as the identity for your application. You can create as many service accounts as needed to represent the different logical components of your application.

The following examples show how you might identify a service account in different types of policies:

• Allow policies: serviceAccount:[e-mail]
• Deny policies: principal://iam.googleapis.com/projects/-/serviceAccounts/[e-mail]

To learn more about principal identifier formats, see Principal identifiers.

For more information about service accounts, see Service accounts overview.

Note: If you use Google Kubernetes Engine (GKE), you can also grant roles to Kubernetes service accounts, which differ from IAM service accounts.

Google groups

A Google group is a named collection of Google Accounts. Every Google group has a unique email address that's associated with the group. You can find the email address that's associated with a Google group by clicking About on the homepage of any Google group. For more information about Google Groups, see the Google Groups homepage.

Google groups are a convenient way to apply access controls to a collection of principals. You can grant and change access controls for a whole group at once instead of granting or changing access controls one at a time for individual principals. You can also add principals to or remove principals from a Google group instead of updating an allow policy to add or remove principals.

Google groups don't have login credentials, and you cannot use Google groups to establish identity to make a request to access a resource.

The following examples show how you might identify a Google group in different types of policies:

• Allow policies: group:[e-mail]
• Deny policies: principalSet://goog/group/[e-mail]

To learn more about principal identifier formats, see Principal identifiers.

To learn more about using groups for access control, see Best practices for using Google groups.

Domains

Domains can exist as either Google Workspace accounts or Cloud Identity domains. They are fundamentally the same because they both represent a virtual group of all the Google Accounts that they contain. The only difference is that Cloud Identity domain users don't have access to Google Workspace applications and features.

Google Workspace accounts and Cloud Identity domains are associated with your organization's internet domain name, such as example.com.

When you create a Google Account for a new user, such as [e-mail], that Google Account is added to the virtual group for your Google Workspace account or Cloud Identity domain.

Like Google groups, domains cannot be used to establish identity, but they enable convenient permission management.

The following examples show how you might identify a domain in different types of policies:

• Allow policies: domain:example.com
• Deny policies: principalSet://goog/cloudIdentityCustomerId/C01Abc35
• Principal access boundary policies: //iam.googleapis.com/locations/global/workspace/C01Abc35

To learn more about principal identifier formats, see Principal identifiers.

For more information about Cloud Identity, see About Cloud Identity.

In your allow and deny policies, secondary domains are automatically replaced with the primary domain. This means that the policy displays the primary domain when you grant access to a secondary domain.

allAuthenticatedUsers

The value allAuthenticatedUsers is a special identifier that represents all service accounts and all users on the internet who have authenticated with a Google Account. This identifier includes accounts that aren't connected to a Google Workspace account or Cloud Identity domain, such as personal Gmail accounts. Users who aren't authenticated, such as anonymous visitors, aren't included.

Note: Consider using allUsers, as described on this page, rather than allAuthenticatedUsers. In many cases, granting access to all users is no more of a security risk than granting access only to authenticated users.

This principal type doesn't include federated identities, which are managed by external identity providers (IdPs). If you use Workforce Identity Federation or Workload Identity Federation, don't use allAuthenticatedUsers. Instead, use one of the following:

• To include users from all IdPs, use allUsers.
• To include users from specific external IdPs, use the identifier for all identities in a workforce identity pool or all identities in a workload identity pool.

Some resource types don't support this principal type.

allUsers

The value allUsers is a special identifier that represents anyone who is on the internet, including authenticated and unauthenticated users.

Some resource types don't support this principal type.

Note: Some Google Cloud services require authentication before a user can access the service. For these services, allUsers includes only authenticated users.

The following examples show how the allUsers identifier might look in different types of policies:

• Allow policies on supported resource types: allUsers
• Deny policies: principalSet://goog/public:all

To learn more about principal identifier formats, see Principal identifiers.

Federated identities in a workforce identity pool

A workforce identity pool is a set of user identities that is managed by an external IdP and federated by using Workforce Identity Federation. You can reference principals in these pools in the following ways:

• A single identity in a workforce identity pool
• All workforce identities in a specified group
• All workforce identities with a specific attribute value
• All identities in a workforce identity pool

The following examples show how you might identify federated workforce identity pools in different types of policies:

• A single principal in allow policies: principal://iam.googleapis.com/locations/global/workforcePools/altostrat-contractors/subject/[e-mail]
• A set of principals in deny policies: principalSet://iam.googleapis.com/locations/global/workforcePools/altostrat-contractors/group/[e-mail]
• Principal access boundary policies: //iam.googleapis.com/locations/global/workforcePools/example-workforce-pool

To learn more about principal identifier formats, see Principal identifiers.

Federated identities in a workload identity pool

A workload identity pool is a set of workload identities that is managed by an external IdP and federated by using Workload Identity Federation. You can reference principals in these pools in the following ways:

• A single identity in a workload identity pool
• All workload identities in a specified group
• All workload identities with a specific attribute value
• All identities in a workload identity pool

The following examples show how you might identify federated workload identity pools in different types of policies:

• A single principal in allow policies: principal://iam.googleapis.com/projects/123456789012/locations/global/workloadIdentityPools/altostrat-contractors/subject/[e-mail]
• A group of principals in deny policies: principalSet://iam.googleapis.com/projects/123456789012/locations/global/workloadIdentityPools/altostrat-contractors/group/[e-mail]
• Principal access boundary policies: //iam.googleapis.com/projects/123456789012/locations/global/workloadIdentityPools/example-workload-pool

To learn more about principal identifier formats, see Principal identifiers.

GKE Pods

Workloads running on GKE use Workload Identity Federation for GKE to access Google Cloud services. For more information about principal identifiers for GKE Pods, see Reference Kubernetes resources in IAM policies.

The following example shows how you might identify all GKE pods in a specific cluster in an allow policy:

principalSet://iam.googleapis.com/projects/123456789012/locations/global/workloadIdentityPools/123456789012.svc.id.goog/kubernetes.cluster/https://container.googleapis.com/v1/projects/123456789012/locations/global/clusters/example-gke-cluster

To learn more about principal identifier formats, see Principal identifiers.

Resource Manager principal sets

Each Resource Manager resource—projects, folders, and organizations—is associated with a set of principals. When you're creating principal access boundary policy bindings, you can use the principal set for a Resource Manager resource to reference all principals associated with that resource.

Principal sets for Resource Manager resources contain the following principals:

• Project principal set: All service accounts and workload identity pools in the specified project.
• Folder principal set: All service accounts and all workload identity pools in any project in the specified folder.

• Organization principal set: Contains the following identities:

  • All identities in all domains associated with your Google Workspace customer ID
  • All workforce identity pools in your organization
  • All service accounts and workload identity pools in any project in the organization

The following example shows how you might identify a project's principal set in a principal access boundary policy for a project's principal set:

//cloudresourcemanager.googleapis.com/projects/example-project

To learn more about principal identifier formats, see Principal identifiers.

What's next

• Learn about the policy types that IAM supports
• Grant a principal a role on a Resource Manager project, folder, or organization