Resolver problemas com permissões do IAM

O solucionador de problemas de políticas facilita o entendimento do motivo pelo qual um usuário tem acesso a um recurso ou não tem permissão para chamar uma API. Com um e-mail, um recurso e uma permissão, o solucionador de problemas de políticas examinará todas as políticas de gerenciamento de identidade e acesso (IAM, na sigla em inglês) aplicáveis ao recurso. Em seguida, ele revela se os papéis do principal incluem a permissão a esse recurso e, em caso afirmativo, quais políticas vinculam o principal a esses papéis.

É possível acessar o solucionador de problemas das políticas usando o console do Google Cloud, a Google Cloud CLI ou a API REST. Para consultas simples, o uso do console do Google Cloud normalmente é mais rápido. Em cenários mais complexos, use a CLI gcloud ou a API REST.

O console do Google Cloud também alerta caso haja alguma política de negação que possa afetar o acesso do principal. A CLI gcloud e a API REST não fornecem informações sobre políticas de negação.

Antes de começar

Ative a API Policy Troubleshooter.
Ative a API

Permissões necessárias

Para resolver problemas no acesso dos seus principais, você precisa das permissões a seguir.

Permissões para resolver problemas de acesso a principais individuais

O solucionador de problemas de políticas analisa o acesso de um principal a um recurso com base nas políticas e papéis do IAM que você tem permissão para ver. Se você não tiver permissão para visualizar uma política que se aplica a um recurso ou se não tiver permissão para visualizar um papel personalizado, talvez não seja possível dizer se um principal tem acesso.

Para receber as permissões necessárias para solucionar problemas de acesso de um principal, peça ao administrador para conceder a você o papel do IAM de Revisor de segurança (roles/iam.securityReviewer) na organização. Para mais informações sobre como conceder papéis, consulte Gerenciar o acesso.

Este papel predefinido contém as permissões necessárias para resolver problemas de acesso do principal. Para ver as permissões exatas necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

iam.roles.get
iam.roles.list
resourcemanager.folders.getIamPolicy
resourcemanager.organizations.getIamPolicy
resourcemanager.projects.getIamPolicy

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

Permissões para resolver problemas de acesso dos participantes do grupo

Se a política do IAM tiver grupos, você precisará da permissão groups.read da API Google Workspace Admin para resolver problemas de acesso a membros individuais do grupo. Os superadministradores e os administradores de grupos têm essa permissão automaticamente. Para conceder a permissão a um usuário que não é administrador do grupo ou de superadministrador, crie um papel de administrador personalizado do Google Workspace que contenha o privilégio groups.read (localizado em Privilégios da API Admin) e o conceda ao usuário.

Se você não tiver essas permissões, as vinculações de papel que contiverem grupos ou domínios terão um resultado de acesso Unknown, a menos que a vinculação também contenha explicitamente o principal.

Permissões para resolver problemas de acesso de membros do domínio

Se a política do IAM tiver domínios, você precisará ser um administrador do domínio para solucionar problemas de acesso para membros individuais do domínio.

Solução de problemas de acesso

Para resolver problemas de acesso, você precisa das seguintes informações:

Principal: o endereço de e-mail a ser verificado. Esse endereço precisa se referir a uma conta de usuário ou de serviço. Outros tipos de participantes não são compatíveis.
Recurso: o nome completo do recurso. Por exemplo, para verificar o projeto my-project, insira //cloudresourcemanager.googleapis.com/projects/my-project. Para outros tipos de recursos, consulte os exemplos de nomes completos de recursos.
Permissão: a permissão para verificar. Se você usa o console do Google Cloud, ele apresenta uma lista de sugestões enquanto você digita. Para uma lista completa de permissões, consulte a referência de permissões.

Console

Solução de problemas de acesso

Para resolver problemas de acesso, faça o seguinte:

No console do Google Cloud, acesse a página Solucionador de problemas de políticas.

Acesse o solucionador de problemas de políticas
Digite o e-mail do principal que você quer verificar.
Digite o nome do recurso e a permissão a ser verificada. Se você não souber o nome completo do recurso ou de permissão, comece a digitar para ver as opções de preenchimento automático.
Opcional: para verificar vários recursos e permissões, selecione Adicionar outro par e repita a etapa anterior.
Clique em Verificar acesso.

Como entender os resultados do solucionador de problemas de políticas

Para cada par de recurso e permissão, o solucionador de problemas de políticas fornece uma página de resultados que explica o acesso do principal.

A página de resultados contém as seguintes informações:

Detalhes da avaliação: um resumo do acesso que você está resolvendo, incluindo o principal, o recurso e a permissão especificados. Se você estiver resolvendo vários pares de permissões e recursos, é possível alternar entre eles usando a lista Avaliação de acesso.
Aviso de política negada: se uma política de negação puder afetar o acesso resolvido, o solucionador de problemas de políticas exibirá um aviso.

Esse aviso é exibido nos seguintes casos:
- Você está resolvendo problemas em uma permissão compatível com políticas de negação, e há uma política de negação que se aplica ao recurso de solução de problemas.
- Você está resolvendo problemas de uma permissão compatível com políticas de negação, mas não tem permissão para ver as políticas.
Se você não receber esse aviso, isso significa que não há políticas de negação que afetam o acesso do principal.
Detalhes da política de permissão do IAM: um breve resumo do acesso do principal com base nas políticas de permissão relevantes do IAM. Isso inclui as políticas de permissão do recurso especificado e de todos os ancestrais do recurso. Por causa da herança de política, se a principal tiver a permissão em qualquer um desses recursos, ela terá a permissão no recurso que você especificou na consulta de solução de problemas.

Essas informações permitem que você veja se o principal tem a permissão no recurso.
Recursos: uma lista do recurso especificado e dos ancestrais dele. Ao lado de cada recurso, há uma avaliação se a política de permissão do recurso concede ao principal a permissão especificada. Essa avaliação se refere apenas à política de permissão desse recurso e não reflete qualquer acesso de políticas herdadas.

Se você não tiver permissão para visualizar a política de permissão de um ancestral, a lista de recursos não incluirá esse ancestral.

Para visualizar as vinculações de papel relevantes na política de permissão de um recurso e ver como elas dão ou não a permissão ao principal, clique no recurso. As vinculações da política de permissão são exibidas no painel Vinculações de papéis.
Vinculações de papéis: uma lista de vinculações de papéis na política de permissão do recurso selecionado. Por padrão, a lista mostra apenas vinculações de papel que incluem um papel com a permissão especificada. Se o principal não tiver acesso, a lista também vai mostrar vinculações com papéis personalizados editáveis. Para ver todas as vinculações de papéis, desmarque a caixa de seleção Mostrar apenas vinculações relevantes.

A coluna Acesso indica se a vinculação de papel concede ao principal a permissão. Essa coluna pode ter qualquer um dos seguintes valores:
- Concedida: a vinculação do papel inclui o principal e um papel com a permissão.
- Não concedido: a vinculação do papel não inclui o principal ou o papel na vinculação não inclui a permissão.
- Condicional: a vinculação do papel inclui o principal e um papel com a permissão. No entanto, ele também contém uma condição, e o principal só terá acesso se a condição for atendida.
- Desconhecido: contém um papel que você não tem permissão para ver ou um grupo que você não tem permissão para verificar.
Para mais detalhes sobre a vinculação de papéis, clique em Ver detalhes de vinculação. Essa ação abre o painel Detalhes da vinculação. A guia Detalhes desse painel exibe informações sobre o papel, principais e condições na vinculação de papel. Se a vinculação de papel não conceder ao principal, esse painel também vai descrever o que você pode fazer para conceder o acesso principal.

A guia JSON exibe o texto bruto da vinculação de papel. Para saber mais sobre a estrutura das vinculações de papéis, consulte Noções básicas sobre políticas.

gcloud

Primeiro, verifique se o ambiente está configurado para usar o solucionador de problemas de políticas.

Ative a API solucionador de problemas de políticas:

gcloud services enable policytroubleshooter.googleapis.com --project=project-id

Em seguida, configure o projeto:

gcloud config set project project-id

Depois de concluir a configuração, use o solucionador de problemas de políticas para verificar se um usuário tem permissão em um recurso. Execute este comando:

gcloud policy-troubleshoot iam resource --principal-email=email \
    --permission=permission

Por exemplo, o comando a seguir verifica se foo@example.com tem a permissão resourcemanager.projects.getIamPolicy no projeto my- project.

gcloud policy-troubleshoot iam //cloudresourcemanager.googleapis.com/projects/my-project \
    --permission=resourcemanager.projects.getIamPolicy --principal-email=foo@example.com

A saída é YAML, indica se o usuário tem a permissão e fornece uma explicação do motivo. O código será semelhante a este:

access: GRANTED
explainedPolicies:
- access: GRANTED
  bindingExplanations:
  - access: NOT_GRANTED
    memberships:
      serviceAccount:service-123@compute-system.iam.gserviceaccount.com: MEMBERSHIP_NOT_INCLUDED
    role: roles/compute.serviceAgent
    rolePermission: ROLE_PERMISSION_NOT_INCLUDED
  - access: GRANTED
    memberships:
      serviceAccount:service@my-project.iam.gserviceaccount.com: MEMBERSHIP_NOT_INCLUDED
      user:foo@example.com: MEMBERSHIP_INCLUDED
    role: roles/owner
    rolePermission: ROLE_PERMISSION_INCLUDED
  fullResourceName: //cloudresourcemanager.googleapis.com/projects/my-project
  policy:
    bindings:
    - members:
      - serviceAccount:service-123@compute-system.iam.gserviceaccount.com
      role: roles/compute.serviceAgent
    - members:
      - serviceAccount:foo@my-project.iam.gserviceaccount.com
      - user:foo@example.com
      role: roles/owner
    etag: BwWAOWEaIEg=
    version: 1
- access: UNKNOWN_INFO_DENIED
policy: {}

API REST

Para descobrir por que um principal tem ou não uma permissão do IAM, use o método iam.troubleshoot da API Policy Troubleshooter.

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

EMAIL: o endereço de e-mail do participante com permissões que você quer resolver.
RESOURCE: o recurso em que a permissão é concedida.
PERMISSION: a permissão que você quer resolver.
PROJECT_ID: o ID do projeto do Google Cloud. Os IDs do projeto são strings alfanuméricas, como my-project.

Método HTTP e URL:

POST https://policytroubleshooter.googleapis.com/v1/iam:troubleshoot

Corpo JSON da solicitação:

{
  "accessTuple": {
    "principal": "EMAIL",
    "fullResourceName": "RESOURCE",
    "permission": "PERMISSION"
  }
}

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

curl (Linux, macOS ou Cloud Shell)

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que faz login automaticamente a CLI gcloud É possível verificar a conta ativa atual executando gcloud auth list.

Salve o corpo da solicitação em um arquivo chamado request.json e execute o seguinte comando:

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "x-goog-user-project: PROJECT_ID" \
    -H "Content-Type: application/json; charset=utf-8" \
    -d @request.json \
    "https://policytroubleshooter.googleapis.com/v1/iam:troubleshoot"

PowerShell (Windows)

Salve o corpo da solicitação em um arquivo chamado request.json e execute o seguinte comando:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "PROJECT_ID" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://policytroubleshooter.googleapis.com/v1/iam:troubleshoot" | Select-Object -Expand Content

API Explorer (navegador)

Copie o corpo da solicitação e abra a página de referência do método. O painel "APIs Explorer" é aberto no lado direito da página. Interaja com essa ferramenta para enviar solicitações. Cole o corpo da solicitação nessa ferramenta, preencha todos os outros campos obrigatórios e clique em Executar.

Você receberá uma resposta JSON semelhante a esta:

{
  "access": "GRANTED",
  "explainedPolicies": [
    {
      "access": "GRANTED",
      "fullResourceName": "//cloudresourcemanager.googleapis.com/projects/my-project",
      "policy": {
        "version": 1,
        "etag": "BwWBUZjK9YQ=",
        "bindings": [
          {
            "role": "roles/owner",
            "members": [
              "user:foo@example.com"
            ]
          }
        ]
      },
      "bindingExplanations": [
        {
          "access": "GRANTED",
          "role": "roles/owner",
          "rolePermission": "ROLE_PERMISSION_INCLUDED",
          "rolePermissionRelevance": "HIGH",
          "memberships": {
            "key": "user:foo@example.com",
            "value": {
              "membership": "MEMBERSHIP_INCLUDED",
              "relevance": "HIGH",
            }
          },
        "relevance: HIGH",
        }
      ]
    },
    {
      "access": "UNKNOWN_INFO_DENIED",
      "policy": {}
    }
  ]
}

Solução de problemas em vinculações de papéis condicionais

Para resolver problemas de vinculações condicionais de papel, o solucionador de problemas de políticas precisa de mais contexto sobre a solicitação. Por exemplo, para resolver problemas de condições com base em atributos de data/hora, o solucionador de problemas de políticas precisa da hora da solicitação.

Para fornecer esse contexto adicional, é possível resolver problemas diretamente de qualquer registro de auditoria da atividade do administrador ou registro de auditoria de acesso a dados. Cada entrada de registro de auditoria corresponde a uma solicitação para uma API do Google Cloud ou a uma ação realizada pelo Google Cloud em seu nome. Quando você resolve um problema de registro de auditoria, o solucionador de problemas de políticas recebe automaticamente informações adicionais sobre a solicitação, como data e hora, o que permite que o solucionador de problemas de políticas analise vinculações de papéis condicionais.

Esse recurso está disponível apenas no console do Google Cloud.

Para resolver problemas de vinculações de papéis condicionais, faça o seguinte:

No console do Google Cloud, acesse a página do Explorador de registros.

Acessar o Explorador de registros
Se o título da página for Visualizador de registros legados, clique na lista suspensa Upgrade e selecione Fazer upgrade para o novo Explorador de registros.
Para visualizar somente os registros de auditoria de Atividade do administrador e Acesso a dados, insira a seguinte consulta no criador de consultas e clique em Executar consulta:
```
logName=("RESOURCE_TYPE/RESOURCE_ID/logs/cloudaudit.googleapis.com%2Factivity" OR "RESOURCE_TYPE/RESOURCE_ID/logs/cloudaudit.googleapis.com%2Fdata_access")
```
Substitua os seguintes valores:
- RESOURCE_TYPE: o tipo de recurso que está listando os registros de auditoria. Use projects, folders ou organizations.
- RESOURCE_ID: o ID do recurso.
Localize a entrada de registro de auditoria que corresponde à solicitação que você quer solucionar. Para saber como usar o Explorador de registros para encontrar entradas de registro específicas, consulte Como usar o Explorador de registros.

Observação: em alguns casos, uma única solicitação pode produzir mais de uma entrada de registro. Analise cuidadosamente as entradas para determinar qual delas resolver.
Na coluna Resumo da entrada de registro, clique em IAM e em Resolver problemas de acesso.

O solucionador de problemas de políticas usa as informações na entrada de registro para solucionar problemas de acesso e mostra os resultados. O contexto adicional está listado nos detalhes da avaliação em Contexto de condição. Para ver os detalhes do contexto, clique em Ver contexto da condição. Para saber mais sobre a página de resultados do solucionador de problemas de políticas, consulte Como solucionar acesso nesta página.

Observação: o contexto adicional não inclui o status de associação ao grupo. Ao resolver problemas de associação a grupos, o solucionador de problemas de políticas sempre usa o status da associação ao grupo no momento da solução de problemas.
Opcional: para solucionar problemas de outra solicitação que envolva vinculações de papéis condicionais, retorne à página "Explorador de registros" e repita as etapas anteriores.

A seguir

Use a referência de permissões ou a referência de papéis predefinidos para determinar qual papel conceder a um usuário que não tem permissões.
Leia sobre as outras ferramentas do Inteligência de política, que ajudam você a entender e gerenciar suas políticas para melhorar proativamente sua configuração de segurança.