Como pesquisar políticas do IAM

A API Cloud Asset permite usar uma linguagem de consulta personalizada para pesquisar políticas de gerenciamento de identidade e acesso (IAM, na sigla em inglês) em um projeto, pasta ou organização.

Antes de começar

Chamando SearchAllIamPolicies

gcloud

É possível chamar SearchAllIamPolicies usando o comando gcloud asset search-all-iam-policies. É preciso usar o SDK do Cloud versão 302.0.0 ou mais recente. É possível verificar sua versão com o comando gcloud version:

gcloud asset search-all-iam-policies \
  --scope=SCOPE \
  --query=QUERY \
  --page-size=PAGE_SIZE

Em que:

  • (Opcional) SCOPE: um escopo pode ser um projeto, uma pasta ou uma organização. A pesquisa é limitada às políticas do IAM dentro desse escopo. O autor da chamada precisa receber um papel que contenha a permissão cloudasset.assets.searchAllIamPolicies no escopo desejado. Se não for especificado, a propriedade do projeto configurada será usada. Para encontrar o projeto configurado, execute: gcloud config get-value project. Para alterar a configuração, execute: gcloud config set project PROJECT_ID.

    Os valores permitidos são:

    • projects/PROJECT_ID (ex., "projects/foo-bar")
    • projects/PROJECT_NUMBER (ex., "projects/12345678")
    • folders/FOLDER_NUMBER (ex., "folders/1234567")
    • organizations/ORGANIZATION_NUMBER (ex., "organizations/123456")
  • (Opcional) QUERY: a instrução de consulta. Consulte Como criar uma consulta para mais informações. Se não for especificado ou estiver vazio, ele pesquisará todas as políticas de IAM no scope especificado. A string de consulta é comparada a cada vinculação de política do Cloud IAM, incluindo os membros, os papéis e as condições do Cloud IAM. As políticas de IAM retornadas terão apenas as vinculações que corresponderem à sua consulta. Para saber mais sobre a estrutura da política do IAM, consulte Noções básicas sobre políticas.

    Exemplos:

    • policy:amy@gmail.com para encontrar vinculações de políticas do IAM que especifiquem o usuário "amy@gmail.com".
    • policy:roles/compute.admin para encontrar vinculações de políticas do IAM que especifiquem o papel de Administrador do Compute.
    • policy:comp* para encontrar vinculações de política de IAM que contenham "comp" como prefixo de qualquer palavra na vinculação.
    • policy.role.permissions:storage.buckets.update para encontrar vinculações de políticas do Cloud IAM que especifiquem um papel que contenha a permissão "storage.buckets.update". Se o autor da chamada não tiver recebido um papel que contenha a permissão iam.roles.get no papel desejado, as vinculações de políticas que especificam esse papel serão descartadas dos resultados da pesquisa.
    • policy.role.permissions:upd* para encontrar vinculações de política de IAM que especificam um papel contendo "upd" como prefixo de qualquer palavra na vinculação. Se o autor da chamada não tiver recebido um papel que contenha a permissão iam.roles.get no papel desejado, as vinculações de políticas que especificam esse papel serão descartadas dos resultados da pesquisa.
    • resource:organizations/123456 para encontrar vinculações de políticas do IAM definidas em "organizations/123456".
    • resource=//cloudresourcemanager.googleapis.com/projects/myproject para encontrar vinculações de políticas do IAM definidas no projeto denominado "myproject".
    • Important para encontrar vinculações de política do IAM que contenham "Importante" como uma palavra em qualquer um dos campos pesquisáveis (exceto para as permissões incluídas).
    • resource:(instance1 OR instance2) policy:amy para encontrar vinculações de política de IAM definidas em recursos "instance1" ou "instance2" e também especificar o usuário "amy".
  • (Opcional) PAGE_SIZE: o tamanho da página para a paginação de resultados da pesquisa. O valor máximo é 500. Se o valor for 0, um padrão apropriado será escolhido;

  • Encontre todas as vinculações de política de IAM no organizations/123456 que contenham o domínio mycompany.com:

    gcloud asset search-all-iam-policies \
      --scope='organizations/123456' \
      --query='policy:"domain:mycompany.com"'
    
  • Encontre todas as vinculações de política de IAM no organizations/123456 em que myuser@mycompany.com recebeu o papel básico de Proprietário (roles/owner):

    gcloud asset search-all-iam-policies \
      --scope='organizations/123456' \
      --query='policy:(roles/owner myuser@mycompany.com)'
    
  • Encontre todas as vinculações de política de IAM no organizations/123456 que estão definidas em projects/12345678:

    gcloud asset search-all-iam-policies \
      --scope='organizations/123456' \
      --query='resource:projects/12345678'
    

api

É possível chamar SearchAllIamPolicies usando um token OAuth válido para um projeto. Para chamar o método SearchAllIamPolicies do Cloud Shell ou de qualquer console em que o comando gcloud esteja disponível:

  1. Se você ainda não configurou a tela de consentimento do OAuth do seu projeto, precisará fazê-lo. É necessário informar um endereço de e-mail e o nome do produto para a tela de consentimento do OAuth.

    1. Acesse a tela de consentimento OAuth do seu projeto.
      Configurar tela de consentimento
    2. Digite o Nome do aplicativo que você quer exibir.
    3. Em E-mail de suporte, selecione o endereço de e-mail que você quer exibir como um contato público. Precisa ser o seu endereço de e-mail ou um grupo do Google que pertença a você.
    4. Adicione os detalhes opcionais que você quiser.
    5. Clique em Salvar.
  2. Crie um token OAuth para seu projeto. Para ver mais informações, consulte Como configurar o OAuth 2.0.

    1. Acesse a página Criar ID do cliente OAuth.
      Criar cliente OAuth
    2. Selecione App para computador como o Tipo de aplicativo.
    3. Clique em Criar.
  3. Faça o download do arquivo client_secret.json.

    1. Acesse a página Credenciais.
    2. À direita de seu novo ID do cliente, clique em Fazer o download do JSON.
    3. Armazene com segurança o arquivo em um local que somente o app possa acessar.
  4. Faça login usando o arquivo JSON com o seguinte comando:

    gcloud auth application-default login --client-id-file=YOUR_JSON_FILE
    

    Esse comando solicitará que você abra um link. Verifique se o Nome do aplicativo definido na tela de consentimento do OAuth é exibido.

  5. Gere um token de autenticação para sua conta com o seguinte comando:

    TOKEN=$(gcloud auth application-default print-access-token)
    
  6. Agora, é possível consultar as políticas do IAM usando comandos curl.

    PAGE_SIZE=PAGE_SIZE
    PAGE_TOKEN="PAGE_TOKEN"
    SCOPE="SCOPE"
    QUERY="QUERY"
    curl -s -G \
        -H "Authorization: Bearer $TOKEN" \
        -d "page_size=$PAGE_SIZE" \
        -d "page_token=$PAGE_TOKEN" \
        --data-urlencode "query=$QUERY" \
        "https://cloudasset.googleapis.com/v1/$SCOPE:searchAllIamPolicies"
    
  • (Opcional) SCOPE: um escopo pode ser um projeto, uma pasta ou uma organização. A pesquisa é limitada às políticas do IAM dentro desse escopo. O autor da chamada precisa receber um papel que contenha a permissão cloudasset.assets.searchAllIamPolicies no escopo desejado.

    Os valores permitidos são:

    • projects/PROJECT_ID (ex., "projects/foo-bar")
    • projects/PROJECT_NUMBER (ex., "projects/12345678")
    • folders/FOLDER_NUMBER (ex., "folders/1234567")
    • organizations/ORGANIZATION_NUMBER (ex., "organizations/123456")
  • (Opcional) QUERY: a instrução de consulta. Veja como criar uma consulta para mais informações. Se não for especificado ou estiver vazio, ele pesquisará todas as políticas de IAM no scope especificado. A string de consulta é comparada a cada vinculação de política do Cloud IAM, incluindo os membros, os papéis e as condições do Cloud IAM. As políticas de IAM retornadas terão apenas as vinculações que corresponderem à sua consulta. Para saber mais sobre a estrutura da política do IAM, consulte Noções básicas sobre políticas.

    Exemplos:

    • policy:amy@gmail.com para encontrar vinculações de políticas do IAM que especifiquem o usuário "amy@gmail.com".
    • policy:roles/compute.admin para encontrar vinculações de políticas do IAM que especifiquem o papel de Administrador do Compute.
    • policy:comp* para encontrar vinculações de política de IAM que contenham "comp" como prefixo de qualquer palavra na vinculação.
    • policy.role.permissions:storage.buckets.update para encontrar vinculações de políticas do Cloud IAM que especifiquem um papel que contenha a permissão "storage.buckets.update". Se o autor da chamada não tiver recebido um papel que contenha a permissão iam.roles.get no papel desejado, as vinculações de políticas que especificam esse papel serão descartadas dos resultados da pesquisa.
    • policy.role.permissions:upd* para encontrar vinculações de política de IAM que especificam um papel contendo "upd" como prefixo de qualquer palavra na permissão de papel. Se o autor da chamada não tiver recebido um papel que contenha a permissão iam.roles.get no papel desejado, as vinculações de políticas que especificam esse papel serão descartadas dos resultados da pesquisa.
    • resource:organizations/123456 para encontrar vinculações de políticas do IAM definidas em "organizations/123456".
    • resource=//cloudresourcemanager.googleapis.com/projects/myproject para encontrar vinculações de políticas do IAM definidas no projeto denominado "myproject".
    • Important para encontrar vinculações de políticas do IAM que contenham "Important" como uma palavra em qualquer um dos campos pesquisáveis (exceto as permissões incluídas).
    • resource:(instance1 OR instance2) policy:amy para encontrar vinculações de políticas do IAM configuradas em recursos "instance1" ou "instance2" e também especificar o usuário "amy".
  • (Opcional) PAGE_SIZE: o tamanho da página para a paginação de resultados da pesquisa. O valor máximo é 2000. Se o valor for 0, um padrão apropriado será escolhido.

  • (Opcional) PAGE_TOKEN: o token que representa o próximo lote de resultados da chamada anterior para esse método. O page_token precisa ser igual ao valor de next_page_token da resposta da chamada anterior.

Biblioteca de cliente e referência de API

Como criar uma consulta

Veja a sintaxe de consulta para saber mais sobre a linguagem de consulta.

Consulte como pesquisar amostras de políticas de iam para saber mais sobre as consultas de amostra para vários casos de uso reais.

Consultar políticas do IAM por informações de vinculação

Para pesquisar as políticas do IAM, uma expressão de consulta terá o seguinte formato:

policy:QUERY

Participante

As vinculações de políticas de IAM são compatíveis com cinco tipos de membros:

  1. Contas do Google, como user:user@gmail.com
  2. Grupos do Google, como group:devs@googlegroups.com
  3. Domínios do Cloud Identity e do G Suite, como domain:google.com
  4. Contas de serviço, como serviceAccount:my-other-app@appspot.gserviceaccount.com
  5. Identificadores especiais, como allUsers e allAuthenticatedUsers

Você pode limitar sua consulta a políticas relacionadas a um usuário específico usando a seguinte sintaxe:

policy:"user:amy@mycompany.com"

É necessário colocar user:amy@mycompany.com entre aspas duplas, já que ele contém o caractere especial :. É possível omitir o prefixo user: ou group: em uma string de consulta, se o valor da consulta for único o suficiente ou se você quiser pesquisar o endereço de e-mail independentemente do tipo de membro. Por exemplo, a consulta a seguir provavelmente corresponderá apenas a um usuário:

policy:amy@mycompany.com
Exemplos: consulta por membro
  • Encontre todas as vinculações de política do IAM que especificam o usuário Amy:

    policy:amy
    
  • Encontre todas as vinculações de política de IAM que especifiquem o domínio mydomain.com:

    policy:mydomain.com
    
  • Encontre todas as vinculações de política de IAM que especifiquem o usuário Amy e John:

    policy:(amy john)
    
  • Encontre todas as vinculações de política de IAM que especifiquem o usuário Amy ou John:

    policy:(amy OR john)
    
  • Encontre todas as vinculações de política de IAM na sua organização que contenham amy@mycompany.com:

    policy:amy@mycompany.com
    
  • Encontre todas as vinculações de políticas de IAM na organização que contenham o domínio mycompany.com:

    policy:"domain:mycompany.com"
    
  • Encontre todas as vinculações de política do IAM que atribuem papéis à conta de serviço mycompany.gserviceaccount.com:

    policy:"serviceAccount:mycompany.gserviceaccount.com"
    
  • Encontre todas as vinculações de políticas do IAM que atribuam papéis ao grupo admins:

    policy:"group:admins"
    
  • Encontre todas as vinculações de políticas de IAM que atribuam papéis a todos os usuários:

    policy:allUsers
    
  • Encontre todas as vinculações de políticas de IAM que atribuam papéis a todos os usuários autenticados:

    policy:allAuthenticatedUsers
    
  • Encontre todas as vinculações de política do IAM que atribuem papéis ao amy@mycompany.com ou ao domínio mycompany.com:

    policy:(amy@mycompany.com OR "domain:mycompany.com")
    

Role

As vinculações de política de IAM são compatíveis com diferentes tipos de papéis. Todos os nomes de papéis do IAM começam com o prefixo roles/.

  1. Papéis básicos: há três papéis que já existiam antes da introdução do IAM: Proprietário (roles/owner ), Editor (roles/editor ) e Visualizador (roles/viewer).
  2. Papéis predefinidos: o IAM oferece papéis predefinidos adicionais que dão acesso granular a recursos diferentes. Veja todos os papéis predefinidos.
  3. Papéis personalizados: papéis do IAM definidos pelo usuário que contêm uma lista selecionada de permissões.

Para limitar a consulta às políticas relacionadas a um papel específico, use a seguinte sintaxe:

policy:roles/role-name

Você poderá omitir o prefixo roles/ em uma string de consulta se o valor da consulta for exclusivo o suficiente. Por exemplo, a consulta a seguir provavelmente corresponderá apenas ao papel roles/cloudasset.owner:

policy:cloudasset.owner
Exemplos: consultar por papel
  • Encontre todas as vinculações de política do IAM que especificam o papel owner.

    policy:roles/owner
    
  • Encontre todas as vinculações de política de IAM que atribuam amy@mycompany.com o papel de proprietário:

    policy:(roles/owner amy@mycompany.com)
    
  • Encontre todas as vinculações de políticas do IAM que atribuam o papel compute.admin aos membros com um endereço de e-mail que contenha a palavra john:

    policy:(roles/compute.admin john)
    
  • Encontre todas as vinculações de política de IAM que concedem o papel viewer aos usuários que tenham "swe" ou "sde" como prefixo.

    policy:(roles/viewer (swe* OR sde*))
    

Condições do IAM

As vinculações de políticas do IAM podem conter um objeto condition que permite definir e aplicar o controle de acesso condicional baseado em atributos para recursos do Google Cloud. Consulte Visão geral das Condições do IAM para mais informações.

Para limitar a consulta a políticas relacionadas a uma condição específica, use a seguinte sintaxe:

policy:condition_information
Exemplos: consulta por condição
  • Encontre todas as vinculações de política de IAM que especifiquem uma condição, cujo título/descrição contém a palavra "myCondition":

    policy:myCondition
    
  • Encontre todas as vinculações de política de IAM que especifiquem uma condição, cuja expressão contenha o atributo "request.time":

    policy:"request.time"
    

Consultar políticas do IAM por permissões incluídas

Os papéis em uma política podem incluir uma lista de permissões. Consulte a referência de permissões do IAM para mais detalhes. É possível limitar sua consulta a políticas que tenham uma permissão específica. Uma expressão de consulta tem estes formatos:

  • Correspondência exata: policy.role.permissions=QUERY
  • Correspondência parcial: policy.role.permissions:QUERY
Exemplos: consulta por permissões
  • Encontre todas as vinculações de política de IAM que contenham a permissão compute.instances.create:

    policy.role.permissions:compute.instances.create
    policy.role.permissions=compute.instances.create
    
  • Encontre todas as vinculações de política de IAM que contenham as permissões relacionadas compute.instances:

    policy.role.permissions:compute.instances
    
  • Encontre todas as vinculações de política do IAM que contêm as permissões cloudasset.assets.export... (por exemplo, cloudasset.assets.exportAssets e cloudasset.assets.exportIamPolicyAnalysis):

    policy.role.permissions:cloudasset.assets.export*
    
  • Encontre todas as vinculações de política de IAM que concedam permissões para alterar as políticas do IAM:

    policy.role.permissions:setIamPolicy
    
  • Encontre todas as vinculações de políticas de IAM com um papel que contenha as permissões compute.instances.create e compute.disks.create:

    policy.role.permissions:(compute.instances.create compute.disks.create)
    
  • Encontre todas as vinculações de política de IAM que contenham a permissão compute.instances.create e especifique o usuário amy:

    policy.role.permissions:compute.instances.create policy:amy
    policy.role.permissions=compute.instances.create policy:amy
    

Consultar políticas do IAM por nome de recurso

Ao fazer uma pesquisa, é possível especificar um nome de recurso completo para pesquisar somente as políticas diretamente definidas no recurso. Uma expressão de consulta tem estes formatos:

  • Correspondência exata: resource=QUERY
  • Correspondência parcial: resource:QUERY

Exemplos: consulta por nome de recurso

  • Encontre todas as vinculações de políticas de IAM que são definidas diretamente em um recurso que tenha nome completo do recurso exatamente igual a //cloudresourcemanager.googleapis.com/projects/myproject:

    resource=//cloudresourcemanager.googleapis.com/projects/myproject
    
  • Encontre todas as vinculações de política de IAM que são definidas diretamente em recursos com o nome completo do recurso que contém a palavra myproject:

    resource:myproject
    
  • Encontre todas as vinculações de política de IAM que são definidas diretamente em recursos com nome completo do recurso que contém uma palavra com prefixo myproj especificado:

    resource:myproj*
    
  • Encontre todas as vinculações de políticas de IAM que são definidas diretamente nos recursos de um determinado tipo de serviço:

    resource:cloudresourcemanager
    
  • Encontre todas as vinculações de política de IAM definidas em myproject ou myfolder:

    resource:(myproject OR myfolder)
    
  • Encontre todas as vinculações de política de IAM definidas em recursos cloudresourcemanager e atribua o papel de proprietário a usuários gmail.com:

    resource:cloudresourcemanager policy:(roles/owner gmail.com)
    

Consultar políticas do IAM por texto livre

Você também pode simplesmente usar uma consulta de texto livre sem especificar um campo. A resposta retornará políticas enquanto houver um campo pesquisável (por exemplo, campos de vinculação de políticas ou nome de recurso) que corresponda à consulta.

Exemplos: consultar por texto livre

  • Encontre todas as vinculações de política de IAM em scope com campos de metadados (como vinculações de política ou nome de recursos) contendo Important como palavra:

    Important
    
  • Encontre todas as vinculações de política de IAM em scope com campos de metadados (como vinculações de política ou nome de recursos) contendo import como prefixo de qualquer palavra:

    import*