Package google.iam.v1

Índice

IAMPolicy

Visão geral da API

Gerencia as políticas de gerenciamento de identidade e acesso (IAM, na sigla em inglês).

Qualquer implementação de uma API que ofereça recursos de controle de acesso implementa a interface google.iam.v1.IAMPolicy.

Modelo de dados

O controle de acesso é aplicado quando um principal (usuário ou conta de serviço) executa alguma ação em um recurso exposto por um serviço. Os recursos, identificados por nomes semelhantes a URI, são a unidade de especificação de controle de acesso. As implementações de serviço podem escolher a granularidade do controle de acesso e as permissões aceitas nos recursos. Por exemplo, um serviço de banco de dados pode permitir que o controle de acesso seja especificado somente no nível da Tabela, já outro pode permitir que o controle de acesso também seja especificado no nível da Coluna.

Estrutura da política

Consulte google.iam.v1.Policy

Ela não tem a intenção de ser uma API no estilo CRUD porque as políticas de controle de acesso são criadas e excluídas implicitamente com os recursos aos quais são anexadas.

GetIamPolicy

rpc GetIamPolicy(GetIamPolicyRequest) returns (Policy)

Busca a política de controle de acesso a um recurso. Retorna uma política vazia se o recurso estiver presente e não tiver um conjunto de políticas.

Escopos de autorização

Requer o seguinte escopo OAuth:

  • https://www.googleapis.com/auth/cloud-platform

Para mais informações, consulte a Visão geral da autenticação.
SetIamPolicy

rpc SetIamPolicy(SetIamPolicyRequest) returns (Policy)

Define a política de controle de acesso no recurso especificado. Substitui qualquer política atual.

Pode retornar erros NOT_FOUND, INVALID_ARGUMENT e PERMISSION_DENIED.

Escopos de autorização

Requer o seguinte escopo OAuth:

  • https://www.googleapis.com/auth/cloud-platform

Para mais informações, consulte a Visão geral da autenticação.
TestIamPermissions

rpc TestIamPermissions(TestIamPermissionsRequest) returns (TestIamPermissionsResponse)

Retorna permissões do autor da chamada no recurso especificado. Se o recurso não existir, isso retornará um conjunto vazio de permissões, mas não um erro NOT_FOUND.

Observação: essa operação foi projetada para ser usada na criação de IUs e ferramentas de linha de comando e não para verificação de autorização. Essa operação pode "falhar em abrir" sem aviso prévio.

Escopos de autorização

Requer o seguinte escopo OAuth:

  • https://www.googleapis.com/auth/cloud-platform

Para mais informações, consulte a Visão geral da autenticação.

Vinculação

Associa members, ou principais, a um role.

Campos
role

string

Papel atribuído à lista de members ou principais. Por exemplo, roles/viewer, roles/editor ou roles/owner.
members[]

string

Especifica as identidades que solicitam acesso a um recurso do Google Cloud. members pode ter os seguintes valores:

  • allUsers: um identificador especial que representa qualquer pessoa na Internet, com ou sem uma conta do Google.

  • allAuthenticatedUsers: um identificador especial que representa qualquer pessoa autenticada com uma Conta do Google ou uma conta de serviço. Não inclui identidades de provedores de identidade externos (IdPs) pela federação de identidade.

  • user:{emailid}: um endereço de e-mail que representa uma Conta do Google específica. Por exemplo, alice@example.com.

  • serviceAccount:{emailid}: um endereço de e-mail que representa uma conta de serviço do Google. Por exemplo, my-other-app@appspot.gserviceaccount.com.

  • serviceAccount:{projectid}.svc.id.goog[{namespace}/{kubernetes-sa}]: identificador de uma conta de serviço do Kubernetes. Por exemplo, my-project.svc.id.goog[my-namespace/my-kubernetes-sa].

  • group:{emailid}: um endereço de e-mail que representa um grupo do Google. Por exemplo, admins@example.com.

  • domain:{domain}: domínio do G Suite (principal) que representa todos os usuários dele. Por exemplo, google.com ou example.com.

  • deleted:user:{emailid}?uid={uniqueid}: um endereço de e-mail (mais identificador exclusivo) que representa um usuário que foi excluído recentemente. Por exemplo, alice@example.com?uid=123456789012345678901. Se o usuário for recuperado, esse valor será revertido para user:{emailid} e o usuário recuperado manterá o papel na vinculação.

  • deleted:serviceAccount:{emailid}?uid={uniqueid}: um endereço de e-mail (além do identificador exclusivo) que representa uma conta de serviço que foi excluída recentemente. Por exemplo, my-other-app@appspot.gserviceaccount.com?uid=123456789012345678901. Se a exclusão da conta de serviço for revertida, esse valor será revertido para serviceAccount:{emailid}, e a conta de serviço não excluída manterá o papel na vinculação.

  • deleted:group:{emailid}?uid={uniqueid}: um endereço de e-mail, mais um identificador exclusivo, que representa um grupo do Google que foi excluído recentemente. Por exemplo, admins@example.com?uid=123456789012345678901. Se o grupo for recuperado, esse valor será revertido para group:{emailid} e o grupo recuperado manterá o papel na vinculação.
condition

Expr

A condição que está associada a essa vinculação.

Se a condição for avaliada como true, essa vinculação se aplicará à solicitação atual.

Se a condição for avaliada como false, essa vinculação não se aplicará à solicitação atual. No entanto, uma vinculação de papel diferente pode conceder o mesmo papel a um ou mais principais da vinculação.

Para saber quais recursos são compatíveis com as condições nas políticas do IAM, consulte a documentação do IAM.

GetIamPolicyRequest

Solicita uma mensagem ao método GetIamPolicy.

Campos
resource

string

OBRIGATÓRIO: o recurso para o qual a política está sendo solicitada. Consulte Nomes de recursos para saber o valor apropriado para esse campo.
options

GetPolicyOptions

OPCIONAL: um objeto GetPolicyOptions para especificar opções para GetIamPolicy.

GetPolicyOptions

Encapsula as configurações fornecidas para GetIamPolicy.

Campos
requested_policy_version

int32

Opcional. A versão máxima da política que será usada para formatar a política.

Os valores válidos são: 0, 1 e 3. Solicitações especificando um valor inválido serão rejeitadas.

As solicitações de políticas com qualquer vinculação de papel condicional precisam especificar a versão 3. As políticas sem vinculações de papéis condicionais podem especificar qualquer valor válido ou deixar o campo sem definição.

A política na resposta pode usar a versão da política especificada ou uma versão anterior. Por exemplo, se você especificar a versão 3, mas a política não tiver vinculações de papéis condicionais, a resposta usará a versão 1.

Para saber quais recursos são compatíveis com as condições nas políticas do IAM, consulte a documentação do IAM.

Policy

Uma política de gerenciamento de identidade e acesso (IAM), que especifica controles de acesso para recursos do Google Cloud.

Um Policy é uma coleção de bindings. Uma binding vincula um ou mais members, ou principais, a um único role. Os membros podem ser contas de usuário, contas de serviço, Grupos do Google e domínios, como o G Suite. Um role é uma lista nomeada de permissões. Cada role pode ser um papel pré-definido do IAM ou um papel personalizado criado pelo usuário.

Para determinados tipos de recursos do Google Cloud, uma binding também pode especificar uma condition, que é uma expressão lógica que permitirá acesso a um recurso somente se a expressão for avaliada como true. Uma condição pode adicionar restrições com base nos atributos da solicitação, do recurso ou de ambos. Para saber quais recursos são compatíveis com as condições nas políticas do IAM, consulte a documentação do IAM.

Exemplo de JSON:

    {
      "bindings": [
        {
          "role": "roles/resourcemanager.organizationAdmin",
          "members": [
            "user:mike@example.com",
            "group:admins@example.com",
            "domain:google.com",
            "serviceAccount:my-project-id@appspot.gserviceaccount.com"
          ]
        },
        {
          "role": "roles/resourcemanager.organizationViewer",
          "members": [
            "user:eve@example.com"
          ],
          "condition": {
            "title": "expirable access",
            "description": "Does not grant access after Sep 2020",
            "expression": "request.time < timestamp('2020-10-01T00:00:00.000Z')",
          }
        }
      ],
      "etag": "BwWWja0YfJA=",
      "version": 3
    }

Exemplo de YAML:

    bindings:
    - members:
      - user:mike@example.com
      - group:admins@example.com
      - domain:google.com
      - serviceAccount:my-project-id@appspot.gserviceaccount.com
      role: roles/resourcemanager.organizationAdmin
    - members:
      - user:eve@example.com
      role: roles/resourcemanager.organizationViewer
      condition:
        title: expirable access
        description: Does not grant access after Sep 2020
        expression: request.time < timestamp('2020-10-01T00:00:00.000Z')
    etag: BwWWja0YfJA=
    version: 3

Para uma descrição do IAM e dos recursos dele, consulte a documentação do IAM.

Campos
version

int32

Especifica o formato da política.

Os valores válidos são 0, 1 e 3. As solicitações que especificam um valor inválido são rejeitadas.

Qualquer operação que afete as vinculações condicionais de papel precisa especificar a versão 3. Esse requisito se aplica às seguintes operações:

  • Como conseguir uma política que inclua uma vinculação de papel condicional
  • Como adicionar uma vinculação de papel condicional a uma política
  • Como alterar uma vinculação de papel condicional em uma política
  • Como remover qualquer vinculação de papel (com ou sem uma condição) de uma política que inclua condições

Importante: se você usar as condições do IAM, precisará incluir o campo etag sempre que chamar setIamPolicy. Se você omitir esse campo, o IAM permitirá substituir uma política de versão 3 por uma política de versão 1, e todas as condições na política de versão 3 serão perdidas.

Se uma política não incluir nenhuma condição, as operações nessa política poderão especificar qualquer versão válida ou deixar o campo não definido.

Para saber quais recursos são compatíveis com as condições nas políticas do IAM, consulte a documentação do IAM.
bindings[]

Binding

Associa uma lista de members ou principais a um role. Como alternativa, pode especificar um condition que determina como e quando o bindings é aplicado. Cada bindings precisa conter pelo menos um membro.

O bindings em uma Policy pode se referir a até 1.500 principais. até 250 desses principais podem ser grupos do Google. Cada ocorrência de um principal conta para esses limites. Por exemplo, se o bindings conceder 50 papéis diferentes a user:alice@example.com, e não a qualquer outro principal, será possível adicionar mais 1.450 principais ao bindings no Policy.
etag

bytes

etag é usado para otimização do controle de simultaneidade, para ajudar a evitar que atualizações simultâneas de uma política substituam-se mutuamente. É altamente recomendável que os sistemas usem etag no ciclo de leitura-modificação-gravação para fazer atualizações de política e evitar disputas. Um etag é retornado na resposta a getIamPolicy e ele é colocado na solicitação a setIamPolicy para garantir que a alteração seja aplicada à mesma versão da política.

Importante: se você usar as condições do IAM, precisará incluir o campo etag sempre que chamar setIamPolicy. Se você omitir esse campo, o IAM permitirá substituir uma política de versão 3 por uma política de versão 1, e todas as condições na política de versão 3 serão perdidas.

SetIamPolicyRequest

Solicita uma mensagem ao método SetIamPolicy.

Campos
resource

string

OBRIGATÓRIO: o recurso para que a política está sendo especificada. Consulte Nomes de recursos para saber o valor apropriado para esse campo.
policy

Policy

OBRIGATÓRIO: a política completa a ser aplicada ao resource. O tamanho da política é limitado a algumas dezenas de KBs. Uma política vazia é válida, mas alguns serviços do Google Cloud (como Projetos) podem rejeitá-la.

TestIamPermissionsRequest

Solicita uma mensagem ao método TestIamPermissions.

Campos
resource

string

OBRIGATÓRIO: o recurso para o qual o detalhe da política está sendo solicitado. Consulte Nomes de recursos para saber o valor apropriado para esse campo.
permissions[]

string

O conjunto de permissões a serem verificadas para o resource. As permissões com caracteres curinga (como * ou storage.*) não são permitidas. Para mais informações, consulte a Visão geral do IAM.

TestIamPermissionsResponse

Mensagem de resposta para o método TestIamPermissions.

Campos
permissions[]

string

Um subconjunto de TestPermissionsRequest.permissions para que o autor da chamada tem permissão.