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 avançado do Eventarc.

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 ativar 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 avançado do Eventarc.

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 avançado do Eventarc 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 do 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 do payload 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

    In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

    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.

      Install the Google Cloud CLI. After installation, initialize the Google Cloud CLI by running the following command: 

      gcloud init

      If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

    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 à 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 avançado do Eventarc 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 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