Controle o acesso de publicação

A gestão de identidade e de acesso (IAM) oferece vários tipos de políticas para ajudar a controlar a que recursos os principais podem aceder. Este guia descreve como usar políticas de acesso para controlar o acesso ao publicar mensagens de eventos num barramento 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 de contexto de eventos específicos, como a prioridade da mensagem de evento.

Cada política de acesso é um conjunto de regras que lhe permite identificar os principais e definir condições que determinam a aplicabilidade de uma regra, e que lhe permite ativar o controlo de acesso detalhado. Por exemplo, consoante a avaliação de uma expressão do idioma de expressão comum (IEC) aplicada a um atributo de contexto de evento, pode permitir ou negar a autorização para publicar um subconjunto de mensagens de eventos num barramento avançado do Eventarc.

Este guia explica como criar e aplicar uma política de acesso. Primeiro, crie uma política de acesso e, de seguida, crie uma associação de políticas para associar essa política a um Google Cloud projeto.

Antes de começar

Antes de criar e aplicar uma política de acesso, já deve ter criado um bus avançado do Eventarc para o qual as mensagens de eventos podem ser publicadas.

  1. Certifique-se de que tem em consideração o seguinte:

    • As políticas de acesso têm de ser aplicadas ou associadas a um Google Cloud projeto. Cada política de acesso pode ser anexada a um máximo de 5 projetos. Cada projeto pode ter um máximo de 5 políticas de acesso anexadas. Pode criar um autocarro por Google Cloud projeto por região suportada. Uma política de acesso associada a um projeto controla o acesso de publicação a qualquer barramento avançado do Eventarc nesse projeto.

    • Pode usar políticas de acesso para controlar o acesso de publicação a um barramento avançado do Eventarc, mas não para controlar o acesso à subscrição de mensagens de um barramento específico. A autorização suportada é eventarc.messageBuses.publish.

    • O controlo de acesso só pode basear-se em atributos do contexto do evento e não no conteúdo do payload do evento.

    • As mensagens de eventos que são publicadas a partir de origens Google e que são recusadas são ignoradas. Se o principal publicar diretamente uma mensagem de evento, uma mensagem de registo Event published successfully indica-o. No entanto, se a mensagem do evento for recusada pela condição na política de acesso, ocorre um erro semelhante ao seguinte:

      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 o fez, ative as APIs Eventarc e IAM:

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

  3. Configurar 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 os exemplos da API REST nesta página num ambiente de desenvolvimento local, usa as credenciais que fornece à CLI gcloud.

      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.

    Para mais informações, consulte o artigo Autenticar para usar REST na Google Cloud documentação de autenticação.

    Funções necessárias

    Uma função de IAM contém um conjunto de autorizações que lhe permite realizar ações específicas em recursos. Google Cloud

    Para receber as autorizações de que precisa para controlar o acesso à publicação, peça ao seu administrador que lhe conceda as seguintes funções de IAM no seu projeto:

    Para mais informações sobre a atribuição de funções, consulte o artigo Faça a gestão do acesso a projetos, pastas e organizações.

    Estas funções predefinidas contêm as autorizações necessárias para controlar o acesso à publicação. Para ver as autorizações exatas que são necessárias, expanda a secção Autorizações necessárias:

    Autorizações necessárias

    São necessárias as seguintes autorizações 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

    Também pode conseguir estas autorizações com funções personalizadas ou outras funções predefinidas.

    Crie uma política de acesso

    Crie uma política de acesso para controlar o acesso quando publicar num barramento avançado do Eventarc no seu projeto.

    Pode criar uma política de acesso através da CLI do Google Cloud ou fazendo um pedido direto à API IAM v3.

    gcloud

    Pode criar uma política de acesso executando 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 o seguinte:

    • POLICY_ID: um nome exclusivo para a política de acesso, por exemplo, my-access-policy.
    • POLICY_PROJECT_ID: o Google Cloud ID do projeto do projeto onde a política vai ser criada.
    • POLICY_DESCRIPTION: uma descrição opcional da política (máximo de 256 carateres).
    • EFFECT: o efeito da regra (ALLOW ou DENY).
    • PRINCIPALS: as identidades às quais esta regra se aplica. O formato do identificador depende do tipo de principal ao qual quer fazer referência. Para mais informações, consulte o artigo 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, pode adicionar um grupo Google a principals e, em seguida, excluir utilizadores específicos que pertencem a esse grupo.
    • CEL_EXPRESSION: a expressão de IEC que vai ser avaliada para determinar a aplicabilidade da regra, por exemplo, message.version != \"v1\". Para mais informações, consulte o artigo Use o idioma de expressão comum.

    Tenha em conta o seguinte:

    • A flag --location especifica a localização da política de acesso e tem de ser global.

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

      A flag também pode ser repetida quando configura 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 o seu pedido. Para saber como obter o estado de uma operação de longa duração, consulte a secção Verifique o estado de uma operação de longa duração neste documento.

    Exemplo

    O comando seguinte cria uma política de acesso que permite que o principal especificado publique mensagens de eventos num barramento, mas nega a publicação quando o tipo de suporte 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

    Pode criar uma política de acesso através do comando projects.locations.accessPolicies.create method.

    Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

    • POLICY_DISPLAY_NAME: opcional. Um nome legível para a política de acesso, por exemplo, "Política de exemplo". O nome a apresentar pode ter um máximo de 63 carateres.
    • POLICY_DESCRIPTION: opcional. Uma descrição legível da política de acesso, por exemplo, "Descrição de exemplo". A descrição pode ter um máximo de 256 carateres.
    • EFFECT: o efeito da regra, ALLOW ou DENY.
    • PRINCIPALS: as identidades às quais esta regra se aplica. O formato do identificador depende do tipo de principal ao qual quer fazer referência. Para mais informações, consulte o artigo Tipos 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, pode adicionar um grupo Google a principals e, em seguida, excluir utilizadores específicos pertencentes a esse grupo.
    • CEL_EXPRESSION: a expressão de IEC que vai ser avaliada para determinar a aplicabilidade da regra. Para mais informações, consulte o artigo Use o idioma de expressão comum.
    • POLICY_PROJECT_ID: o Google Cloud ID do projeto onde a política vai ser criada.
    • POLICY_ID: um nome exclusivo para a política de acesso, por exemplo, my-access-policy.

    Podem ser apresentadas várias regras. Cada regra é avaliada de forma independente. Se uma regra não se aplicar, podem aplicar-se outras regras.

    Corpo JSON do pedido: 

    {
  "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 o seu pedido, expanda uma destas opções:

    A resposta contém uma operação de longa duração que representa o seu pedido. Para saber como obter o estado de uma operação de longa duração, consulte a secção Verifique o estado de uma operação de longa duração nesta página deste documento. 

    {
  "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 seguinte política de acesso permite que o principal especificado publique mensagens de eventos num 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"

    Aplique uma política de acesso

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

    Pode aplicar uma política de acesso através da CLI do Google Cloud ou fazendo um pedido direto à API IAM v3.

    gcloud

    Pode criar uma associação de políticas e aplicar a sua política de acesso executando 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 o seguinte:

    • BINDING_ID: um nome exclusivo para a associação de políticas, por exemplo, my-access-policy-binding.
    • BINDING_PROJECT_ID: o Google Cloud ID do projeto do projeto onde a associação vai ser criada. Este deve ser o mesmo que o ID do projeto onde o Eventarc Advanced bus é criado e indica o destino da associação.

    A flag --location especifica a localização da associação de políticas e tem de ser global.

    A resposta contém uma operação de longa duração que representa o seu pedido. Para saber como obter o estado de uma operação de longa duração, consulte a secção Verifique o estado de uma operação de longa duração neste documento.

    Exemplo

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

    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

    Pode criar uma associação de políticas e aplicar a sua política de acesso através do comando projects.locations.policyBindings.create method.

    Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

    • BINDING_DISPLAY_NAME: opcional. Um nome legível para a associação de políticas, por exemplo, "Associação de exemplo". O nome a apresentar pode ter um máximo de 63 carateres.
    • BINDING_PROJECT_ID: o Google Cloud ID do projeto onde a associação vai ser criada. Este deve ser o mesmo que o ID do projeto onde o bus avançado do Eventarc é criado e indica o destino da associação.
    • POLICY_PROJECT_ID: o Google Cloud ID do projeto onde a política é criada.
    • POLICY_ID: o nome da política de acesso a associar, por exemplo, my-access-policy.

    Corpo JSON do pedido: 

    {
  "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 o seu pedido, expanda uma destas opções:

    A resposta contém uma operação de longa duração que representa o seu pedido. Para saber como obter o estado de uma operação de longa duração, consulte a secção Verifique o estado de uma operação de longa duração nesta página deste documento. 

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

    Verifique o estado de uma operação de longa duração

    Quando usa a API REST do IAM, qualquer método que altere uma política de acesso ou uma vinculação devolve uma operação de longa duração (LRO). A operação de longa duração acompanha o estado do pedido e indica se a alteração à política ou à associação está concluída.

    O método operations.get devolve o estado de uma operação de longa duração.

    Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

    • OPERATION_NAME: o nome completo da operação. Recebe este 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 Google Cloud ID do projeto do projeto onde a operação é devolvida.

    Para enviar o seu pedido, expanda uma destas opções:

    Deve receber uma resposta JSON semelhante à seguinte:

    {
  "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 monitorizar o respetivo estado através da obtenção repetida da operação. Use a retirada exponencial truncada para introduzir um atraso entre cada pedido. Quando o campo done está definido como true, a operação está concluída e pode parar de receber a operação.

    O que se segue?