Restringir o uso de endpoints

Nesta página, você encontra uma visão geral da restrição de uso de endpoint da política da organização, que permite aos administradores corporativos controlar quais endpoints da API Google Cloud podem ser usados na hierarquia de recursos Google Cloud .

Os administradores podem usar essa restrição para definir restrições hierárquicas em endpoints de API Google Cloud permitidos, como endpoints globais, locais ou regionais. Por exemplo, é possível configurar um projeto para negar solicitações ao endpoint global bigquery.googleapis.com, mas permitir solicitações ao endpoint regional LOCATION-biguery.googleapis.com. Ao restringir o uso endpoint de API globais, as organizações podem atender aos requisitos de compliance garantindo que apenas os endpoints locais ou regionais permitidos sejam usados.

A restrição "Restringir uso de endpoint" é definida usando uma lista de bloqueio, permitindo solicitações para endpoints de API de qualquer serviço compatível que não seja explicitamente negado.

Essa restrição controla o acesso ao ambiente de execução para todos os recursos no escopo. Quando a política da organização que contém essa restrição é atualizada, ela é aplicada imediatamente a todos os recursos no escopo da política, com consistência eventual.

Recomendamos que os administradores gerenciem cuidadosamente as atualizações das políticas da organização que contêm essa restrição. Por exemplo, considere definir a política no modo de simulação para monitorar como uma mudança afetaria seus fluxos de trabalho atuais antes de ela ser aplicada.

Tipos de endpoint de API

Um endpoint de API (ou endpoint de serviço) é um URL que especifica o endereço de rede de um serviço de API Google Cloud , como bigquery.googleapis.com. OsGoogle Cloud services permitem o acesso a recursos usando diferentes tipos de endpoints de API, incluindo globais, locais e regionais. O suporte para cada tipo depende do serviço.

• Os endpoints globais da API não especificam o local no nome do host do URL. Exemplo:

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

  Esses endpoints de escopo global fornecem endpoints de serviço altamente disponíveis que encerram a sessão TLS o mais próximo possível do cliente, o que minimiza a latência ao atender chamadas de API de uma população de clientes dispersa pela Internet.

• Os endpoints de API de localização especificam o local no nome do host do URL. Exemplo:

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

  Esses endpoints oferecem benefícios aos clientes que precisam usar serviços específicos de local e querem garantir que os dados em trânsito permaneçam em um local específico quando acessados por conectividade particular.

• Os endpoints regionais da API especificam o local como um subdomínio. Exemplo:

  • 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

  Esses endpoints regionais oferecem mais benefícios para clientes que precisam usar serviços específicos de localidade e querem garantir que os dados em trânsito permaneçam em um local específico quando acessados por conectividade particular ou pela Internet pública.

Limitações

A restrição "Restringir o uso de endpoints" controla a capacidade de usar endpoints de API específicos para acessar seus recursos. Não confunda com outras restrições semelhantes, como:

• Restringir a restrição de local de recursos, que controla onde os recursos podem ou não ser criados.
• A restrição "Restringir o uso do serviço de recurso", que controla quais serviços de recursos podem ser usados.

Para evitar a quebra da infraestrutura de veiculação atual, teste qualquer nova política da organização em projetos e pastas que não sejam de produção e aplique a política gradualmente na organização.

Essa restrição se aplica a um subconjunto específico de produtos e tipos de recursos. Para conferir uma lista de serviços compatíveis e detalhes sobre o comportamento de cada um, consulte a seção Endpoints de API compatíveis.

Para compromissos de armazenamento de dados, consulte os Google Cloud Termos de Serviço e os Termos Específicos do Serviço. As políticas da organização que contêm a restrição "Restringir o uso de endpoint" não são compromissos de residência de dados.

Como definir a política da organização

Para definir, alterar ou excluir uma política da organização, você precisa ter o papel Administrador da Política da organização.

As restrições de política da organização podem ser definidas no nível da organização, da pasta e do projeto. Cada política se aplica a todos os recursos na hierarquia de recursos correspondente, mas pode ser substituída em níveis inferiores da hierarquia.

Para mais informações sobre avaliação de política, consulte Noções básicas sobre avaliação de hierarquia.

A restrição "Restringir o uso de endpoints" é um tipo de restrição de lista. É possível adicionar e remover endpoints das listas denied_values da restrição.

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'

Se uma solicitação para um endpoint de API negado tentar acessar um recurso, ela vai falhar, e um erro será retornado descrevendo o motivo dessa falha.

Criar uma política da organização no modo de teste

Uma política da organização em modo de simulação é um tipo de política em que as violações são registradas em auditoria, mas as ações violadoras não são negadas. É possível criar uma política da organização no modo de simulação usando a restrição Restringir o uso de endpoint para monitorar como ela afetaria sua organização antes de aplicar a política ativa. Para mais informações, consulte Criar uma política da organização no modo de simulação.

Mensagem de erro

Se você definir uma política da organização para negar um endpoint, as operações que usam esse endpoint na hierarquia de recursos vão falhar. Um erro é retornado descrevendo o motivo dessa falha. Além disso, uma entrada de registro de auditoria é gerada para monitoramento, alerta ou depuração.

Exemplo de mensagem de erro

No exemplo a seguir, uma solicitação curl usando o endpoint de API storage.googleapis.com falha devido à aplicação da política:

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.restrictEndpointUsage organization policy constraint. To
access this resource, please use an allowed endpoint.

Exemplo de entrada de registro de auditoria

O exemplo de entrada de registro de auditoria a seguir demonstra quando o acesso a um recurso é negado:

{
  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"
}

Endpoints de API compatíveis

Os seguintes endpoints de API são compatíveis com a restrição "Restringir o uso de endpoints":

Grupos de valores

Grupos de valores são conjuntos de grupos e endpoints de API selecionados pelo Google para oferecer uma maneira mais simples de definir restrições de endpoint. Os grupos de valores incluem muitos endpoints de API relacionados e são expandidos ao longo do tempo pelo Google sem a necessidade de mudar a política da sua organização para acomodar os novos endpoints.

Para usar grupos de valores na sua política da organização, insira a string in: no prefixo das entradas. Para mais informações sobre o uso de valores prefixo, consulte Usando restrições. Os nomes dos grupos são validados na chamada para definir a política da organização. Usar um nome de grupo inválido vai fazer com que a definição da política falhe.

A tabela a seguir contém a lista atual de grupos disponíveis: