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:

  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

IAM supports the following types of principals:

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.

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.

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

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.

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

Google Workspace accounts

A Google Workspace account represents a virtual group of all of the Google Accounts that it contains. Google Workspace accounts 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 username@example.com, that Google Account is added to the virtual group for your Google Workspace account.

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

Cloud Identity domains

A Cloud Identity domain is like a Google Workspace account, because it represents a virtual group of all Google Accounts in an organization. However, Cloud Identity domain users don't have access to Google Workspace applications and features. For more information, 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.

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:

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.

Federated identities in a workforce identity pool

A federated identity in a workforce identity pool is a user identity that is managed by an external IdP and federated by using Workforce Identity Federation. You can use a specific identity in a workforce identity pool, or you can use certain attributes to specify a group of user identities in a workforce identity pool.

Federated identities in a workload identity pool

A federated identity in a workload identity pool is a workload identity that is managed by an external IdP and federated by using Workload Identity Federation. You can use a specific workload identity in a workload identity pool, or you can use certain attributes to specify a group of workload identities in a workload identity pool.

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.

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

What's next