Supported identities for ingress and egress rules

VPC Service Controls uses ingress and egress rules to control access to and from resources and clients within service perimeters. To refine access further, you can specify supported identities in ingress and egress rules.

This page lists the identities supported by VPC Service Controls and their identifier formats.

Note: You can specify workforce identity pools, workload identity pools, Workload Identity Federation for GKE (Preview), agentic identities, and service agents only in service perimeter ingress and egress rules. These identity types are not supported in Access Context Manager access levels.

Supported identities

VPC Service Controls supports the following identities from Principal identifiers for allow policies, which use the IAM v1 API:

Identity type	Principal type	Identifier
Single principals	User accounts	user:USER_EMAIL_ADDRESS
	Service accounts	serviceAccount:SA_EMAIL_ADDRESS
Identity groups and third-party identities	Group	group:GROUP_EMAIL_ADDRESS
	Single identity in a workforce identity pool	principal://iam.googleapis.com/locations/global/workforcePools/POOL_ID/subject/SUBJECT_ATTRIBUTE_VALUE
	All workforce identities in a group	principalSet://iam.googleapis.com/locations/global/workforcePools/POOL_ID/group/GROUP_ID
	All workforce identities with a specific attribute value	principalSet://iam.googleapis.com/locations/global/workforcePools/POOL_ID/attribute.ATTRIBUTE_NAME/ATTRIBUTE_VALUE
	All identities in a workforce identity pool	principalSet://iam.googleapis.com/locations/global/workforcePools/POOL_ID/*
	Single identity in a workload identity pool	principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/SUBJECT_ATTRIBUTE_VALUE
	Workload identity pool group	principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/group/GROUP_ID
	All identities in a workload identity pool with a certain attribute	principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.ATTRIBUTE_NAME/ATTRIBUTE_VALUE
	All identities in a workload identity pool	principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/*
Workload Identity Federation for GKE (Preview)	All GKE Pods that use a Kubernetes service account by name	principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/subject/ns/NAMESPACE/sa/KUBERNETES_SERVICE_ACCOUNT
	All GKE Pods that use a Kubernetes service account by ID	principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/kubernetes.serviceaccount.uid/SERVICEACCOUNT_ID
	All GKE Pods in a Kubernetes namespace, regardless of service account or cluster	principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/namespace/NAMESPACE
	All GKE Pods in a cluster	principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/kubernetes.cluster/https://container.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/clusters/CLUSTER_NAME
Agent identities	Agent identity	principal://TRUST_DOMAIN/AGENT_UNIQUE_IDENTIFIER
	All agent identities in a trust domain with a certain attribute	principalSet://TRUST_DOMAIN/attribute.ATTRIBUTE_NAME/ATTRIBUTE_VALUE
	All agent identities in a trust domain	principalSet://TRUST_DOMAIN/*

For more information about these identities, see Principal identifiers for allow policies.

VPC Service Controls also supports the following SPIFFE formats for third-party workforce and workload identities:

Identity type	Principal type	Identifier
Workforce identities in SPIFFE format	Single identity in a workforce identity pool	principal://POOL_ID.global.workforce.id.goog/SUBJECT_ATTRIBUTE_VALUE
	All identities in a workforce identity pool as a trust domain with a certain attribute	principalSet://POOL_ID.global.workforce.id.goog/attribute.ATTRIBUTE_NAME/ATTRIBUTE_VALUE
	All identities in a workforce identity pool as a trust domain	principalSet://POOL_ID.global.workforce.id.goog/*
Workload identities in SPIFFE format	Single identity in a workload identity pool	principal://POOL_ID.global.ORGANIZATION_ID.workload.id.goog/SUBJECT_ATTRIBUTE_VALUE
	All identities in a workload identity pool as a trust domain with a certain attribute	principalSet://POOL_ID.global.ORGANIZATION_ID.workload.id.goog/attribute.ATTRIBUTE_NAME/ATTRIBUTE_VALUE
	All identities in a workload identity pool as a trust domain	principalSet://POOL_ID.global.ORGANIZATION_ID.workload.id.goog/*

Workload Identity Federation for GKE considerations

Preview

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

• A limit of 1,000 Workload Identity Federation for GKE principals per access policy applies. For more information, see Quotas and limits.
• Workload Identity Federation for GKE principals don't support deleted principal syntax.
• You can specify Workload Identity Federation for GKE principals by using either the full IAM principal identifier format (for example, principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/subject/ns/NAMESPACE/sa/KUBERNETES_SERVICE_ACCOUNT) or the equivalent SPIFFE format (for example, principal://PROJECT_ID.svc.id.goog/ns/NAMESPACE/sa/KUBERNETES_SERVICE_ACCOUNT). When you describe or retrieve a service perimeter that contains rules created with SPIFFE syntax, VPC Service Controls returns the identity in SPIFFE format.

Deleted IAM principals

Preview

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

To help you manage service perimeters that reference deleted accounts, VPC Service Controls lets you enable support for deleted IAM principal identifiers. By default, attempting to update or list perimeters that contain deleted principals fails with a The email address is invalid or non-existent error. For more information, see Troubleshooting common issues.

To retrieve or update perimeters that contain deleted principals, use the Access Context Manager API. Set the deletedPrincipalSyntax parameter (REST) or the deleted_principal_syntax field (gRPC) to DELETED_PRINCIPAL_SYNTAX_SUPPORT_ENABLED in a request, such as the get, list, or patch methods.

For more information, see the REST or gRPC reference pages.

For example, you can use the following curl command to get a perimeter:

curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://accesscontextmanager.googleapis.com/v1/accessPolicies/\
POLICY_NAME/servicePerimeters/PERIMETER_NAME?\
deletedPrincipalSyntax=DELETED_PRINCIPAL_SYNTAX_SUPPORT_ENABLED"

Note: You can't use the Google Cloud console or the gcloud command-line tool to manage perimeters that contain deleted principals. Attempting to do so fails with a The email address is invalid or non-existent error.

For a list of IAM principal types that support the deleted syntax, see Principal identifiers for allow policies.

Limitations

The following limitations apply to deleted IAM principals in VPC Service Controls perimeters:

• VPC Service Controls supports only the deleted IAM principals that use the IAM v1 API. It doesn't support deleted principals that use the IAM v2 or v3 APIs.
• Deleted IAM principals in access levels are not supported.
• Principals that don't support the deleted: prefix syntax in IAM are also not supported in VPC Service Controls service perimeter rules.
• You can specify a maximum of 500 deleted identities in an access policy.

What's next

• Configure identity groups and third-party identities in ingress and egress rules