Restricting endpoint usage

This page provides an overview of the Restrict Endpoint Usage organization policy constraint, which allows enterprise administrators to control which Google Cloud API endpoints can be used within their Google Cloud resource hierarchy.

Administrators can use this constraint to define hierarchical restrictions on allowed Google Cloud API endpoints, such as global, locational, or regional endpoints. For example, you can configure a project to deny requests to the global bigquery.googleapis.com endpoint, but allow requests to the locational LOCATION-biguery.googleapis.com endpoint. By restricting global API endpoint usage, organizations can meet compliance requirements by ensuring that only allowed locational or regional endpoints are used.

The Restrict Endpoint Usage constraint is set using a denylist, allowing requests to any supported services' API endpoints that are not explicitly denied.

This constraint controls the runtime access to all in-scope resources. When the organization policy containing this constraint is updated, it immediately applies to all resources within the scope of the policy, with eventual consistency.

We recommend that administrators carefully manage updates to organization policies containing this constraint. For example, you should consider setting the policy in dry-run mode to monitor how a policy change would impact your existing workflows before it is enforced.

API endpoint types

An API endpoint (or service endpoint) is a URL that specifies the network address of a Google Cloud API service, such as bigquery.googleapis.com. Google Cloud services allow access to resources using different types of API endpoints, including global, locational, and regional endpoints. Support for each type depends on the service.

• Global API endpoints don't specify the location in the URL hostname. For example:

  • storage.googleapis.com
  • content-bigqueryconnection.googleapis.com
  • bigquerydatatransfer.mtls.googleapis.com
  • logging.googleapis.com

  These globally-scoped endpoints provide highly-available service endpoints that terminate the TLS session as close to the client as possible, which minimizes latency when serving API calls from a dispersed client population over the internet.

• Locational API endpoints specify the location in the URL hostname. For example:

  • us-storage.googleapis.com
  • content-us-west3-bigqueryconnection.googleapis.com
  • us-west1-bigquerydatatransfer.mtls.googleapis.com
  • us-central1-logging.googleapis.com

  These locational endpoints offer benefits to customers who require the use of location-specific services, and want to ensure that in-transit data remains in a particular location when accessed through private connectivity.

• Regional API endpoints specify the location as a sub-domain. For example:

  • storage.us-east2.rep.googleapis.com
  • content-bigqueryconnection.us-west3.rep.googleapis.com
  • bigquerydatatransfer.us-west1.rep.mtls.googleapis.com
  • logging.us-central1.rep.googleapis.com

  These regional endpoints offer the most benefits to customers who require the use of location-specific services, and want to have ways to ensure that in-transit data remains in a particular location when accessed through either private connectivity or the public internet.

Limitations

The Restrict Endpoint Usage constraint controls the ability to use specific API endpoints to access your resources. It shouldn't be confused with other similar constraints, such as:

• Restrict Resource Location constraint, which controls where resources can or cannot be created.
• Restrict Resource Service Usage constraint, which controls which resource services can be used.

To avoid breaking existing serving infrastructure, you should test any new organization policy on non-production projects and folders, then apply the policy gradually within your organization.

This constraint applies to a specific subset of products and resource types. For a list of supported services and details on the behavior of each service, see the Supported API endpoints section.

For data storage commitments, see the Google Cloud Terms of Service and the Service Specific Terms. Organization policies that contain the Restrict Endpoint Usage constraint are not data residency commitments.

Setting the organization policy

To set, change, or delete an organization policy, you must have the Organization Policy Administrator role.

Organization policy constraints can be set at the organization, folder, and project level. Each policy applies to all resources within its corresponding resource hierarchy, but can be overridden at lower levels in the resource hierarchy.

For more information about policy evaluation, see Understanding Hierarchy Evaluation.

The Restrict Endpoint Usage constraint is a type of list constraint. You can add and remove endpoints from the denied_values lists of the constraint.

constraint: constraints/gcp.restrictEndpointUsage
listPolicy:
    deniedValues:
    - storage.googleapis.com
    - content-bigqueryreservation.googleapis.com
    - bigquerystorage.mtls.googleapis.com
    - logging.googleapis.com

gcloud resource-manager org-policies set-policy \
--RESOURCE_TYPE='RESOURCE_ID' /tmp/policy.yaml

constraint: constraints/gcp.restrictEndpointUsage
etag: CKCRl6oGEPjG-tMB
listPolicy:
  deniedValues:
  - storage.googleapis.com
  - content-bigqueryreservation.googleapis.com
  - bigquerystorage.mtls.googleapis.com
  - logging.googleapis.com
updateTime: '2023-11-04T04:29:20.444507Z'

If a request to a denied API endpoint attempts to access a resource, the request will fail, and an error is returned that describes the reason for this failure.

Create an organization policy in dry-run mode

An organization policy in dry-run mode is a type of organization policy where violations of the policy are audit logged, but the violating actions aren't denied. You can create an organization policy in dry-run mode using the Restrict Endpoint Usage constraint to monitor how it would affect your organization before you enforce the live policy. For more information, see Create an organization policy in dry-run mode.

Error message

If you set an organization policy to deny an endpoint, operations using that endpoint within your resource hierarchy fail. An error is returned that describes the reason for this failure. Also, an audit log entry is generated for further monitoring, alerting, or debugging.

Example error message

In the following example, a curl request using API endpoint storage.googleapis.com fails due to policy enforcement:

curl -X GET \
-H "Authorization: Bearer OAUTH2_TOKEN" \
-o "SAVE_TO_LOCATION" \
"https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME?alt=media"

Access to projects/foo-123 through endpoint storage.googleapis.com was denied by
the constraints/gcp.endpointUsageRestriction organization policy constraint. To
access this resource, please use an allowed endpoint.

Example audit log entry

The following example audit log entry demonstrates when access to a resource is denied:

{
  logName: "projects/my-projectid/logs/cloudaudit.googleapis.com%2Fpolicy"
  protoPayload: {
    @type: "type.googleapis.com/google.cloud.audit.AuditLog"
    status: {
      code: 7
      message: "Access to projects/my-projectid through endpoint bigquery.googleapis.com was denied by the constraints/gcp.restrictEndpointUsage organization policy constraint. To access this resource, please use an allowed endpoint."
    }
    serviceName: "bigquery.googleapis.com"
    methodName: "google.cloud.bigquery.v2.TableDataService.InsertAll"
    resourceName: "projects/my-projectid"
    authenticationInfo: {
      principalEmail: "user_or_service_account@example.com"
    }
  }
  requestMetadata: {
    callerIp: "123.123.123.123"
  }
  policyViolationInfo: {
    orgPolicyViolationInfo: {
      violationInfo: [
        {
          constraint: "constraints/gcp.restrictEndpointUsage"
          checkedValue: "bigquery.googleapis.com"
          policyType: LIST_CONSTRAINT
        }
      ]
    }
  }
  resource: {
    type: "audited_resource"
    labels: {
      project_id: "224034263908"
      method: "google.cloud.bigquery.v2.TableDataService.InsertAll"
      service: "bigquery.googleapis.com"
    }
  }
  severity: "ERROR"
  timestamp: "2024-12-05T01:15:30.332519510Z"
  receiveTimestamp: "2024-08-15T17:55:01.159788588Z"
  insertId: "42"
}

Supported API endpoints

The following API endpoints are supported by the Restrict Endpoint Usage constraint:

Value groups

Value groups are collections of groups and API endpoints that are curated by Google to provide a simpler way to define your endpoint restrictions. Value groups include many related API endpoints and are expanded over time by Google without needing to change your organization policy to accommodate the new endpoints.

To use value groups in your organization policy, prefix your entries with the string in:. For more information on using value prefixes, see Using Constraints. Group names are validated on the call to set the organization policy. Using an invalid group name will cause the policy setting to fail.

The following table contains the current list of available groups: