Organization policy constraints

This document describes how to use Organization Policy Service to manage Conversational Analytics API resources.

The Organization Policy Service provides centralized control over your Google Cloud resources through constraints that restrict how resources can be configured and used. You can apply these constraints to data agents and conversations at the organization, folder, or project level. By default, child resources inherit the policies of their parent resources.

To enforce a constraint, you create an organization policy and attach it to a resource in your resource hierarchy. You can set and manage these policies by using the Google Cloud console or the gcloud CLI. For detailed instructions, see Creating and managing organization policies.

Before you begin

Before you can apply organization policies to restrict Conversational Analytics API resources, ensure that you have the required Identity and Access Management (IAM) roles.

Required roles

To get the permissions that you need to manage or view organization policies, ask your administrator to grant you the following IAM roles:

For more information about granting roles, see Manage access to projects, folders, and organizations.

You might also be able to get the required permissions through custom roles or other predefined roles.

Predefined constraints

You can apply organization policies that use the following predefined constraints to restrict Conversational Analytics API resources. If you don't set an organization policy for a constraint, the default behavior is to allow all relevant actions.

Constraint Description Default behavior
gcp.restrictServiceUsage Restricts whether the Conversational Analytics API service can be used in your resource hierarchy. Using the Conversational Analytics API service is not restricted.
gcp.resourceLocations Limits the locations where data agents and conversations can be created. Conversational Analytics API resources can be created in any supported location.
gcp.restrictNonCmekServices Requires that resources be protected by customer-managed encryption keys (CMEK). CMEK protection is not required for new Conversational Analytics API resources.
gcp.restrictCmekCryptoKeyProjects Limits the projects, folders, and organizations that can provide encryption keys for CMEK. No restrictions are placed on the sources of encryption keys.

Restrict service usage

The constraints/gcp.restrictServiceUsage constraint lets you control which Google Cloud services can be used in your resource hierarchy.

To restrict the Conversational Analytics API, you can add the Gemini Data Analytics service (geminidataanalytics.googleapis.com) to a denylist for this constraint, or you can omit it from an allowlist.

If you use an allowlist, you must also include any underlying data source services that the API uses, such as the BigQuery service (bigquery.googleapis.com) or the Looker (Google Cloud core) service (looker.googleapis.com). If any of these services are restricted, then users can't create or interact with data agents and conversations.

Restrict resource locations

The constraints/gcp.resourceLocations constraint limits the creation of new Conversational Analytics API data agents and conversations to specified Google Cloud locations. For a list of supported regions and multi-regions for the API, see Conversational Analytics API locations.

If this policy is enforced, any attempt to create a resource within a denied location fails. Existing Conversational Analytics API resources are not affected by changes to this policy.

To learn how to specify locations in your organization policy, see Restrict resource locations.

Require CMEK protection

The constraints/gcp.restrictNonCmekServices constraint lets you require customer-managed encryption keys (CMEK) protection for Conversational Analytics API resources.

When this constraint is configured to deny the Gemini Data Analytics (geminidataanalytics.googleapis.com) service, new Conversational Analytics API data agents and conversations must be protected by CMEK. If you attempt to create a resource without specifying a Cloud KMS key, then the Conversational Analytics API blocks the request.

Restrict CMEK keys

The constraints/gcp.restrictCmekCryptoKeyProjects constraint lets you limit the projects, folders, and organizations that can provide Cloud KMS keys for CMEK protection.

When you configure this constraint, Conversational Analytics API resources that use CMEK must use a key that belongs to an allowed project, folder, or organization. If you attempt to create a resource by using a key from a project that isn't in the allowlist, then the Conversational Analytics API blocks the request.

Troubleshoot policy violations

If a request violates an organization policy, the Conversational Analytics API returns an error with an HTTP status code of 403 Forbidden. The error message includes the name of the constraint that was violated.

The following example shows an error message for a request that violates the gcp.restrictServiceUsage constraint:

{
  "error": {
    "code": 403,
    "message": "Request is disallowed by organization's constraints/gcp.restrictServiceUsage constraint for projects/PROJECT_ID attempting to use service geminidataanalytics.googleapis.com.",
    "status": "PERMISSION_DENIED",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "SECURITY_POLICY_VIOLATED",
        "domain": "googleapis.com",
        "metadata": {
          "service": "geminidataanalytics.googleapis.com",
          "consumer": "projects/PROJECT_ID"
        }
      }
    ]
  }
}

The error message includes the technical name of the constraint, but it doesn't include the human-readable description of the constraint. To understand the requirements of a specific constraint, see the descriptions in Predefined constraints.

What's next