Reduzir escopo com limites de acesso a credenciais

Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

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.

Se você precisar dar aos principais um conjunto diferente de permissões para cada sessão, usar limites de acesso a credenciais pode ser mais eficiente do que criar várias contas de serviço ou conceder um conjunto de papéis diferente para 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 principal 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 principal tenta ler um objeto em example-bucket com o prefixo customer-a/invoices/, a condição é avaliada como true.
  • Quando um principal 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.

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ê usa o acesso uniforme no nível do bucket para gerenciar o acesso aos recursos do Cloud Storage.

  • 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.

Além disso, você precisa ativar as APIs necessárias:

  • Ative as APIs IAM and Security Token Service.

    Ative as APIs

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.

Conceda 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 tirar permissões de um principal, mas não consegue adicionar permissões que o principal ainda não tenha.

Dessa maneira, também é necessário conceder ao principal 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.

Componentes de um limite de acesso a credenciais

Um limite de acesso a credenciais é um objeto 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.

Quando representado como um objeto JSON, 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.

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 .

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 no formato JSON, consulte Exemplos de limites de acesso a credenciais nesta página.

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.

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 token com escopo diminuído que respeite o limite de acesso a credenciais. Esse processo normalmente envolve um agente de tokens e um consumidor de token:

  • O agente de tokens é responsável por definir o limite de acesso a credenciais e trocar um token de acesso por um token com escopo diminuído.

    O agente de token pode usar uma biblioteca de autenticação compatível para trocar tokens de acesso automaticamente ou pode chamar o Serviço de token de segurança para trocar tokens manualmente. de dados.

  • O consumidor de token solicita um token de acesso com escopo diminuído do agente de token e, em seguida, usa o token de acesso com escopo diminuído para executar outra ação.

    O consumidor de token pode usar uma biblioteca de autenticação compatível para atualizar automaticamente os tokens de acesso antes que eles expirem. Como alternativa, é possível atualizar tokens manualmente ou permitir que os tokens expirem sem atualizá-los.

Trocar e atualizar o token de acesso automaticamente

Se você criar o agente e o consumidor de token com uma das seguintes linguagens, poderá usar a biblioteca de autenticação do Google para trocar e atualizar tokens automaticamente:

Go

Para o Go, é possível trocar e atualizar tokens automaticamente com a versão v0.0.0-20210819190943-2bc19b11175f ou posterior do pacote golang.org/x/oauth2.

Para verificar a versão do pacote que você está usando, execute o seguinte comando no diretório do aplicativo:

go list -m golang.org/x/oauth2

O exemplo a seguir mostra como um agente de token pode gerar tokens com escopo diminuído:

auth/downscoping/token_broker.go 

import (
	"context"
	"fmt"

	"golang.org/x/oauth2"
	"golang.org/x/oauth2/google"
	"golang.org/x/oauth2/google/downscope"
)

// createDownscopedToken would be run on the token broker in order to generate
// a downscoped access token that only grants access to objects whose name begins with prefix.
// The token broker would then pass the newly created token to the requesting token consumer for use.
func createDownscopedToken(bucketName string, prefix string) error {
	// bucketName := "foo"
	// prefix := "profile-picture-"

	ctx := context.Background()
	// A condition can optionally be provided to further restrict access permissions.
	condition := downscope.AvailabilityCondition{
		Expression:  "resource.name.startsWith('projects/_/buckets/" + bucketName + "/objects/" + prefix + "'",
		Title:       prefix + " Only",
		Description: "Restricts a token to only be able to access objects that start with `" + prefix + "`",
	}
	// Initializes an accessBoundary with one Rule which restricts the downscoped
	// token to only be able to access the bucket "bucketName" and only grants it the
	// permission "storage.objectViewer".
	accessBoundary := []downscope.AccessBoundaryRule{
		{
			AvailableResource:    "//storage.googleapis.com/projects/_/buckets/" + bucketName,
			AvailablePermissions: []string{"inRole:roles/storage.objectViewer"},
			Condition:            &condition, // Optional
		},
	}

	// This Source can be initialized in multiple ways; the following example uses
	// Application Default Credentials.
	var rootSource oauth2.TokenSource

	// You must provide the "https://www.googleapis.com/auth/cloud-platform" scope.
	rootSource, err := google.DefaultTokenSource(ctx, "https://www.googleapis.com/auth/cloud-platform")
	if err != nil {
		return fmt.Errorf("failed to generate rootSource: %v", err)
	}

	// downscope.NewTokenSource constructs the token source with the configuration provided.
	dts, err := downscope.NewTokenSource(ctx, downscope.DownscopingConfig{RootSource: rootSource, Rules: accessBoundary})
	if err != nil {
		return fmt.Errorf("failed to generate downscoped token source: %v", err)
	}
	// Token() uses the previously declared TokenSource to generate a downscoped token.
	tok, err := dts.Token()
	if err != nil {
		return fmt.Errorf("failed to generate token: %v", err)
	}
	// Pass this token back to the token consumer.
	_ = tok
	return nil
}

O exemplo a seguir mostra como um consumidor de token pode usar um gerenciador de atualização para receber e atualizar automaticamente tokens com escopo diminuído:

auth/downscoping/token_consumer.go 

import (
	"context"
	"fmt"
	"io"
	"io/ioutil"

	"golang.org/x/oauth2/google"
	"golang.org/x/oauth2/google/downscope"

	"cloud.google.com/go/storage"
	"golang.org/x/oauth2"
	"google.golang.org/api/option"
)

// A token consumer should define their own tokenSource. In the Token() method,
// it should send a query to a token broker requesting a downscoped token.
// The token broker holds the root credential that is used to generate the
// downscoped token.
type localTokenSource struct {
	ctx        context.Context
	bucketName string
	brokerURL  string
}

func (lts localTokenSource) Token() (*oauth2.Token, error) {
	var remoteToken *oauth2.Token
	// Usually you would now retrieve remoteToken, an oauth2.Token, from token broker.
	// This snippet performs the same functionality locally.
	accessBoundary := []downscope.AccessBoundaryRule{
		{
			AvailableResource:    "//storage.googleapis.com/projects/_/buckets/" + lts.bucketName,
			AvailablePermissions: []string{"inRole:roles/storage.objectViewer"},
		},
	}
	rootSource, err := google.DefaultTokenSource(lts.ctx, "https://www.googleapis.com/auth/cloud-platform")
	if err != nil {
		return nil, fmt.Errorf("failed to generate rootSource: %v", err)
	}
	dts, err := downscope.NewTokenSource(lts.ctx, downscope.DownscopingConfig{RootSource: rootSource, Rules: accessBoundary})
	if err != nil {
		return nil, fmt.Errorf("failed to generate downscoped token source: %v", err)
	}
	// Token() uses the previously declared TokenSource to generate a downscoped token.
	remoteToken, err = dts.Token()
	if err != nil {
		return nil, fmt.Errorf("failed to generate token: %v", err)
	}

	return remoteToken, nil
}

// getObjectContents will read the contents of an object in Google Storage
// named objectName, contained in the bucket "bucketName".
func getObjectContents(output io.Writer, bucketName string, objectName string) error {
	// bucketName := "foo"
	// prefix := "profile-picture-"

	ctx := context.Background()

	thisTokenSource := localTokenSource{
		ctx:        ctx,
		bucketName: bucketName,
		brokerURL:  "yourURL.com/internal/broker",
	}

	// Wrap the TokenSource in an oauth2.ReuseTokenSource to enable automatic refreshing.
	refreshableTS := oauth2.ReuseTokenSource(nil, thisTokenSource)
	// You can now use the token source to access Google Cloud Storage resources as follows.
	storageClient, err := storage.NewClient(ctx, option.WithTokenSource(refreshableTS))
	if err != nil {
		return fmt.Errorf("failed to create the storage client: %v", err)
	}
	defer storageClient.Close()
	bkt := storageClient.Bucket(bucketName)
	obj := bkt.Object(objectName)
	rc, err := obj.NewReader(ctx)
	if err != nil {
		return fmt.Errorf("failed to retrieve the object: %v", err)
	}
	defer rc.Close()
	data, err := ioutil.ReadAll(rc)
	if err != nil {
		return fmt.Errorf("could not read the object's contents: %v", err)
	}
	// Data now contains the contents of the requested object.
	output.Write(data)
	return nil
}

Java

Para Java, é possível trocar e atualizar tokens automaticamente com a versão 1.1.0 ou mais recente do artefato com.google.auth:google-auth-library-oauth2-http.

Para verificar qual versão desse artefato você está usando, execute o seguinte comando do Maven no diretório do aplicativo:

mvn dependency:list -DincludeArtifactIds=google-auth-library-oauth2-http

O exemplo a seguir mostra como um agente de token pode gerar tokens com escopo diminuído:

auth/src/main/java/com/google/cloud/auth/samples/DownscopingExample.java 
public static AccessToken getTokenFromBroker(String bucketName, String objectPrefix)
    throws IOException {
  // Retrieve the source credentials from ADC.
  GoogleCredentials sourceCredentials =
      GoogleCredentials.getApplicationDefault()
          .createScoped("https://www.googleapis.com/auth/cloud-platform");

  // Initialize the Credential Access Boundary rules.
  String availableResource = "//storage.googleapis.com/projects/_/buckets/" + bucketName;

  // Downscoped credentials will have readonly access to the resource.
  String availablePermission = "inRole:roles/storage.objectViewer";

  // Only objects starting with the specified prefix string in the object name will be allowed
  // read access.
  String expression =
      "resource.name.startsWith('projects/_/buckets/"
          + bucketName
          + "/objects/"
          + objectPrefix
          + "')";

  // Build the AvailabilityCondition.
  CredentialAccessBoundary.AccessBoundaryRule.AvailabilityCondition availabilityCondition =
      CredentialAccessBoundary.AccessBoundaryRule.AvailabilityCondition.newBuilder()
          .setExpression(expression)
          .build();

  // Define the single access boundary rule using the above properties.
  CredentialAccessBoundary.AccessBoundaryRule rule =
      CredentialAccessBoundary.AccessBoundaryRule.newBuilder()
          .setAvailableResource(availableResource)
          .addAvailablePermission(availablePermission)
          .setAvailabilityCondition(availabilityCondition)
          .build();

  // Define the Credential Access Boundary with all the relevant rules.
  CredentialAccessBoundary credentialAccessBoundary =
      CredentialAccessBoundary.newBuilder().addRule(rule).build();

  // Create the downscoped credentials.
  DownscopedCredentials downscopedCredentials =
      DownscopedCredentials.newBuilder()
          .setSourceCredential(sourceCredentials)
          .setCredentialAccessBoundary(credentialAccessBoundary)
          .build();

  // Retrieve the token.
  // This will need to be passed to the Token Consumer.
  AccessToken accessToken = downscopedCredentials.refreshAccessToken();
  return accessToken;
}

O exemplo a seguir mostra como um consumidor de token pode usar um gerenciador de atualização para receber e atualizar automaticamente tokens com escopo diminuído:

auth/src/main/java/com/google/cloud/auth/samples/DownscopingExample.java 
public static void tokenConsumer(final String bucketName, final String objectName)
    throws IOException {
  // You can pass an `OAuth2RefreshHandler` to `OAuth2CredentialsWithRefresh` which will allow the
  // library to seamlessly handle downscoped token refreshes on expiration.
  OAuth2CredentialsWithRefresh.OAuth2RefreshHandler handler =
      new OAuth2CredentialsWithRefresh.OAuth2RefreshHandler() {
        @Override
        public AccessToken refreshAccessToken() throws IOException {
          // The common pattern of usage is to have a token broker pass the downscoped short-lived
          // access tokens to a token consumer via some secure authenticated channel.
          // For illustration purposes, we are generating the downscoped token locally.
          // We want to test the ability to limit access to objects with a certain prefix string
          // in the resource bucket. objectName.substring(0, 3) is the prefix here. This field is
          // not required if access to all bucket resources are allowed. If access to limited
          // resources in the bucket is needed, this mechanism can be used.
          return getTokenFromBroker(bucketName, objectName.substring(0, 3));
        }
      };

  // Downscoped token retrieved from token broker.
  AccessToken downscopedToken = handler.refreshAccessToken();

  // Create the OAuth2CredentialsWithRefresh from the downscoped token and pass a refresh handler
  // which will handle token expiration.
  // This will allow the consumer to seamlessly obtain new downscoped tokens on demand every time
  // token expires.
  OAuth2CredentialsWithRefresh credentials =
      OAuth2CredentialsWithRefresh.newBuilder()
          .setAccessToken(downscopedToken)
          .setRefreshHandler(handler)
          .build();

  // Use the credentials with the Cloud Storage SDK.
  StorageOptions options = StorageOptions.newBuilder().setCredentials(credentials).build();
  Storage storage = options.getService();

  // Call Cloud Storage APIs.
  Blob blob = storage.get(bucketName, objectName);
  String content = new String(blob.getContent());
  System.out.println(
      "Retrieved object, "
          + objectName
          + ", from bucket,"
          + bucketName
          + ", with content: "
          + content);
}

Node.js

Para Node.js, é possível trocar e atualizar tokens automaticamente com a versão 7.9.0 ou posterior do pacote google-auth-library.

Para verificar a versão do pacote que você está usando, execute o seguinte comando no diretório do aplicativo:

npm list google-auth-library

O exemplo a seguir mostra como um agente de token pode gerar tokens com escopo diminuído:

auth/downscoping.js 
// Imports the Google Auth libraries.
const {GoogleAuth, DownscopedClient} = require('google-auth-library');
/**
 * Simulates token broker generating downscoped tokens for specified bucket.
 *
 * @param bucketName The name of the Cloud Storage bucket.
 * @param objectPrefix The prefix string of the object name. This is used
 *        to ensure access is restricted to only objects starting with this
 *        prefix string.
 */
async function getTokenFromBroker(bucketName, objectPrefix) {
  const googleAuth = new GoogleAuth({
    scopes: 'https://www.googleapis.com/auth/cloud-platform',
  });

  // Define the Credential Access Boundary object.
  const cab = {
    // Define the access boundary.
    accessBoundary: {
      // Define the single access boundary rule.
      accessBoundaryRules: [
        {
          availableResource: `//storage.googleapis.com/projects/_/buckets/${bucketName}`,
          // Downscoped credentials will have readonly access to the resource.
          availablePermissions: ['inRole:roles/storage.objectViewer'],
          // Only objects starting with the specified prefix string in the object name
          // will be allowed read access.
          availabilityCondition: {
            expression:
              "resource.name.startsWith('projects/_/buckets/" +
              `${bucketName}/objects/${objectPrefix}')`,
          },
        },
      ],
    },
  };

  // Obtain an authenticated client via ADC.
  const client = await googleAuth.getClient();

  // Use the client to create a DownscopedClient.
  const cabClient = new DownscopedClient(client, cab);

  // Refresh the tokens.
  const refreshedAccessToken = await cabClient.getAccessToken();

  // This will need to be passed to the token consumer.
  return refreshedAccessToken;
}

O exemplo a seguir mostra como um consumidor de token pode fornecer um gerenciador de atualização que automaticamente recebe e atualiza tokens com escopo diminuído:

auth/downscoping.js 
// Imports the Google Auth and Google Cloud libraries.
const {OAuth2Client} = require('google-auth-library');
const {Storage} = require('@google-cloud/storage');
/**
 * Simulates token consumer generating calling GCS APIs using generated
 * downscoped tokens for specified bucket.
 *
 * @param bucketName The name of the Cloud Storage bucket.
 * @param objectName The name of the object in the Cloud Storage bucket
 *        to read.
 */
async function tokenConsumer(bucketName, objectName) {
  // Create the OAuth credentials (the consumer).
  const oauth2Client = new OAuth2Client();
  // We are defining a refresh handler instead of a one-time access
  // token/expiry pair.
  // This will allow the consumer to obtain new downscoped tokens on
  // demand every time a token is expired, without any additional code
  // changes.
  oauth2Client.refreshHandler = async () => {
    // The common pattern of usage is to have a token broker pass the
    // downscoped short-lived access tokens to a token consumer via some
    // secure authenticated channel. For illustration purposes, we are
    // generating the downscoped token locally. We want to test the ability
    // to limit access to objects with a certain prefix string in the
    // resource bucket. objectName.substring(0, 3) is the prefix here. This
    // field is not required if access to all bucket resources are allowed.
    // If access to limited resources in the bucket is needed, this mechanism
    // can be used.
    const refreshedAccessToken = await getTokenFromBroker(
      bucketName,
      objectName.substring(0, 3)
    );
    return {
      access_token: refreshedAccessToken.token,
      expiry_date: refreshedAccessToken.expirationTime,
    };
  };

  const storageOptions = {
    projectId: process.env.GOOGLE_CLOUD_PROJECT,
    authClient: oauth2Client,
  };

  const storage = new Storage(storageOptions);
  const downloadFile = await storage
    .bucket(bucketName)
    .file(objectName)
    .download();
  console.log(downloadFile.toString('utf8'));
}

Python

Para o Python, é possível trocar e atualizar tokens automaticamente com a versão 2.0.0 ou posterior do pacote google-auth.

Para verificar qual versão do pacote você está usando, execute o seguinte comando no ambiente em que o pacote está instalado:

pip show google-auth

O exemplo a seguir mostra como um agente de token pode gerar tokens com escopo diminuído:

auth/downscoping/snippets.py 
import google.auth

from google.auth import downscoped
from google.auth.transport import requests

def get_token_from_broker(bucket_name, object_prefix):
    """Simulates token broker generating downscoped tokens for specified bucket.

    Args:
        bucket_name (str): The name of the Cloud Storage bucket.
        object_prefix (str): The prefix string of the object name. This is used
            to ensure access is restricted to only objects starting with this
            prefix string.

    Returns:
        Tuple[str, datetime.datetime]: The downscoped access token and its expiry date.
    """
    # Initialize the Credential Access Boundary rules.
    available_resource = f"//storage.googleapis.com/projects/_/buckets/{bucket_name}"
    # Downscoped credentials will have readonly access to the resource.
    available_permissions = ["inRole:roles/storage.objectViewer"]
    # Only objects starting with the specified prefix string in the object name
    # will be allowed read access.
    availability_expression = (
        "resource.name.startsWith('projects/_/buckets/{}/objects/{}')".format(
            bucket_name, object_prefix
        )
    )
    availability_condition = downscoped.AvailabilityCondition(availability_expression)
    # Define the single access boundary rule using the above properties.
    rule = downscoped.AccessBoundaryRule(
        available_resource=available_resource,
        available_permissions=available_permissions,
        availability_condition=availability_condition,
    )
    # Define the Credential Access Boundary with all the relevant rules.
    credential_access_boundary = downscoped.CredentialAccessBoundary(rules=[rule])

    # Retrieve the source credentials via ADC.
    source_credentials, _ = google.auth.default()
    if source_credentials.requires_scopes:
        source_credentials = source_credentials.with_scopes(
            ["https://www.googleapis.com/auth/cloud-platform"]
        )

    # Create the downscoped credentials.
    downscoped_credentials = downscoped.Credentials(
        source_credentials=source_credentials,
        credential_access_boundary=credential_access_boundary,
    )

    # Refresh the tokens.
    downscoped_credentials.refresh(requests.Request())

    # These values will need to be passed to the token consumer.
    access_token = downscoped_credentials.token
    expiry = downscoped_credentials.expiry
    return (access_token, expiry)

O exemplo a seguir mostra como um consumidor de token pode fornecer um gerenciador de atualização que automaticamente recebe e atualiza tokens com escopo diminuído:

auth/downscoping/snippets.py 
from google.cloud import storage
from google.oauth2 import credentials

def token_consumer(bucket_name, object_name):
    """Tests token consumer readonly access to the specified object.

    Args:
        bucket_name (str): The name of the Cloud Storage bucket.
        object_name (str): The name of the object in the Cloud Storage bucket
            to read.
    """
    # Create the OAuth credentials from the downscoped token and pass a
    # refresh handler to handle token expiration. We are passing a
    # refresh_handler instead of a one-time access token/expiry pair.
    # This will allow the consumer to obtain new downscoped tokens on
    # demand every time a token is expired, without any additional code
    # changes.
    def refresh_handler(request, scopes=None):
        # The common pattern of usage is to have a token broker pass the
        # downscoped short-lived access tokens to a token consumer via some
        # secure authenticated channel.
        # For illustration purposes, we are generating the downscoped token
        # locally.
        # We want to test the ability to limit access to objects with a certain
        # prefix string in the resource bucket. object_name[0:3] is the prefix
        # here. This field is not required if access to all bucket resources are
        # allowed. If access to limited resources in the bucket is needed, this
        # mechanism can be used.
        return get_token_from_broker(bucket_name, object_prefix=object_name[0:3])

    creds = credentials.Credentials(
        None,
        scopes=["https://www.googleapis.com/auth/cloud-platform"],
        refresh_handler=refresh_handler,
    )

    # Initialize a Cloud Storage client with the oauth2 credentials.
    storage_client = storage.Client(credentials=creds)
    # The token broker has readonly access to the specified bucket object.
    bucket = storage_client.bucket(bucket_name)
    blob = bucket.blob(object_name)
    print(blob.download_as_bytes().decode("utf-8"))

Trocar e atualizar o token de acesso manualmente

Um agente de token pode usar a API Security Token Service para trocar um token de acesso por um token de acesso com escopo diminuído. Em seguida, ele pode fornecer o token com escopo diminuído a um consumidor de token.

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

Um limite de acesso a credenciais no formato JSON, codificado com codificação percentual.

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 token de acesso do OAuth 2.0 com escopo diminuído que respeita o limite de acesso a credenciais.

expires_in

number

O tempo até o token com escopo diminuído expirar, em segundos.

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 token com escopo diminuído 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 um limite de acesso a credenciais no formato JSON 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
}

Quando um consumidor de token solicita um token com escopo diminuído, o agente de token deve responder com o token com escopo diminuído e o número de segundos até que expire. Para atualizar o token com escopo diminuído, o consumidor pode solicitar um token com escopo reduzido do agente antes que o token atual expire.

A seguir