Restricting identities by domain

The Resource Manager provides a domain restriction constraint that can be used in organization policies to limit resource sharing based on domain or organization resource. This constraint allows you to restrict the set of identities that are allowed to be used in Identity and Access Management policies.

Note: If your organization was created on or after May 3, 2024, this constraint is enforced by default, with your domain listed as the only allowed value.

Organization policies can use this constraint to limit resource sharing to identities that belong to a particular organization resource. Alternatively, you can specify a set of one or more domains, and exceptions can be granted on a per-folder or per-project basis. For more information about adding exceptions, see Override the organization policy for a project.

The domain restriction constraint is not retroactive. Once a domain restriction is set, this limitation will apply to IAM policy changes made from that point forward, and not to any previous changes. The domain restriction constraint will apply to any IAM policy changes, including changes that a service agent makes in response to another action. For example, if you have an automated service that imports BigQuery datasets, a BigQuery service agent will make IAM policy changes on the newly created dataset. This action would be restricted by the domain restriction constraint and blocked.

For example, consider two related organizations: examplepetstore.com and altostrat.com. You have granted an examplepetstore.com identity an IAM role in altostrat.com. Later, you decided to restrict identities by domain, and implemented an organization policy with the domain restriction constraint in altostrat.com. In this case, the existing examplepetstore.com identities would not lose access in altostrat.com. From that point, you could only grant IAM roles to identities from the altostrat.com domain.

The domain restriction constraint is based on the iam.allowedPolicyMemberDomains list constraint.

Note: Your organization's domain is not automatically added to the allowed list of a policy when you set the domain restriction constraint. You must add your domain explicitly to maintain access. If your domain isn't added, and the Organization Policy Administrator role grant is then removed from all users, the organization policy would become inaccessible.

When this constraint is set on a Google Cloud organization resource, it affects all identities that are parented by that organization resource. When this constraint is set on a Google Workspace domain, it will affect all identities that are under that domain. This includes user accounts that are managed in the Google Workspace console and not from within the Google Cloud console.

Setting the organization policy

The domain restriction constraint is a type of list constraint. Google Workspace customer IDs and Google Cloud organization resource IDs can be added and removed from the allowed_values list of a domain restriction constraint. The domain restriction constraint does not support denying values, and an organization policy can't be saved with IDs in the denied_values list.

All domains associated with a Google Workspace account or organization resource listed in the allowed_values will be allowed by the organization policy. All other domains will be denied by the organization policy.

You can make an organization policy enforcing the domain restriction constraint conditional on any resource included in the list of supported resources. For example, Cloud Storage buckets, BigQuery datasets, or Compute Engine VMs.

You must have permission to modify organization policies to set this constraint. For example, the orgpolicy.policyAdmin role has permission to set organization policy constraints. The resourcemanager.organizationAdmin role has permission to add a user as an Organization Policy Administrator. Read the Using Constraints page to learn more about managing policies at the organization level.

Console

To set an organization policy including a domain restriction constraint, do the following:

1. In the Google Cloud console, go to the Organization policies page.

   Go to Organization policies

2. From the project picker, select the organization resource on which you want to set the organization policy.

3. On the Organization policies page, select Domain Restricted Sharing from the list of constraints.

4. On the Policy details page, click Manage policy.

5. Under Applies to, select Override parent's policy.

6. Click Add a rule.

7. Under Policy values, select custom. Note: The domain restriction constraint does not support Deny All.

8. Under Policy type, select Allow. Note: The domain restriction constraint does not support Deny values.

9. Under Custom values, enter an organization resource ID or Google Workspace customer ID into the field.

10. If you want to add multiple IDs, click New policy value to create an additional field.

11. Click Done.

12. Optionally, to make the domain restriction constraint conditional on a tag, click Add condition.

    1. In the Title field, enter a name for the condition.

    2. In the Description field, give your condition a description. The description provides context on the tags that are required and how they impact resources.

    3. You can use the Condition builder to create a condition that requires a particular tag for the constraint to take effect.

       1. In the Condition type dropdown menu in the Condition builder tab, select Tag.

       2. Select the Operator for your condition. To match an entire tag, use the matches operator. To match a tag key and a tag value, use the matches ID operator.

       3. If you selected the matches operator, enter the value namespaced name of the tag. If you selected the matches ID operator, enter the key and value IDs.

       4. You can create multiple conditions by clicking Add. If you add another condition, you can set the conditional logic to require all of them by toggling And. You can set the conditional logic to require only one of the conditions to be true by toggling Or.

       5. You can delete an expression by clicking the large X to the right of the condition fields.

       6. When you have finished editing your conditions, click Save.

13. To enforce the policy, click Set policy.

gcloud

Policies can be set through the Google Cloud CLI. To create a policy that includes the domain restriction constraint, run the following command:

To set an organization policy that includes the domain restriction constraint, run the following command:

gcloud org-policies set-policy POLICY_PATH

Where POLICY_PATH is the full path to your organization policy YAML file, which should look like the following:

name: organizations/ORGANIZATION_ID/policies/iam.allowedPolicyMemberDomains
spec:
  rules:
  - condition: # This condition applies to the values block.
      expression: "resource.matchTag('ORGANIZATION_ID/environment', 'dev')"
    values:
      allowedValues:
      - PRINCIPAL_SET
  - values:
      allowedValues:
      - PRINCIPAL_SET

Replace the following:

• ORGANIZATION_ID with the ID of the organization resource on which to set this policy.

• PRINCIPAL_SET for Cloud Identity principal identifiers you want to allow, including organization resource ID. For example, is:principalSet://iam.googleapis.com/organizations/01234567890123.

  Google Workspace customer IDs must be used for all other identities you want to allow. For example, is:C03g5e3bc.

Only identities belonging to the organization resource ID or Google Workspace domain from the list of allowed_values will be allowed on IAM policies once this organization policy has been applied. Google Workspace human users and groups must be children of that organization resource or part of that Google Workspace domain, and IAM service accounts must be children of an organization resource associated with the given Google Workspace domain.

For example, if you created an organization policy with only the customer ID of your company's Google Workspace, only principals from that domain could be added to the IAM policy from that point forward.

To learn more about using constraints in organization policies, see Using Constraints.

Example error message

When the domain restriction organization constraint is violated by trying to add a principal that is not included in the allowed_values list, the operation will fail and then an error message will be displayed.

Console

gcloud

ERROR: (gcloud.projects.set-iam-policy) FAILED_PRECONDITION:
One or more users named in the policy do not belong to a permitted customer.

Retrieving an organization resource ID

You can get your organization resource ID using the Google Cloud console, the gcloud CLI, or the Cloud Resource Manager API.

console

To get your organization resource ID using the Google Cloud console, do the following:

1. Go to the Google Cloud console:

   Go to the Google Cloud console

2. From the project picker at the top of the page, select your organization resource.
3. On the right side, click More, and then click Settings.
   

The Settings page displays your organization resource ID.

gcloud

To find your organization resource ID, run the following command:

gcloud organizations list

This command lists all the organization resources to which you belong to, and their corresponding organization resource IDs.

API

To find your organization resource ID using the Cloud Resource Manager API, use the organizations.search() method, including a query for your domain. For example:

GET https://cloudresourcemanager.googleapis.com/v3/organizations:search{query=domain:altostrat.com}

The response contains the metadata of the organization resource that belongs to altostrat.com, which includes the organization resource ID.

After you have your organization resource ID, you need to use the correct identifier for the set of principals belonging to it. For example:

principalSet://iam.googleapis.com/organizations/01234567890123

For more information about IAM principal identifiers, see Principal identifiers.

Retrieving a Google Workspace customer ID

The Google Workspace customer ID used by the domain restriction constraint can be obtained in two ways:

gcloud

The gcloud organizations list command can be used to see all organizations for which you have the resourcemanager.organizations.get permission:

gcloud organizations list

This command will return the DISPLAY_NAME, ID (Organization ID), and DIRECTORY_CUSTOMER_ID. The Google Workspace customer ID is the DIRECTORY_CUSTOMER_ID.

API

The Google Workspace Directory API can be used to retrieve a Google Workspace customer ID.

While logged in as a Google Workspace admin, you can visit the Customers: get API method documentation and click Execute. After authorization, the response would show your customer ID.

Alternatively, you can use an API client:

1. Obtain an OAuth access token for the https://www.googleapis.com/auth/admin.directory.customer.readonly scope.

2. Run the following command to query the Google Workspace directory API:

   curl -# -X GET "https://www.googleapis.com/admin/directory/v1/customers/customerKey" \
   -H "Authorization: Bearer $access_token" -H "Content-Type: application/json"
   

This command will return a JSON response including the customer's information. The Google Workspace customer ID is the id.

Restricting subdomains

If you allow a Google Cloud organization resource in a domain restriction constraint, it allows access to all resources that are associated with that organization resource, and blocks access to all others.

If you allow a Google Workspace customer ID in a domain restriction constraint, it limits access to all domains that are associated with that Google Workspace customer ID, and blocks access to all others. Every Google Workspace account has exactly one primary domain, and zero or more secondary domains. All domains that are associated with the Google Workspace customer ID will be subject to the constraint.

Enforcing the domain restriction constraint on a resource controls the primary domain and all secondary domains that can access that resource and its descendants in the resource hierarchy.

For examples on common Google Workspace domain and subdomain combinations, see the table below:

Primary domain	Subdomain	Domain restriction constraint	Is [e-mail] allowed?
altostrat.com	none	Allow: altostrat.com	No
altostrat.com	sub.altostrat.com	Allow: altostrat.com	Yes
altostrat.com	sub.altostrat.com	Allow: sub.altostrat.com	Yes
sub.altostrat.com	altostrat.com	Allow: sub.altostrat.com	Yes
sub.altostrat.com	none	Allow: sub.altostrat.com	Yes

To differentiate domain restriction constraint access between two domains, each domain must be associated with a different Google Workspace account. Each Google Workspace account is associated with an organization node, and can have their own organization policies applied. This allows you to associate altostrat.com with one Google Workspace account, and sub.altostrat.com with another for more granular access control. For more information, see Managing Multiple Organizations.

Troubleshooting known issues

Organization policies are not retroactive. If you need to force a change to your resource hierarchy that would violate an enforced constraint, you can disable the organization policy, make the change, and then enable the organization policy again.

The following sections describe known issues with services that can occur when this constraint is enforced.

Linking Google Analytics 360 with BigQuery

If you attempt to link Google Analytics 360 with BigQuery where the domain restriction constraint is enforced, the action fails with the One or more users named in the policy do not belong to a permitted customer error message, even if the [e-mail] service account is already added as Editor at the project level, either directly or using Google Groups.

To link Google Analytics 360 with BigQuery, do the following:

1. Disable the organization policy containing the domain restriction constraint.

2. Do the linking process in Google Analytics 360.

3. Enforce the domain restriction constraint again.

Public data sharing

Some Google Cloud products such as BigQuery, Cloud Run functions, Cloud Run, Cloud Storage, and Pub/Sub support public data sharing. Enforcing the domain restricted sharing constraint in an organization policy will prevent public data sharing.

To publicly share data, disable the domain restricted sharing constraint temporarily for the Project resource where the data you want to share resides. After you share the resource publicly, you can then re-enable the domain restricted sharing constraint.

BigQuery log sink for a billing account

The service account used by BigQuery log sink for billing accounts (format: b*@*.iam.gserviceaccount.com) is treated as external and blocked by the domain restricted sharing constraint in an organization policy. To grant this service account a role on a BigQuery dataset in a project that has the domain restriction constraint enforced:

1. Disable the organization policy containing the domain restriction constraint.

2. Grant the corresponding service account (format: b*@*.iam.gserviceaccount.com) the BigQuery role indicated during the sink creation process.

3. Enforce the domain restriction constraint again.

Cloud Billing export service account

Enabling billing export to a bucket with this constraint enabled will probably fail. Do not use this constraint on buckets used for billing export.

The Cloud Billing export service account email address is: [e-mail]

Enable storage access logging

If enabled, the domain restriction constraint will block any domain not specifically allowed in the organization policy. This will prevent granting Google service accounts access as well. To set up storage access logging on a Cloud Storage bucket that has the domain restriction constraint enforced, do the following:

1. Disable the organization policy containing the domain restriction constraint.

2. Grant [e-mail] WRITE access to that bucket.

3. Enforce the domain restriction constraint again.

Granting service agent roles

Service agent roles are only granted to service accounts. If you need to grant this type of role, do the following:

1. Disable the organization policy containing the domain restriction constraint.

2. Grant the service agent role.

3. Enforce the domain restriction constraint again.

Enable Firebase API

If enabled, the domain restriction constraint will block service accounts that are not allowed in the organization policy. This makes it impossible to enable the Firebase API, which requires external service accounts during the process of enabling the API. Once the API has been enabled, you can safely enforce the domain restriction constraint without interfering with the function of the Firebase API. To enable the Firebase API:

1. Disable the organization policy containing the domain restriction constraint.

2. Enable the Firebase Management API.

3. Enforce the domain restriction constraint again.

Google groups

If the domain restriction constraint is enforced in your organization, then you might not be able to grant roles to newly created Google groups, even if the groups belong to an allowed domain. This is because it can take up to 24 hours for a group to fully propagate through Google Cloud. If you can't grant a role to a newly created Google group, wait 24 hours and then try again.

Additionally, when evaluating whether a group belongs to an allowed domain, IAM only evaluates the group's domain. It doesn't evaluate the domains of any of the group's members. As a result, project administrators can bypass the domain restriction constraint by adding outside members to Google groups, and then granting roles to those Google groups.

To ensure that project administrators can't bypass the domain restriction constraint, the Google Workspace administrator should ensure that group owners cannot allow members from outside of the domain in the Google Workspace administrator panel.

Forcing account access

If you need to force account access for a project in violation of domain restrictions:

1. Remove the organization policy containing the domain restriction constraint.

2. Grant account access to the project.

3. Implement the organization policy with the domain restriction constraint again.

Alternatively, you can grant access to a Google group that contains the relevant service accounts:

1. Create a Google group within the allowed domain.

2. Use the Google Workspace administrator panel to turn off domain restriction for that group.

3. Add the service account to the group.

4. Grant access to the Google group in the IAM policy.

Use Pub/Sub as an endpoint for a Google Chat app.

When you are trying to grant publish rights on your topic to the Google Chat API service account, you may be blocked if the Restricted Domain Sharing constraint is enabled. Follow the process to force the account access.