Como diminuir o escopo usando limites de acesso a credenciais

Nesta página, explicamos como usar os limites de acesso a credenciais para diminuir o escopo ou restringir as permissões de gerenciamento de identidade e acesso (IAM) que uma credencial de curta duração pode usar.

Como funcionam os limites de acesso a credenciais

Para diminuir o escopo das permissões, defina um limite de acesso a credenciais que especifique quais recursos a credencial de curta duração poderá acessar, assim como um limite máximo nas permissões disponíveis em cada recurso. Crie uma credencial de curta duração e, então, troque-a por uma nova credencial que respeite o limite de acesso a credenciais.

Observação: apenas o Cloud Storage é compatível com limites de acesso a credenciais. Os outros serviços do Google Cloud não são compatíveis com esse recurso.

Se você precisar dar aos membros um conjunto distinto de permissões para cada sessão, é possível que o uso de limites de acesso a credenciais seja mais eficiente do que a criação de várias contas de serviço e do que a concessão de um conjunto de papéis diferente a cada conta de serviço. Por exemplo, se um de seus clientes precisar acessar dados do Cloud Storage que você controla, crie uma conta de serviço que acesse todos os buckets do Google Cloud Storage e aplique um limite de acesso a credenciais que permita acesso apenas ao bucket com os dados do cliente.

Exemplos de limites de acesso a credenciais

Nas seções a seguir, mostramos exemplos de limites de acesso a credenciais para casos de uso comuns. Você usa o limite de acesso a credenciais ao trocar um token de acesso do OAuth 2.0 por um token com escopo diminuído.

Limitar permissões para um bucket

No exemplo a seguir, mostramos um limite de acesso a credenciais simples. Ele se aplica ao bucket example-bucket do Cloud Storage e define o limite máximo para as permissões incluídas no papel Leitor de objetos do Storage (roles/storage.objectViewer):

{
  "accessBoundary": {
    "accessBoundaryRules": [
      {
        "availablePermissions": [
          "inRole:roles/storage.objectViewer"
        ],
        "availableResource": "//storage.googleapis.com/projects/_/buckets/example-bucket"
      }
    ]
  }
}

Limitar permissões para vários buckets

No exemplo a seguir, mostramos um limite de acesso a credenciais que inclui regras para vários buckets:

• O bucket do Cloud Storage example-bucket-1: para esse bucket, apenas as permissões no papel Leitor de objetos do Storage (roles/storage.objectViewer) estão disponíveis.
• O bucket do Cloud Storage example-bucket-2: para esse bucket, apenas as permissões no papel Criador de objeto do Storage (roles/storage.objectCreator) estão disponíveis.

{
  "accessBoundary": {
    "accessBoundaryRules": [
      {
        "availablePermissions": [
          "inRole:roles/storage.objectViewer"
        ],
        "availableResource": "//storage.googleapis.com/projects/_/buckets/example-bucket-1"
      },
      {
        "availablePermissions": [
          "inRole:roles/storage.objectCreator"
        ],
        "availableResource": "//storage.googleapis.com/projects/_/buckets/example-bucket-2"
      }
    ]
  }
}

Limitar permissões para objetos específicos

Também é possível usar as condições do IAM para especificar quais objetos do Cloud Storage um membro pode acessar. Por exemplo, adicione uma condição que disponibilize permissões para objetos com nome que comece com customer-a:

{
  "accessBoundary": {
    "accessBoundaryRules": [
      {
        "availablePermissions": [
          "inRole:roles/storage.objectViewer"
        ],
        "availableResource": "//storage.googleapis.com/projects/_/buckets/example-bucket",
        "availabilityCondition": {
          "expression" : "resource.name.startsWith('projects/_/buckets/example-bucket/objects/customer-a')"
        }
      }
    ]
  }
}

Limitar permissões ao listar objetos

Ao listar os objetos em um intervalo do Cloud Storage, você chama um método em um recurso do bucket, não em um recurso do objeto. Como resultado, se uma condição for avaliada para uma solicitação de lista e a condição se referir ao nome do recurso, o nome do recurso identificará o bucket, não um objeto dentro do bucket. Por exemplo, quando você lista objetos em example-bucket, o nome do recurso é projects/_/buckets/example-bucket.

Essa convenção de nomenclatura pode causar um comportamento inesperado ao listar objetos. Por exemplo, suponha que você queira um limite de acesso a credenciais que permita acesso para ver objetos em example-bucket com o prefixo customer-a/invoices/. Tente usar a seguinte condição no limite de acesso a credenciais:

Incompleto: condição que verifica apenas o nome do recurso

resource.name.startsWith('projects/_/buckets/example-bucket/objects/customer-a/invoices/')

Essa condição funciona para ler objetos, mas não para listá-los:

• Quando um membro tenta ler um objeto em example-bucket com o prefixo customer-a/invoices/, a condição é avaliada como true.
• Quando um membro tenta listar objetos com esse prefixo, a condição é avaliada como false. O valor de resource.name é projects/_/buckets/example-bucket, que não começa com projects/_/buckets/example-bucket/objects/customer-a/invoices/.

Para evitar esse problema, além de usar resource.name.startsWith(), sua condição pode verificar um atributo de API chamado storage.googleapis.com/objectListPrefix. Esse atributo contém o valor do parâmetro prefix que foi usado para filtrar a lista de objetos. Como resultado, é possível escrever uma condição que se refira ao valor do parâmetro prefix.

Aviso: os atributos da API do Cloud Storage são compatíveis apenas com limites de acesso a credenciais. Se você usar atributos da API Cloud Storage em uma vinculação de papel condicional, os métodos do Cloud Storage funcionarão incorretamente e falharão inesperadamente. Além disso, pode demorar mais para verificar as permissões do IAM quando você acessar o Cloud Storage.

No exemplo a seguir, mostramos como usar o atributo de API em uma condição. Ele permite ler e listar objetos em example-bucket com o prefixo customer-a/invoices/:

Completo: condição que verifica o nome do recurso e o prefixo

resource.name.startsWith('projects/_/buckets/example-bucket/objects/customer-a/invoices/')  ||
    api.getAttribute('storage.googleapis.com/objectListPrefix', '')
                     .startsWith('customer-a/invoices/')

Agora é possível usar essa condição em um limite de acesso a credenciais:

{
  "accessBoundary": {
    "accessBoundaryRules": [
      {
        "availablePermissions": [
          "inRole:roles/storage.objectViewer"
        ],
        "availableResource": "//storage.googleapis.com/projects/_/buckets/example-bucket",
        "availabilityCondition": {
          "expression":
            "resource.name.startsWith('projects/_/buckets/example-bucket/objects/customer-a/invoices/') || api.getAttribute('storage.googleapis.com/objectListPrefix', '').startsWith('customer-a/invoices/')"
        }
      }
    ]
  }
}

Antes de começar

Antes de usar limites de acesso a credenciais, certifique-se de que você atende aos seguintes requisitos:

• Você precisa diminuir o escopo de permissões apenas para o Cloud Storage, não para outros serviços do Google Cloud.

  Se você precisar diminuir o escopo de permissões para outros serviços do Google Cloud, crie várias contas de serviço e conceda um conjunto diferente de funções a cada conta de serviço.

• Você consegue usar tokens de acesso do OAuth 2.0 para autenticação. Outros tipos de credenciais de curta duração não são compatíveis com os limites de acesso a credenciais.

Como criar uma credencial de curta duração com escopo diminuído

Para criar um token de acesso do OAuth 2.0 com permissões escopo diminuído, siga estas etapas:

1. Conceda os papéis apropriados do IAM a um usuário ou conta de serviço.
2. Defina um limite de acesso a credenciais que configure um limite superior para as permissões disponíveis para o usuário ou conta de serviço.
3. Crie um token de acesso do OAuth 2.0 para o usuário ou conta de serviço.
4. Troque o token de acesso do OAuth 2.0 por um novo token que respeite o limite de acesso a credenciais.

Em seguida, será possível usar o novo token de acesso do OAuth 2.0 com escopo diminuído para autenticar as solicitações para o Cloud Storage.

Como conceder papéis do IAM

Um limite de acesso a credenciais configura um limite superior para as permissões disponíveis para um recurso. Ele consegue subtrair permissões de um membro, mas não de adicionar permissões que o membro ainda não tenha.

Dessa maneira, também é necessário conceder ao membro papéis que garantam as permissões de que ele precisa, seja em um intervalo do Cloud Storage, seja em um recurso de nível superior, como o projeto.

Por exemplo, suponha que você precise criar uma credencial de curta duração com escopo diminuído que permita que uma conta de serviço crie objetos em um bucket:

• No mínimo, é necessário conceder um papel à conta de serviço que inclua a permissão storage.objects.create, como o papel Criador de objetos do Storage (roles/storage.objectCreator). Também é necessário que o limite de acesso a credenciais inclua essa permissão.
• Também é possível conceder um papel que inclua mais permissões, como o de Administrador de objetos do Storage (roles/storage.objectAdmin). A conta de serviço poderá usar apenas as permissões que aparecem na concessão do papel e no limite de acesso a credenciais.

Consulte Papéis do Cloud Storage para saber mais.

Como definir um limite de acesso a credenciais

Um limite de acesso a credenciais é um objeto JSON que contém uma lista de regras de limite de acesso. Cada regra contém as seguintes informações:

• O recurso a que a regra se aplica.
• O limite máximo das permissões disponíveis nesse recurso.
• Opcional: uma condição que restringe ainda mais as permissões. Uma condição inclui o seguinte:
  • Uma expressão de condição avaliada como true ou false. Se ela for avaliada como true, o acesso será permitido. Caso contrário, o acesso será negado.
  • Opcional: um título que identifica a condição.
  • Opcional: uma descrição com mais informações sobre a condição.

Se você aplicar um limite de acesso a credenciais a uma credencial de curta duração, ela só poderá acessar os recursos dentro do limite de acesso a credenciais. Nenhuma permissão está disponível em outros recursos.

Um limite de acesso a credenciais contém até 10 regras de limite de acesso. É possível aplicar apenas um limite de acesso a credenciais a cada credencial de curta duração.

Um limite de acesso a credenciais contém os seguintes campos:

Campos
accessBoundary	object Um wrapper para o limite de acesso a credenciais.
accessBoundary.accessBoundaryRules[]	object Uma lista de regras de limite de acesso a ser aplicada a uma credencial de curta duração.
accessBoundary.accessBoundaryRules[].availablePermissions[]	string Uma lista que define o limite superior das permissões disponíveis para o recurso. Cada valor é o identificador de um papel predefinido ou papel personalizado do IAM com o prefixo inRole:. Por exemplo: inRole:roles/storage.objectViewer. Somente as permissões nesses papéis estarão disponíveis. Observação: não é possível especificar os nomes das permissões diretamente. Em vez disso, especifique um papel em que a permissão aparece. Se necessário, crie um papel personalizado que inclua apenas as permissões necessárias.
accessBoundary.accessBoundaryRules[].availableResource	string O nome completo do recurso do bucket do Cloud Storage a que a regra se aplica. Use o formato //storage.googleapis.com/projects/_/buckets/bucket-name.
accessBoundary.accessBoundaryRules[].availabilityCondition	object Opcional. Uma condição que restringe a disponibilidade de permissões a objetos específicos do Cloud Storage. Use este campo para disponibilizar permissões para objetos específicos em vez de todos os objetos em um intervalo do Cloud Storage.
accessBoundary.accessBoundaryRules[].availabilityCondition.expression	string Uma expressão de condição que especifica os objetos do Cloud Storage em que as permissões estão disponíveis. Para saber como se referir a objetos específicos em uma expressão de condição, consulte o atributo resource.name . Observação: se algum dos seus aplicativos listar objetos do Cloud Storage e usar o parâmetro prefix para filtrar a resposta, será preciso executar outras etapas para evitar um conflito entre a expressão de condição do IAM e o filtro do Cloud Storage. Para detalhes, consulte Limitar as permissões ao listar objetos nesta página.
accessBoundary.accessBoundaryRules[].availabilityCondition.title	string Opcional. Uma string curta que identifica a finalidade da condição.
accessBoundary.accessBoundaryRules[].availabilityCondition.description	string Opcional. Detalhes sobre a finalidade da condição.

Para exemplos, consulte Exemplos de limites de acesso a credenciais nesta página.

Crie um arquivo JSON que defina um limite de acesso a credenciais. Você usará esse arquivo quando trocar um token de acesso do OAuth 2.0 por um token com escopo diminuído.

Como criar um token de acesso do OAuth 2.0

Antes de criar uma credencial de curta duração com escopo diminuído, é necessário criar um token de acesso normal do OAuth 2.0. Em seguida, será possível trocar a credencial normal por uma credencial com escopo diminuído. Ao criar o token de acesso, use o escopo https://www.googleapis.com/auth/cloud-platform do OAuth 2.0.

Para criar um token de acesso para uma conta de serviço, conclua o fluxo do OAuth 2.0 de servidor para servidor ou use a API Service Account Credentials para gerar um token de acesso do OAuth 2.0.

Para criar um token de acesso para um usuário, consulte Como receber tokens de acesso do OAuth 2.0. Também é possível usar o OAuth 2.0 Playground para criar um token de acesso para sua própria Conta do Google.

Como trocar o token de acesso do OAuth 2.0

Depois de criar um token de acesso do OAuth 2.0, é possível trocá-lo por um novo que respeite o limite de acesso a credenciais. Troque o token de acesso por meio da API Security Token Service, que faz parte do Identity Platform.

Para trocar o token de acesso, use o método HTTP e URL a seguir:

POST https://sts.googleapis.com/v1/token

Defina o cabeçalho Content-Type na solicitação como application/x-www-form-urlencoded. Inclua os seguintes campos no corpo da solicitação:

Campos
grant_type	string Use o valor urn:ietf:params:oauth:grant-type:token-exchange.
options	string O limite de acesso a credenciais codificado por porcentagem.
requested_token_type	string Use o valor urn:ietf:params:oauth:token-type:access_token.
subject_token	string O token de acesso do OAuth 2.0 que você quer trocar.
subject_token_type	string Use o valor urn:ietf:params:oauth:token-type:access_token.

A resposta é um objeto JSON que contém os seguintes campos:

Campos
access_token	string Um novo token de acesso do OAuth 2.0 que respeita o limite de acesso a credenciais.
expires_in	number O tempo restante, em segundo, do prazo de validade do novo token de acesso. Esse campo só estará presente se o token de acesso original representar uma conta de serviço. Se esse campo não estiver presente, o novo token de acesso terá o mesmo tempo de validade do token de acesso original.
issued_token_type	string Contém o valor urn:ietf:params:oauth:token-type:access_token.
token_type	string Contém o valor Bearer.

Por exemplo, se o limite de acesso a credenciais estiver armazenado no arquivo ./access-boundary.json, use o comando curl a seguir para trocar o token de acesso. Substitua original-token pelo token de acesso original:

curl -H "Content-Type:application/x-www-form-urlencoded" \
    -X POST \
    https://sts.googleapis.com/v1/token \
    -d "grant_type=urn:ietf:params:oauth:grant-type:token-exchange&subject_token_type=urn:ietf:params:oauth:token-type:access_token&requested_token_type=urn:ietf:params:oauth:token-type:access_token&subject_token=original-token" \
    --data-urlencode "options=$(cat ./access-boundary.json)"

A resposta será semelhante ao seguinte exemplo:

{
  "access_token": "ya29.dr.AbCDeFg-123456...",
  "issued_token_type": "urn:ietf:params:oauth:token-type:access_token",
  "token_type": "Bearer",
  "expires_in": 3600
}

A seguir

• Saiba mais sobre o controle de acesso para Cloud Storage.
• Crie uma credencial de conta de serviço de curta duração.
• Crie um token de acesso do OAuth 2.0 para uma conta de serviço usando o fluxo do OAuth 2.0 de servidor para servidor ou a API Service Account Credentials.
• Crie um token de acesso do OAuth 2.0 para um usuário.
• Consulte as permissões em cada papel predefinido.
• Saiba mais sobre papéis personalizados.