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

This page describes how to use identity groups in ingress and egress rules to allow access to resources protected by service perimeters.

VPC Service Controls uses ingress and egress rules to allow access to and from the resources and clients protected by service perimeters. To further refine access, you can specify identity groups in your ingress and egress rules.

An identity group is a convenient way to apply access controls to a collection of users and lets you manage identities that have similar access policies.

To configure identity groups in the ingress or egress rules, you can use the following supported identity groups in the identities attribute:

For information about how to apply ingress and egress rule policies, see Configuring ingress and egress policies.

Before you begin

Configure identity groups in ingress rules

Console

When you update an ingress policy of a service perimeter or set an ingress policy during perimeter creation using the Google Cloud console, you can configure the ingress rule to use identity groups.

  1. When you create a perimeter or edit a perimeter in the Google Cloud console, select Ingress policy.

  2. In the From section of your ingress policy, select Select identities & groups from the Identities list.

  3. Click Add identities.

  4. In the Add identities pane, specify a Google group or a third-party identity to which you want to provide access to resources in the perimeter. To specify an identity group, use the format specified in IAM v1 API Principal identifiers.

    VPC Service Controls supports only the v1 identities that start with the group, principal, and principalSet prefixes in the IAM v1 API Principal identifiers. For example, use the principalSet://iam.googleapis.com/locations/global/workforcePools/POOL_ID/group/GROUP_ID format to specify all workforce identities in a group or use the group:GROUP_NAME@googlegroups.com format to specify a Google group.

  5. Click Add identities.

  6. Click Save.

For information about the other ingress rule attributes, see Ingress rules reference.

gcloud

You can configure an ingress rule to use identity groups using a JSON file or a YAML file. The following sample uses the YAML format:

- ingressFrom:
    identities:
    - PRINCIPAL_IDENTIFIER
    sources:
    - resource: RESOURCE
      *OR*
    - accessLevel: ACCESS_LEVEL
  ingressTo:
    operations:
    - serviceName: SERVICE_NAME
      methodSelectors:
      - method: METHOD_NAME
    resources:
    - projects/PROJECT_NUMBER

Replace the following:

  • PRINCIPAL_IDENTIFIER: specify a Google group or a third-party identity to which you want to provide access to resources in the perimeter. To specify an identity group, use the format specified in IAM v1 API Principal identifiers.

    VPC Service Controls supports only the v1 identities that start with the group, principal, and principalSet prefixes in the IAM v1 API Principal identifiers. For example, use the principalSet://iam.googleapis.com/locations/global/workforcePools/POOL_ID/group/GROUP_ID format to specify all workforce identities in a group or use the group:GROUP_NAME@googlegroups.com format to specify a Google group.

For information about the other ingress rule attributes, see Ingress rules reference.

After you update an existing ingress rule to configure identity groups, you need to update the rule policies of the service perimeter:

gcloud access-context-manager perimeters update PERIMETER_ID --set-ingress-policies=RULE_POLICY.yaml

Replace the following:

  • PERIMETER_ID: the ID of the service perimeter that you want to update.
  • RULE_POLICY: the path of the modified ingress rule file.

For more information, see Updating ingress and egress policies for a service perimeter.

Configure identity groups in egress rules

Console

When you update an egress policy of a service perimeter or set an egress policy during perimeter creation using the Google Cloud console, you can configure the egress rule to use identity groups.

  1. When you create a perimeter or edit a perimeter in the Google Cloud console, select Egress policy.

  2. In the From section of your egress policy, select Select identities & groups from the Identities list.

  3. Click Add identities.

  4. In the Add identities pane, specify a Google group or a third-party identity that can access the specified resources outside the perimeter. To specify an identity group, use the format specified in IAM v1 API Principal identifiers.

    VPC Service Controls supports only the v1 identities that start with the group, principal, and principalSet prefixes in the IAM v1 API Principal identifiers. For example, use the principalSet://iam.googleapis.com/locations/global/workforcePools/POOL_ID/group/GROUP_ID format to specify all workforce identities in a group or use the group:GROUP_NAME@googlegroups.com format to specify a Google group.

  5. Click Add identities.

  6. Click Save.

For information about the other egress rule attributes, see Egress rules reference.

gcloud

You can configure an egress rule to use identity groups using a JSON file or a YAML file. The following sample uses the YAML format:

- egressTo:
    operations:
    - serviceName: SERVICE_NAME
      methodSelectors:
      - method: METHOD_NAME
    resources:
    - projects/PROJECT_NUMBER
  egressFrom:
    identities:
    - PRINCIPAL_IDENTIFIER

Replace the following:

  • PRINCIPAL_IDENTIFIER: specify a Google group or a third-party identity that can access the specified resources outside the perimeter. To specify an identity group, use the format specified in IAM v1 API Principal identifiers.

    VPC Service Controls supports only the v1 identities that start with the group, principal, and principalSet prefixes in the IAM v1 API Principal identifiers. For example, use the principalSet://iam.googleapis.com/locations/global/workforcePools/POOL_ID/group/GROUP_ID format to specify all workforce identities in a group or use the group:GROUP_NAME@googlegroups.com format to specify a Google group.

For information about the other egress rule attributes, see Egress rules reference.

After you update an existing egress rule to configure identity groups, you need to update the rule policies of the service perimeter:

gcloud access-context-manager perimeters update PERIMETER_ID --set-egress-policies=RULE_POLICY.yaml

Replace the following:

  • PERIMETER_ID: the ID of the service perimeter that you want to update.
  • RULE_POLICY: the path of the modified egress rule file.

For more information, see Updating ingress and egress policies for a service perimeter.

Limitations

  • Before using identity groups, understand the unsupported features in ingress and egress rules.
  • When you use identity groups in an egress rule, you can't set the resources field in the egressTo attribute to "*".
  • For information about ingress and egress rule limits, see Quotas and limits.

What's next