Controlar o acesso de publicação

O Identity and Access Management (IAM) oferece vários tipos de políticas para ajudar você a controlar quais recursos os principais podem acessar. Neste guia, descrevemos como usar políticas de acesso para controlar o acesso ao publicar mensagens de eventos em um barramento do Eventarc Advanced.

As políticas de acesso do IAM podem permitir e negar o acesso a recursos. No entanto, ao contrário das políticas de permissão e negação do IAM, as políticas de acesso podem conceder ou negar o acesso com base em atributos específicos do contexto do evento, como a prioridade da mensagem do evento.

Cada política de acesso é um conjunto de regras que permite identificar principais e definir condições que determinam a aplicabilidade de uma regra, além de permitir o controle de acesso refinado. Por exemplo, dependendo da avaliação de uma expressão da Common Expression Language (CEL) aplicada a um atributo de contexto de evento, é possível permitir ou negar a permissão para publicar um subconjunto de mensagens de evento em um barramento do Eventarc Advanced.

Neste guia, explicamos como criar e aplicar uma política de acesso. Primeiro, crie uma política de acesso e, em seguida, uma vinculação para conectar essa política a um projeto Google Cloud .

Antes de começar

Antes de criar e aplicar uma política de acesso, você precisa ter criado um barramento Eventarc Advanced em que as mensagens de evento podem ser publicadas.

  1. Você precisa desativar a aplicação da restrição gerenciada Desativar a política de acesso de vinculação ao recurso (constraints/iam.managed.disableAccessPolicyBindings). Por padrão, essa restrição booleana é ativada para novas organizações e impede que você vincule uma política de acesso à API IAM v3 a um recurso. Para mais informações, consulte Como atualizar políticas com regras booleanas.

  2. Considere o seguinte:

    • As políticas de acesso precisam ser aplicadas ou vinculadas a um projeto Google Cloud . Cada política de acesso pode ser anexada a até cinco projetos, e cada projeto pode ter até cinco políticas de acesso anexadas. É possível criar um barramento por projeto do Google Cloud por região compatível. Uma política de acesso anexada a um projeto controla o acesso de publicação a qualquer barramento do Eventarc Advanced nesse projeto.

    • É possível usar políticas de acesso para controlar o acesso de publicação a um barramento Eventarc Advanced, mas não para controlar o acesso à assinatura de mensagens de um barramento específico. A permissão aceita é eventarc.messageBuses.publish.

    • O controle de acesso pode ser baseado apenas em atributos de contexto do evento, e não no conteúdo da carga útil do evento.

    • As mensagens de eventos que são publicadas de fontes do Google e que são negadas são descartadas. Se o principal publicar diretamente uma mensagem de evento, uma mensagem de registro Event published successfully vai indicar isso. No entanto, se a mensagem de evento for negada pela condição na política de acesso, ocorrerá um erro semelhante a este:

      ERROR: (gcloud.beta.eventarc.message-buses.publish)
PERMISSION_DENIED: Permission 'eventarc.googleapis.com/messageBuses.publish' denied on resource due to an IAM Access Policy.
This command is authenticated as user@example.com which is the active account specified by the [core/account] property.
'@type': type.googleapis.com/google.rpc.ErrorInfo
domain: iam.googleapis.com
metadata:
permission: eventarc.googleapis.com/messageBuses.publish
reason: IAM_PERMISSION_DENIED

  3. Se ainda não tiver feito isso, ative as APIs Eventarc e IAM:

    gcloud services enable eventarc.googleapis.com \
    eventarcpublishing.googleapis.com \
    iam.googleapis.com

  4. Configure a autenticação:

    gcloud

    Instale a Google Cloud CLI e faça login na CLI gcloud com sua identidade federada. Depois de fazer login, inicialize a Google Cloud CLI executando o seguinte comando: 

    gcloud init

    API REST

    Para usar as amostras da API REST nesta página em um ambiente de desenvolvimento local, use as credenciais fornecidas para a CLI gcloud.

      Instale a Google Cloud CLI e faça login na CLI gcloud com sua identidade federada.

    Saiba mais em Autenticar para usar REST na documentação de autenticação do Google Cloud .

Funções exigidas

Um papel do IAM contém um conjunto de permissões que permite realizar ações específicas em recursos do Google Cloud .

Para receber as permissões necessárias para controlar o acesso à publicação, peça ao administrador para conceder a você os seguintes papéis do IAM no projeto:

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Esses papéis predefinidos contêm as permissões necessárias para controlar o acesso de publicação. Para acessar as permissões exatas necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

As seguintes permissões são necessárias para controlar o acesso à publicação:

  • Crie políticas de acesso: iam.accessPolicies.create
  • Aplicar políticas de acesso:
    • iam.accessPolicies.bind
    • resourcemanager.projects.createPolicyBinding

Essas permissões também podem ser concedidas com funções personalizadas ou outros papéis predefinidos.

Criar uma política de acesso

Crie uma política de acesso para controlar o acesso ao publicar em um barramento do Eventarc Advanced no seu projeto.

É possível criar uma política de acesso usando a Google Cloud CLI ou fazendo uma solicitação direta à API IAM v3.

gcloud

Para criar uma política de acesso, execute o comando gcloud beta iam access-policies create.

gcloud beta iam access-policies create POLICY_ID \
    --project=POLICY_PROJECT_ID \
    --location=global \
    --details-rules=description="POLICY_DESCRIPTION",effect=EFFECT, \
    principals=[PRINCIPALS],excludedPrincipals=[EXCLUDED_PRINCIPALS], \
    operation={permissions=[eventarc.googleapis.com/messageBuses.publish]}, \
    conditions={eventarc.googleapis.com={expression="CEL_EXPRESSION"}}

Substitua:

  • POLICY_ID: um nome exclusivo para a política de acesso. Por exemplo, my-access-policy.
  • POLICY_PROJECT_ID: o ID do projeto Google Cloud em que a política será criada.
  • POLICY_DESCRIPTION: uma descrição opcional da política (máximo de 256 caracteres).
  • EFFECT: o efeito da regra (ALLOW ou DENY).
  • PRINCIPALS: as identidades a que esta regra se aplica. O formato do identificador depende do tipo de principal que você quer consultar. Para mais informações, consulte Tipos de principais para políticas de acesso.
  • EXCLUDED_PRINCIPALS: as identidades que são excluídas da aplicação da regra, mesmo que estejam listadas em principals. Por exemplo, você pode adicionar um Grupo do Google a principals e excluir usuários específicos que pertencem a ele.
  • CEL_EXPRESSION: a expressão CEL que será avaliada para determinar a aplicabilidade da regra. Por exemplo, message.version != \"v1\". Para mais informações, consulte Usar a Common Expression Language.

Observe o seguinte:

  • A flag --location especifica o local da política de acesso e precisa ser global.

  • A flag --details-rules pode especificar o caminho para o arquivo de política de acesso, que pode ser gravado em JSON ou YAML. Por exemplo, --details-rules=path_to_file.json.

    A flag também pode ser repetida ao configurar várias regras. Cada regra é avaliada de forma independente.

    Uma política de acesso usa o seguinte formato:

    {
  "displayName": "POLICY_DISPLAY_NAME",
  "details": {
    "rules": [
      {
        "description": "POLICY_DESCRIPTION",
        "effect": "EFFECT",
        "principals": [
          "PRINCIPALS"
        ],
        "excludedPrincipals": [
        "EXCLUDED_PRINCIPALS"
        ],
        "operation": {
          "permissions": ["eventarc.googleapis.com/messageBuses.publish"]
        },
        "conditions": {
          "eventarc.googleapis.com": {
              "expression": "CEL_EXPRESSION"
          }
        }
      }
    ]
  }
}

A resposta contém uma operação de longa duração que representa a solicitação. Para saber como conferir o status de uma operação de longa duração, consulte Verificar o status de uma operação de longa duração neste documento.

Exemplo

O comando a seguir cria uma política de acesso que permite que o principal especificado publique mensagens de evento em um barramento, mas nega a publicação quando o tipo de mídia de dados é JSON.

gcloud beta iam access-policies create my-access-policy \
    --project=my-project-id \
    --location=global \
    --details-rules=description="Allow publishing to bus",effect=ALLOW,principals=[principal://goog/subject/user@example.com],operation={permissions=[eventarc.googleapis.com/messageBuses.publish]} \
    --details-rules=description="Deny publishing to bus if media type is JSON",effect=DENY,principals=[principal://goog/subject/user@example.com],operation={permissions=[eventarc.googleapis.com/messageBuses.publish]},conditions={eventarc.googleapis.com={expression="message.datacontenttype=='application/json'"}}

API REST

É possível criar uma política de acesso usando o projects.locations.accessPolicies.create method.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • POLICY_DISPLAY_NAME: opcional. Um nome legível para a política de acesso, por exemplo, "Política de exemplo". O nome de exibição pode ter no máximo 63 caracteres.
  • POLICY_DESCRIPTION: opcional. Uma descrição legível da política de acesso, por exemplo, "Descrição de exemplo". A descrição pode ter no máximo 256 caracteres.
  • EFFECT: o efeito da regra, que pode ser ALLOW ou DENY.
  • PRINCIPALS: as identidades a que esta regra se aplica. O formato do identificador depende do tipo de principal que você quer consultar. Para mais informações, consulte Tipos de principais para políticas de acesso.
  • EXCLUDED_PRINCIPALS: as identidades excluídas da aplicação da regra, mesmo que estejam listadas em principals. Por exemplo, você pode adicionar um grupo do Google a principals e excluir usuários específicos que pertencem a ele.
  • CEL_EXPRESSION: a expressão CEL que será avaliada para determinar a aplicabilidade da regra. Para mais informações, consulte Usar a Common Expression Language.
  • POLICY_PROJECT_ID: o Google Cloud ID do projeto em que a política será criada.
  • POLICY_ID: um nome exclusivo para a política de acesso, por exemplo, my-access-policy.

Várias regras podem ser listadas. Cada regra é avaliada de forma independente. Se uma regra não se aplicar, outras poderão ser válidas.

Corpo JSON da solicitação:

{
  "displayName": "POLICY_DISPLAY_NAME",
  "details": {
    "rules": [
      {
        "description": "POLICY_DESCRIPTION",
        "effect": "EFFECT",
        "principals": [
          "PRINCIPALS"
        ],
        "excludedPrincipals": [
        "EXCLUDED_PRINCIPALS"
        ],
        "operation": {
          "permissions": [
            "eventarc.googleapis.com/messageBuses.publish"
          ]
        },
        "conditions": {
          "eventarc.googleapis.com": {
            "expression": "CEL_EXPRESSION"
          }
        }
      }
    ]
  }
}

Para enviar a solicitação, expanda uma destas opções:

A resposta contém uma operação de longa duração que representa a solicitação. Para saber como conferir o status de uma operação de longa duração, consulte Verificar o status de uma operação de longa duração nesta página. 

{
  "name": "projects/POLICY_PROJECT_ID/locations/global/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.iam.v3.OperationMetadata",
    "createTime": "2025-01-25T17:17:45.782370139Z",
    "target": "projects/POLICY_PROJECT_ID/locations/global/accessPolicies/POLICY_ID",
    "verb": "create",
    "requestedCancellation": false,
    "apiVersion": "v3"
  },
  "done": false
}

Exemplo

A política de acesso a seguir permite que o principal especificado publique mensagens de evento em um barramento, mas nega a publicação quando a prioridade da mensagem é HIGH.

cat > request.json << 'EOF'
{
"displayName": "Eventarc Advanced access policy",
"details": {
  "rules": [
  {
    "description": "Allow publishing to bus",
    "effect": "ALLOW",
    "principals": [
      "principal://goog/subject/user@example.com"
    ],
    "operation": {
      "permissions": [
        "eventarc.googleapis.com/messageBuses.publish"
      ]
    }
  },
    {
      "description": "Deny publishing to bus if message priority is HIGH",
      "effect": "DENY",
      "principals": [
        "principal://goog/subject/user@example.com"
      ],
      "operation": {
        "permissions": [
          "eventarc.googleapis.com/messageBuses.publish"
        ]
      },
      "conditions": {
        "eventarc.googleapis.com": {
          "expression": "message.priority == \"HIGH\""
        }
      }
    }
  ]
}
}
EOF

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://iam.googleapis.com/v3/projects/POLICY_PROJECT_ID/locations/global/accessPolicies?access_policy_id=POLICY_ID"

Aplicar uma política de acesso

Crie uma vinculação de política para aplicar sua política de acesso a um projeto Google Cloud . Cada vinculação de política associa uma política de acesso a um recurso.

É possível aplicar uma política de acesso usando a Google Cloud CLI ou fazendo uma solicitação direta à API IAM v3.

gcloud

Para criar uma vinculação de política e aplicar sua política de acesso, execute o comando gcloud beta iam policy-bindings create.

gcloud beta iam policy-bindings create BINDING_ID \
    --project=BINDING_PROJECT_ID \
    --location=global \
    --policy=projects/POLICY_PROJECT_ID/locations/global/accessPolicies/POLICY_ID \
    --target-resource=//cloudresourcemanager.googleapis.com/projects/BINDING_PROJECT_ID

Substitua:

  • BINDING_ID: um nome exclusivo para a vinculação de política. Por exemplo, my-access-policy-binding.
  • BINDING_PROJECT_ID: o ID do projeto Google Cloud em que a vinculação será criada. Precisa ser o mesmo ID do projeto em que o barramento do Eventarc Advanced foi criado e indica o destino da vinculação.

A flag --location especifica o local da vinculação de política e precisa ser global.

A resposta contém uma operação de longa duração que representa a solicitação. Para saber como conferir o status de uma operação de longa duração, consulte Verificar o status de uma operação de longa duração neste documento.

Exemplo

O comando a seguir cria uma vinculação de política que aplica a política de acesso especificada a um projeto Google Cloud :

gcloud beta iam policy-bindings create my-access-policy-binding \
    --project=my-project-id \
    --location=global \
    --policy=projects/my-project-id/locations/global/accessPolicies/my-access-policy \
    --target-resource=//cloudresourcemanager.googleapis.com/projects/my-project-id

API REST

É possível criar uma vinculação de política e aplicar sua política de acesso usando o projects.locations.policyBindings.create method.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • BINDING_DISPLAY_NAME: opcional. Um nome legível para a vinculação de política, por exemplo, "Exemplo de vinculação". O nome de exibição pode ter no máximo 63 caracteres.
  • BINDING_PROJECT_ID: o ID do projeto Google Cloud em que a vinculação será criada. Precisa ser o mesmo ID do projeto em que o barramento do Eventarc Advanced foi criado e indica o destino da vinculação.
  • POLICY_PROJECT_ID: o Google Cloud ID do projeto em que a política é criada.
  • POLICY_ID: o nome da política de acesso a ser vinculada, por exemplo, my-access-policy.

Corpo JSON da solicitação:

{
  "display_name": "BINDING_DISPLAY_NAME",
  "target": {"resource": "//cloudresourcemanager.googleapis.com/projects/BINDING_PROJECT_ID"},
  "policy_kind": "ACCESS",
  "policy": "projects/POLICY_PROJECT_ID/locations/global/accessPolicies/POLICY_ID"
}

Para enviar a solicitação, expanda uma destas opções:

A resposta contém uma operação de longa duração que representa a solicitação. Para saber como conferir o status de uma operação de longa duração, consulte Verificar o status de uma operação de longa duração nesta página. 

{
  "name": "projects/BINDING_PROJECT_ID/locations/global/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.iam.v3.OperationMetadata",
    "createTime": "2025-01-25T17:17:45.782370139Z",
    "target": "projects/BINDING_PROJECT_ID/locations/global/policyBindings/POLICY_ID-binding",
    "verb": "create",
    "requestedCancellation": false,
    "apiVersion": "v3"
  },
  "done": false
}

Verificar o status de uma operação de longa duração

Quando você usa a API REST do IAM, qualquer método que mude uma política ou vinculação de acesso retorna uma operação de longa duração (LRO). A operação de longa duração rastreia o status da solicitação e indica se a mudança na política ou vinculação foi concluída.

O método operations.get retorna o status de uma operação de longa duração.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • OPERATION_NAME: o nome completo da operação. Você recebe esse nome na resposta à sua solicitação original.

    O nome da operação tem o seguinte formato: 

    projects/PROJECT_ID/locations/global/operations/OPERATION_ID
  • PROJECT_ID: o ID do projeto Google Cloud em que a operação é retornada.

Para enviar a solicitação, expanda uma destas opções:

Você receberá uma resposta JSON semelhante a esta:

{
  "name": "projects/PROJECT_ID/locations/global/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.iam.v3.OperationMetadata",
    "createTime": "2025-01-28T00:05:12.006289686Z",
    "endTime": "2025-01-28T00:05:12.192141801Z",
    "target": "projects/PROJECT_ID/locations/global/accessPolicies/POLICY_ID",
    "verb": "create",
    "requestedCancellation": false,
    "apiVersion": "v3"
  },
  "done": true,
  "response": {
    ACCESS_POLICY
  }
}

Se o campo done da operação não estiver presente, continue a monitorar o status recebendo a operação repetidamente. Use a espera exponencial truncada para introduzir um atraso entre cada solicitação. Quando o campo done estiver definido como true, a operação será concluída e você poderá interromper a operação.

A seguir