In Identity and Access Management (IAM), you control access for *principals*. A principal
represents 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](https://docs.cloud.google.com/iam/docs/user-identities).
   - To learn how to configure identities for workloads, see [Identities for
     workloads](https://docs.cloud.google.com/iam/docs/workload-identities).
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](https://docs.cloud.google.com/iam/docs/principal-identifiers.md.txt).

   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](https://docs.cloud.google.com/iam/docs/policy-types.md.txt).

### 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](https://docs.cloud.google.com/iam/docs/principal-identifiers.md.txt).

## 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 Service agents 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](https://docs.cloud.google.com/iam/docs/principals-overview.md.txt#google-account) | 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** - **Unified Access Policy (UAP)** The following policy types don't support Google Accounts: - **Principal Access Boundary** |
| [Service accounts](https://docs.cloud.google.com/iam/docs/principals-overview.md.txt#service-account) | 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** - **UAP** The following policy types don't support service accounts: - **Principal Access Boundary** |
| [A set of service accounts](https://docs.cloud.google.com/iam/docs/principals-overview.md.txt#service-account) | All service accounts in a project, folder, or organization. | Principal set that contains service accounts. | Google-managed | The following policy types support a set of service accounts: - **Allow** - **Deny** - **UAP** The following policy types don't support a set of service accounts: - **Principal Access Boundary** |
| [A set of service agents](https://docs.cloud.google.com/iam/docs/principals-overview.md.txt#service-account) | All Google-managed service accounts (service agents) associated with a project, folder, or organization. | Principal set that contains service agents. | Google-managed | The following policy types support a set of service agents: - **Deny** - **UAP deny rules** The following policy types don't support a set of service agents: - **Allow** - **Principal Access Boundary** - **UAP allow rules** |
| [Google groups](https://docs.cloud.google.com/iam/docs/principals-overview.md.txt#google-group) | 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** - **UAP** The following policy types don't support Google groups: - **Principal Access Boundary** |
| [Domains](https://docs.cloud.google.com/iam/docs/principals-overview.md.txt#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** - **UAP** |
| [`allAuthenticatedUsers`](https://docs.cloud.google.com/iam/docs/principals-overview.md.txt#all-authenticated-users) | 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** - **UAP** |
| [`allUsers` or `principalSet://goog/public:all`](https://docs.cloud.google.com/iam/docs/principals-overview.md.txt#all-users) | 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` or `principalSet://goog/public:all`: - **Allow** (for some resources) - **Deny** - **UAP deny rules** The following policy types don't support `allUsers` or `principalSet://goog/public:all`: - **Principal Access Boundary** - **UAP allow rules** |
| [A single principal in a workforce identity pool](https://docs.cloud.google.com/iam/docs/principals-overview.md.txt#workforce) | 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 principal in a workforce identity pool: - **Allow** - **Deny** - **UAP** The following policy types don't support a single principal in a workforce identity pool: - **Principal Access Boundary** |
| [A set of principals in a workforce identity pool](https://docs.cloud.google.com/iam/docs/principals-overview.md.txt#workforce) | 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** - **UAP** |
| [A single principal in a workload identity pool](https://docs.cloud.google.com/iam/docs/principals-overview.md.txt#workload) | 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** - **UAP** The following policy types don't support a single principal in a workload identity pool: - **Principal Access Boundary** |
| [A set of principals in a workload identity pool](https://docs.cloud.google.com/iam/docs/principals-overview.md.txt#workload) | 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** - **UAP** |
| [A set of Google Kubernetes Engine Pods](https://docs.cloud.google.com/iam/docs/principals-overview.md.txt#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** - **UAP** |
| [Agent identities](https://docs.cloud.google.com/iam/docs/principals-overview.md.txt#agent-identity) | An identity for an agentic workload that is strongly attested and is tied to the lifecycle of the agent. | Single principal | Google-managed | The following policy types support agent identities: - **Allow** - **Deny** - **UAP** The following policy types don't support individual agent identities: - **Principal Access Boundary** |
| [A set of agent identities](https://docs.cloud.google.com/iam/docs/principals-overview.md.txt#agent-identity) | All agent identities in a trust domain. | Principal set that contains agent identities. | Google-managed | The following policy types support a set of agent identities: - **Allow** - **Deny** - **Principal Access Boundary** (only for agent identities in a project) - **UAP** |
| [Resource Manager principal sets](https://docs.cloud.google.com/iam/docs/principals-overview.md.txt#crm-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** - **UAP** |

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 can identify a Google Account in different
types of policies:

- **Allow policies** : `user:alex@example.com`
- **Deny policies** : `principal://goog/subject/alex@example.com`
- **UAPs** : `principal://goog/subject/alex@example.com`


To learn more about principal identifier formats, see [Principal
identifiers](https://docs.cloud.google.com/iam/docs/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](https://docs.cloud.google.com/iam/docs/user-identities.md.txt#google-accounts).

### Service accounts

A service account is an account for an application or compute workload instead
of an individual end user. Service accounts can be divided into *user-managed
service accounts* and Google-managed service accounts, which are called *service
agents*:

- 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
  user-managed service accounts as needed to represent the different logical
  components of your application.

- Some Google Cloud services need access to your resources so they can act
  on 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 account
in 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`
- **A service account in UAPs** : `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 a
project, 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`
- **All service accounts for an organization in UAPs** : `principalSet://cloudresourcemanager.googleapis.com/organizations/123456789012/type/ServiceAccount`


To learn more about principal identifier formats, see [Principal
identifiers](https://docs.cloud.google.com/iam/docs/principal-identifiers).

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

- [Service accounts overview](https://docs.cloud.google.com/iam/docs/service-account-overview.md.txt)
- [Types of service accounts](https://docs.cloud.google.com/iam/docs/service-account-types.md.txt)

> [!NOTE]
> **Note:** If you use Google Kubernetes Engine (GKE), you can also grant roles to [Kubernetes service accounts](https://docs.cloud.google.com/kubernetes-engine/docs/how-to/service-accounts.md.txt#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](https://groups.google.com/)
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 can't use Google
groups to establish identity to make a request to access a resource.

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

- **Allow policies** : `group:my-group@example.com`
- **Deny policies** : `principalSet://goog/group/my-group@example.com`
- **UAPs** : `principalSet://goog/group/my-group@example.com`


To learn more about principal identifier formats, see [Principal
identifiers](https://docs.cloud.google.com/iam/docs/principal-identifiers).

To learn more about using groups for access control, see [Best practices for
using Google groups](https://docs.cloud.google.com/iam/docs/groups-best-practices).

### 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.

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

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 or Cloud Identity domain. When you modify
access for the Google Workspace account or Cloud Identity domain,
you modify access for all Google Accounts in that virtual group.

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

- **Allow policies** : `domain:example.com`
- **Deny policies** : `principalSet://goog/cloudIdentityCustomerId/C01Abc35`
- **UAPs** : `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](https://docs.cloud.google.com/iam/docs/principal-identifiers).

For more information about Cloud Identity, see
[About Cloud Identity](https://support.google.com/a/answer/7319251).

#### Secondary domains

When you create a Google Workspace account or a Cloud Identity
domain, you're assigned a unique customer ID. Then, you provide a domain name
that becomes your primary domain name---for example, `example.com`.

After you create your primary domain, you can optionally add [secondary
domains](https://support.google.com/a/answer/7502379) with their own domain names. However, these domains
are associated with the same customer ID as the primary domain.

IAM uses your customer ID to identify members in the domain, not
the domain name. As a result, you can't manage access for primary and secondary
domains separately. This is true even for allow policies, where you identify the
domain using the domain name. When evaluating allow policies, IAM
identifies the customer ID associated with that domain, then uses that customer
ID---not the domain name---to identify members of that domain.

Domain names in allow policies default to the primary domain name. If you grant
access to a domain using a secondary domain name, it will be automatically
replaced with the corresponding primary domain name.

### `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]
> **Note:** By default, organizations created on or after May 3, 2024 don't allow roles to be granted to `allAuthenticatedUsers`. This is because of the default configuration of the `iam.managed.allowedPolicyMembers` constraint. To learn how to change this setting, see [Restricting identities by
> domain](https://docs.cloud.google.com/resource-manager/docs/organization-policy/restricting-domains).

> [!NOTE]
> **Note:** Consider using [`allUsers`](https://docs.cloud.google.com/iam/docs/principals-overview.md.txt#all-users), 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](https://docs.cloud.google.com/iam/docs/workforce-identity-federation.md.txt) or [Workload Identity Federation](https://docs.cloud.google.com/iam/docs/workload-identity-federation.md.txt),
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](https://docs.cloud.google.com/iam/docs/workforce-identity-federation.md.txt#representing-workforce-users) or [all identities in a workload identity pool](https://docs.cloud.google.com/iam/docs/workload-identity-federation.md.txt#impersonation).

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]
> **Note:** By default, organizations created on or after May 3, 2024 don't allow roles to be granted to `allUsers`. This is because of the default configuration of the `iam.managed.allowedPolicyMembers` constraint. To learn how to change this setting, see [Restricting identities by
> domain](https://docs.cloud.google.com/resource-manager/docs/organization-policy/restricting-domains).

> [!NOTE]
> **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 and UAP deny rules** : `principalSet://goog/public:all`


To learn more about principal identifier formats, see [Principal
identifiers](https://docs.cloud.google.com/iam/docs/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](https://docs.cloud.google.com/iam/docs/workforce-identity-federation.md.txt). 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 can identify federated workforce
identity 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, see [Principal
identifiers](https://docs.cloud.google.com/iam/docs/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](https://docs.cloud.google.com/iam/docs/workload-identity-federation.md.txt). 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 can identify federated workload
identity 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, see [Principal
identifiers](https://docs.cloud.google.com/iam/docs/principal-identifiers).

### GKE Pods

Workloads running on GKE use [Workload Identity Federation for GKE](https://docs.cloud.google.com/kubernetes-engine/docs/concepts/workload-identity.md.txt) to
access Google Cloud services. For more information about principal
identifiers for GKE Pods, see
[Reference Kubernetes resources in IAM policies](https://docs.cloud.google.com/kubernetes-engine/docs/concepts/workload-identity.md.txt#kubernetes-resources-iam-policies).

The following example shows how you can 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](https://docs.cloud.google.com/iam/docs/principal-identifiers).

### Agent identities

> [!WARNING]
>
> **Preview**
>
>
> This product or feature is
>
> subject to the "Pre-GA Offerings Terms" in the General Service Terms section
> of the [Service Specific
> Terms](https://docs.cloud.google.com/terms/service-terms#1).
>
> Pre-GA products and features are available "as is" and might have limited support.
>
> For more information, see the
> [launch stage descriptions](https://cloud.google.com/products/#product-launch-stages).

An agent identity is a Google-managed identity for agentic workloads. An agent
identity is attested and tied to the lifecycle of the agent, which provides
a more secure way to manage agent access to Google Cloud resources than
using service accounts.

Each agent is automatically provisioned with an agent identity. You can grant or
deny access to Google Cloud resources using IAM allow and
deny policies. You can also manage access for all agent identities in a project,
folder, or organization using allow, deny, and Principal Access Boundary policies.

Agent identities can also be grouped into *agent identity pools*.

The following examples show how you can identify agent identities in
various types of policies:

- **A single agent identity in an allow policy (in an organization)** : `principal://agents.global.org-123456789012.system.id.goog/resources/aiplatform/projects/9876543210/locations/us-central1/reasoningEngines/my-test-agent`
- **A single agent identity in an allow policy (in a project without an organization)** : `principal://agents.global.proj-9876543210.system.id.goog/resources/aiplatform/projects/9876543210/locations/us-central1/reasoningEngines/my-test-agent`
- **All agent identities in a project in a deny policy** : `principal://agents.global.org-123456789012.system.id.goog/resources/aiplatform/projects/9876543210`
- **All agent identities in a project in a Principal Access Boundary policy** : `//agents.global.org-123456789012.system.id.goog/attribute.container/projects/9876543210`


To learn more about principal identifier formats, see [Principal
identifiers](https://docs.cloud.google.com/iam/docs/principal-identifiers).

### Resource Manager principal sets

Each Resource Manager resource---such as a project, folder, or
organization---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 can identify a project's principal set in
a Principal Access Boundary policy:

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


To learn more about principal identifier formats, see [Principal
identifiers](https://docs.cloud.google.com/iam/docs/principal-identifiers).

## What's next

- Learn about the [policy types](https://docs.cloud.google.com/iam/docs/policy-types.md.txt) that IAM supports.
- [Grant a principal a role](https://docs.cloud.google.com/iam/docs/granting-changing-revoking-access.md.txt) on a Resource Manager project, folder, or organization.