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 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 de política 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. 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 por região compatível.Google Cloud Uma política de acesso anexada a um projeto controla o acesso de publicação a qualquer barramento Eventarc Advanced nesse projeto.

    • É possível usar políticas de acesso para controlar o acesso de publicação a um barramento do 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 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

  2. 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

  3. Configure a autenticação:

    gcloud

    No console do Google Cloud , ative o Cloud Shell.

    Ativar o Cloud Shell

    Na parte de baixo do console Google Cloud , uma sessão do Cloud Shell é iniciada e exibe um prompt de linha de comando. O Cloud Shell é um ambiente shell com a CLI do Google Cloud já instalada e com valores já definidos para o projeto atual. A inicialização da sessão pode levar alguns segundos.

    API REST

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

      Instale a CLI do Google Cloud.

      Ao usar um provedor de identidade (IdP) externo, primeiro faça login na gcloud CLI 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 de 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 à 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], \
    permissions=[eventarc.googleapis.com/messageBuses.publish], \
    activationConditions={eventarc.googleapis.com={celCondition={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"
        ],
        "permissions": [
          "eventarc.googleapis.com/messageBuses.publish"
        ],
        "activationConditions": {
          "eventarc.googleapis.com": {
            "celCondition": {
              "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],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],permissions=[eventarc.googleapis.com/messageBuses.publish],activationConditions={eventarc.googleapis.com={celCondition={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"
        ],
        "permissions": [
          "eventarc.googleapis.com/messageBuses.publish"
        ],
        "activationConditions": {
          "eventarc.googleapis.com": {
            "celCondition": {
              "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"
    ],
    "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"
      ],
      "permissions": [
        "eventarc.googleapis.com/messageBuses.publish"
      ],
      "activationConditions": {
        "eventarc.googleapis.com": {
          "celCondition": {
            "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 na 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 monitorando 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