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. This constraint allows you to restrict the set of identities that are allowed to be used in Identity and Access Management policies.

Organization policies can use this constraint to limit resource sharing to a specified set of one or more Google Workspace 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.

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: The parent organization is not automatically added to the allowed list of a policy when you set the domain restriction constraint. You must add your organization explicitly to maintain access. If the parent organization is not 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 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 can be added and removed from the allowed_values list of a domain restriction constraint. All domains associated with that Google Workspace account will be affected by the organization policy.

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:

1. Go to the Organization policies page in the Cloud Console.
   Go to the Organization policies page
2. Click Select.
3. Select the organization you want to set the policy for.
4. Click Domain Restricted Sharing.
5. Click the Edit button.
6. Under Applies to, select Customize.
7. Under Policy values, select Custom.
8. Enter a Google Workspace customer ID into the Policy value text box, then press Enter. Multiple IDs can be entered in this way.
9. Click Save. A notification will appear to confirm that the policy has been updated.

gcloud

Policies can be set through the gcloud command-line tool. To create a policy that includes the domain restriction constraint, run the following command:

gcloud resource-manager org-policies allow \
    --organization 'ORGANIZATION_ID' \
    iam.allowedPolicyMemberDomains 'DOMAIN_ID_1' \
    'DOMAIN_ID_2'

Where:

• ORGANIZATION_ID is the ID of the organization node to set this policy on.
• DOMAINID# is the one or more Google Workspace customer IDs you want to allow access to.

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

Example organization policy

The following code snippet shows an organization policy including the domain restriction constraint:

resource: "organizations/842463781240"
policy {
  constraint: "constraints/iam.allowedPolicyMemberDomains"
  etag: "\a\005L\252\122\321\946\334"
  list_policy {
  allowed_values: "C03xgje4y"
  allowed_values: "C03g5e3bc"
  allowed_values: "C03t213bc"
  }
}

The allowed_values are Google Workspace customer IDs, such as C03xgje4y. Only identities belonging to a 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 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 members from that domain could be added to the IAM policy from that point forward.

Example error message

When the domain restriction organization constraint is violated by trying to add a member 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 in the policy do not belong to a permitted customer.

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

The domain restriction constraint functions by limiting access to all domains that are associated with a given Google Workspace customer ID. 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.

Applying the domain restriction constraint to 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?
domain.com	none	Allow: domain.com	No
domain.com	sub.domain.com	Allow: domain.com	Yes
domain.com	sub.domain.com	Allow: sub.domain.com	Yes
sub.domain.com	domain.com	Allow: sub.domain.com	Yes
sub.domain.com	none	Allow: sub.domain.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 domain.com with one Google Workspace account, and sub.domain.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.

Public data sharing

Some Google Cloud products such as BigQuery, Cloud 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.

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:

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

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

3. Implement the organization policy with 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. Remove the organization policy containing the domain restriction constraint.

2. Enable the Firebase Management API.

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

Google groups

Google groups created within an allowed domain can be always be granted roles in the IAM policy when the domain restriction constraint is enforced even if the group contains members from outside of that domain.

To ensure that project administrators cannot 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.