In Identity and Access Management (IAM), you control access forprincipals. A principalrepresents 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. Configuringidentities is the process of creating identities that Google Cloud canrecognize. 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, seeIdentities forusers.
   • To learn how to configure identities for workloads, seeIdentities forworkloads.

2. Determine the principal identifier that you will use. The principalidentifier is how you refer to a principal in your policies. This identifiercan 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 eachtype of policy, seePrincipal identifiers.

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

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

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

Support for principal types

Each IAM policy type supports a subset of the principal typesthat IAM supports. To see the principal types that are supportedfor each policy type, seePrincipal identifiers.

Principal types

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

Preview — Principal identifiers for all service accounts in a project, folder, or organization

This feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of theService Specific Terms. Pre-GA features are available "as is" and might have limited support. For more information, see thelaunch stage descriptions.

Google AccountsService accountsService agentsGoogle groupsDomainsallAuthenticatedUsersallUsersWorkforce identity poolWorkload identity poolGoogle Kubernetes Engine PodsResource Manager principal sets

The following sections describe these principal types in more detail.

Google Accounts

A Google Account represents a developer, an administrator, or any other personwho interacts with Google Cloud by using an account they created withGoogle. Any email address that's associated with a Google Account, also called amanaged user account, can be used as a principal. This includesgmail.comemail addresses and email addresses with other domains.

The following examples show how you can identify a Google Account in differenttypes of policies:

• Allow policies:user:alex@example.com
• Deny policies:principal://goog/subject/alex@example.com

To learn more about principal identifier formats, seePrincipalidentifiers.

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

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

Service accounts

A service account is an account for an application or compute workload insteadof an individual end user. Service accounts can be divided intouser-managedservice accounts and Google-managed service accounts, which are calledserviceagents:

• When you run code that's hosted on Google Cloud, you specify a serviceaccount to use as the identity for your application. You can create as manyuser-managed service accounts as needed to represent the different logicalcomponents of your application.

• Some Google Cloud services need access to your resources so they can acton your behalf. Google creates and manages service agents to meet this need.

You can reference service accounts and service agents in the following ways:

• A single service account
• All service accounts in a project
• All service agents associated with a project.
• All service accounts in all projects in a folder
• All service agents associated with a folder and its descendants
• All service accounts in all projects in an organization
• All service agents associated with an organization and its descendants

The following examples show how you can identify an individual service accountin different types of policies:

• A service account in allow policies:serviceAccount:my-service-account@my-project.iam.gserviceaccount.com
• A service account in deny policies:principal://iam.googleapis.com/projects/-/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com

The following examples show how you can identify all service accounts for aproject, folder, or organization in different types of policies:

• All service accounts for a project in allow policies:principalSet://cloudresourcemanager.googleapis.com/projects/123456789012/type/ServiceAccount
• All service agents associated with a folder in deny policies:principalSet://cloudresourcemanager.googleapis.com/folders/123456789012/type/ServiceAgent

To learn more about principal identifier formats, seePrincipalidentifiers.

For more information about service accounts, see the following pages:

• Service accounts overview
• Types of service accounts

Google groups

A Google group is a named collection of Google Accounts. Every Google group hasa unique email address that's associated with the group. You can find the emailaddress that's associated with a Google group by clickingAbout on thehomepage of any Google group. For more information aboutGoogle Groups, see theGoogle Groupshomepage.

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

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

The following examples show how you can identify a Google group in differenttypes of policies:

• Allow policies:group:my-group@example.com
• Deny policies:principalSet://goog/group/my-group@example.com

To learn more about principal identifier formats, seePrincipalidentifiers.

To learn more about using groups for access control, seeBest practices forusing Google groups.

Domains

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

Google Workspace accounts and Cloud Identity domains areassociated with your organization's internet domain name, such asexample.com.

When you create a Google Account for a new user, such asusername@example.com,that Google Account is added to the virtual group for yourGoogle Workspace account or Cloud Identity domain.

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

The following examples show how you can identify a domain in different typesof 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, seePrincipalidentifiers.

For more information about Cloud Identity, seeAbout Cloud Identity.

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

allAuthenticatedUsers

The valueallAuthenticatedUsers is a special identifier that represents allservice accounts and all users on the internet who have authenticated with aGoogle Account. This identifier includes accounts that aren't connected to aGoogle Workspace account or Cloud Identity domain, such aspersonal Gmail accounts. Users who aren't authenticated, such as anonymousvisitors, aren't included.

This principal type doesn't include federated identities, which are managed byexternal identity providers (IdPs). If you useWorkforce Identity Federation orWorkload Identity Federation,don't useallAuthenticatedUsers. Instead, use one of the following:

• To include users from all IdPs, useallUsers.
• To include users from specific external IdPs, use the identifier forall identities in a workforce identity pool orall identities in a workload identity pool.

Some resource types don't support this principal type.

allUsers

The valueallUsers is a special identifier that represents anyone who is onthe internet, including authenticated and unauthenticated users.

Some resource types don't support this principal type.

To learn more about principal identifier formats, seePrincipalidentifiers.

Federated identities in a workforce identity pool

A workforce identity pool is a set of user identities that is managed by anexternal IdP and federated by usingWorkforce Identity Federation. Youcan 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 can identify federated workforceidentity pools in different types of policies:

• A single identity in allow policies:principal://iam.googleapis.com/locations/global/workforcePools/altostrat-contractors/subject/raha@altostrat.com
• A group of identities in deny policies:principalSet://iam.googleapis.com/locations/global/workforcePools/altostrat-contractors/group/administrators-group@altostrat.com
• A workforce identity pool in Principal access boundary policies://iam.googleapis.com/locations/global/workforcePools/example-workforce-pool

To learn more about principal identifier formats, seePrincipalidentifiers.

Federated identities in a workload identity pool

A workload identity pool is a set of workload identities that is managed byan external IdP and federated by usingWorkload Identity Federation. Youcan 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 can identify federated workloadidentity pools in different types of policies:

• A single identity in allow policies:principal://iam.googleapis.com/projects/123456789012/locations/global/workloadIdentityPools/altostrat-contractors/subject/raha@altostrat.com
• A group of identities in deny policies:principalSet://iam.googleapis.com/projects/123456789012/locations/global/workloadIdentityPools/altostrat-contractors/group/administrators-group@altostrat.com
• A workload identity pool in Principal access boundary policies://iam.googleapis.com/projects/123456789012/locations/global/workloadIdentityPools/example-workload-pool

To learn more about principal identifier formats, seePrincipalidentifiers.

GKE Pods

Workloads running on GKE useWorkload Identity Federation for GKE toaccess Google Cloud services. For more information about principalidentifiers for GKE Pods, seeReference Kubernetes resources in IAM policies.

The following example shows how you can identify all GKE podsin 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, seePrincipalidentifiers.

Resource Manager principal sets

Each Resource Manager resource—projects, folders, andorganizations—is associated with a set of principals. When you'recreating principal access boundary policy bindings, you can use the principal set for aResource Manager resource to reference all principals associated with thatresource.

Principal sets for Resource Manager resources contain the followingprincipals:

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

• Organization principal set: Contains the following identities:

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

The following example shows how you can identify a project's principal set ina principal access boundary policy:

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

To learn more about principal identifier formats, seePrincipalidentifiers.

What's next

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