In Identity and Access Management (IAM) you control access for principals. A principal represents one or more identities that have authenticated to Trusted Cloud.
Use principals in your policies
To use principals in your policies, do the following:
Configure identities that Trusted Cloud can recognize. Configuring identities is the process of creating identities that Trusted 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.
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.
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.
| Principal type | Description | Single principal or principal set | Google-managed or federated | Policy type Support |
|---|---|---|---|---|
| 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:
|
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-managed |
The following policy types support
The following policy types don't support
|
allUsers |
A special identifier that represents anyone who is on the internet—authenticated and unauthenticated. |
Principal set that can contain the following principal types:
|
Both |
The following policy types support
|
| 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:
|
| 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:
|
| 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:
|
| 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:
|
| 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:
The following policy types don't support GKE pods:
|
The following sections describe these principal types in more detail.
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 Trusted 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:my-service-account@my-project. - Deny policies:
principal://iam.googleapis.com/projects/-/serviceAccounts/my-service-account@my-project.
To learn more about principal identifier formats, see Principal identifiers.
For more information about service accounts, see Service accounts overview.
allAuthenticatedUsers
The value allAuthenticatedUsers is a special identifier that represents all
service accounts.
This principal type doesn't include federated identities, which are managed by external identity providers (IdPs). To include federated identities, use one of the following choices:
- 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.
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/raha@altostrat.com - A set of principals in deny policies:
principalSet://iam.googleapis.com/locations/global/workforcePools/altostrat-contractors/group/administrators-group@altostrat.com
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/raha@altostrat.com - A group of principals in deny policies:
principalSet://iam.googleapis.com/projects/123456789012/locations/global/workloadIdentityPools/altostrat-contractors/group/administrators-group@altostrat.com
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