Crie uma credencial de curta duração com âmbito reduzido

Esta página explica como usar limites de acesso de credenciais para criar um token de acesso OAuth 2.0 com autorizações do Cloud Storage com âmbito reduzido.

O processo de criação de um token com autorizações restritas inclui os seguintes passos:

  1. Conceda as funções de IAM adequadas a um utilizador ou a uma conta de serviço.
  2. Defina um limite de acesso às credenciais que estabelece um limite superior para as autorizações disponíveis para o utilizador ou a conta de serviço.
  3. Crie uma chave de acesso OAuth 2.0 para o utilizador ou a conta de serviço.
  4. Troque a chave de acesso OAuth 2.0 por uma nova chave que respeite o limite de acesso às credenciais.

Em seguida, pode usar o novo token de acesso OAuth 2.0 com âmbito reduzido para autenticar pedidos ao Cloud Storage.

Antes de começar

Antes de usar os limites de acesso às credenciais, certifique-se de que cumpre os seguintes requisitos:

  • Tem de restringir as autorizações apenas para o Cloud Storage e não para outros serviçosGoogle Cloud .

    Se precisar de reduzir o âmbito das autorizações para serviços Google Cloud adicionais, pode criar várias contas de serviço e conceder um conjunto diferente de funções a cada conta de serviço.

  • Pode usar chaves de acesso OAuth 2.0 para autenticação. Outros tipos de credenciais de curta duração não suportam limites de acesso às credenciais.

Além disso, tem de ativar as APIs necessárias:

  • Enable the IAM and Security Token Service APIs.

    Enable the APIs

Conceda funções de IAM

Um limite de acesso às credenciais define um limite superior para as autorizações disponíveis para um recurso. Pode subtrair autorizações de um principal, mas não pode adicionar autorizações que o principal ainda não tenha.

Como resultado, também tem de conceder funções ao principal que forneçam as autorizações de que necessita, num contentor do Cloud Storage ou num recurso de nível superior, como o projeto.

Por exemplo, suponhamos que precisa de criar uma credencial de curta duração com âmbito reduzido que permita a uma conta de serviço criar objetos num contentor:

  • No mínimo, tem de conceder uma função à conta de serviço que inclua a autorização storage.objects.create, como a função Storage Object Creator (roles/storage.objectCreator). O limite de acesso às credenciais também tem de incluir esta autorização.
  • Também pode conceder uma função que inclua mais autorizações, como a função de administrador de objetos de armazenamento (roles/storage.objectAdmin). A conta de serviço só pode usar as autorizações que aparecem na concessão de funções e no limite de acesso às credenciais.

Para saber mais sobre as funções predefinidas do Cloud Storage, consulte o artigo Funções do Cloud Storage.

Defina o limite de acesso às credenciais

Um limite de acesso de credenciais é um objeto que contém uma lista de regras de limites de acesso. As regras são compostas por parâmetros que especificam o limite superior das autorizações disponíveis para o utilizador ou a conta de serviço. Para definir um limite de acesso de credenciais, crie um objeto JSON que liste as regras do limite de acesso e os respetivos parâmetros.

Segue-se um exemplo de um limite de acesso às credenciais:

{
  "accessBoundary": {
    "accessBoundaryRules": [
      {
        "availablePermissions": [
          "inRole:ROLE_ID"
        ],
        "availableResource": "//storage.googleapis.com/projects/_/buckets/BUCKET_NAME"
         "availabilityCondition": {
            "expression" : "CONDITION"
      }
    ]
  }
}

Substitua o seguinte:

  • ROLE_ID: O ID de uma função predefinida ou personalizada que define o limite superior das autorizações disponíveis para o recurso. Por exemplo, roles/storage.objectViewer. Para especificar várias funções, adicione uma nova linha com o prefixo inRole: seguido do ID da função. Apenas as autorizações nas funções especificadas vão estar disponíveis.
  • BUCKET_NAME: o nome do contentor do Cloud Storage ao qual a regra se aplica.

  • CONDITION: opcional. Uma expressão de condição que especifica os objetos do Cloud Storage onde as autorizações estão disponíveis. Por exemplo, a seguinte condição disponibiliza autorizações para objetos cujo nome começa por customer-a:

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

Para saber como criar e personalizar limites de acesso a credenciais, consulte o artigo Componentes de um limite de acesso a credenciais.

Para ver exemplos de potenciais exemplos de utilização de limites de acesso a credenciais, consulte o artigo Exemplos de limites de acesso a credenciais.

Crie uma chave de acesso OAuth 2.0

Antes de criar uma credencial de curta duração com âmbito reduzido, tem de criar uma chave de acesso OAuth 2.0 normal. Em seguida, pode trocar a credencial normal por uma credencial com âmbito reduzido. Quando criar a chave de acesso, use o âmbito do OAuth 2.0 https://www.googleapis.com/auth/cloud-platform.

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

Para criar uma chave de acesso para um utilizador, consulte o artigo Obter chaves de acesso OAuth 2.0. Também pode usar o OAuth 2.0 Playground para criar um token de acesso para a sua própria Conta Google.

Troque a chave de acesso OAuth 2.0

Depois de criar uma chave de acesso OAuth 2.0, pode trocar a chave de acesso por uma chave com âmbito reduzido que respeite o limite de acesso das credenciais. Normalmente, este processo envolve um agente de tokens e um consumidor de tokens:

  • O agente de tokens é responsável por definir o limite de acesso de credenciais e trocar um token de acesso por um token com âmbito reduzido.

    O agente de tokens pode usar uma biblioteca de autenticação suportada para trocar automaticamente tokens de acesso ou pode chamar o serviço de tokens de segurança para trocar tokens manualmente.

  • O consumidor de tokens pede um token de acesso com âmbito reduzido ao agente de tokens e, em seguida, usa o token de acesso com âmbito reduzido para realizar outra ação.

    O consumidor do token pode usar uma biblioteca de autenticação suportada para atualizar automaticamente os tokens de acesso antes de expirarem. Em alternativa, pode atualizar os tokens manualmente ou permitir que os tokens expirem sem os atualizar.

Existem duas formas de trocar o token de acesso por um token com âmbito reduzido:

  • Troca de tokens do lado do cliente (recomendada): os clientes obtêm materiais criptográficos do servidor da API Security Token Service. Os materiais criptográficos permitem que os clientes gerem tokens com âmbito reduzido com regras de limite de acesso de credenciais variáveis de forma independente do lado do cliente durante um período definido (por exemplo, 1 hora). Esta abordagem reduz a latência e melhora a eficiência, especialmente para clientes que requerem atualizações frequentes das regras do limite de acesso às credenciais. Também é mais eficiente para aplicações que precisam de gerar muitos tokens com âmbito reduzido únicos. Esta é a abordagem recomendada porque oferece um melhor desempenho, escalabilidade e compatibilidade com funcionalidades futuras.

  • Troca de tokens do lado do servidor: os clientes pedem um novo token com âmbito reduzido ao servidor da API Security Token Service sempre que uma regra de limite de acesso às credenciais é alterada. Esta abordagem é simples, mas requer um processo de ida e volta ao servidor da API do serviço de tokens de segurança para cada pedido de token com âmbito reduzido. Esta abordagem só é recomendada para clientes que precisam de uma biblioteca de cliente que não suporte a troca de tokens do lado do cliente, devido ao ciclo completo para a API Security Token Service para cada pedido de token com âmbito reduzido.

Troca de tokens do lado do cliente

Se criar o agente de tokens e o consumidor de tokens com a seguinte linguagem, pode usar a biblioteca de autenticação da Google para trocar e atualizar tokens automaticamente através da abordagem do lado do cliente.

Java

Para Java, pode trocar e atualizar tokens automaticamente com a versão 1.32.1 ou posterior do artefacto com.google.auth:google-auth-library-cab-token-generator.

Para verificar a versão do artefacto, execute o seguinte comando Maven no diretório da aplicação:

mvn dependency:list -DincludeArtifactIds=google-auth-library-cab-token-generator

O exemplo seguinte mostra como um agente de tokens pode gerar tokens com âmbito reduzido:

import com.google.auth.credentialaccessboundary.ClientSideCredentialAccessBoundaryFactory;
import com.google.auth.oauth2.AccessToken;
import com.google.auth.oauth2.CredentialAccessBoundary;
import com.google.auth.oauth2.GoogleCredentials;
import dev.cel.common.CelValidationException;
import java.io.IOException;
import java.security.GeneralSecurityException;
  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 an instance of ClientSideCredentialAccessBoundaryFactory.
    ClientSideCredentialAccessBoundaryFactory factory =
        ClientSideCredentialAccessBoundaryFactory.newBuilder()
            .setSourceCredential(sourceCredentials)
            .build();

    // Generate the token and pass it to the Token Consumer.
    try {
      return factory.generateToken(credentialAccessBoundary);
    } catch (GeneralSecurityException | CelValidationException e) {
      throw new IOException("Error generating downscoped token", e);
    }
  }

O exemplo seguinte mostra como um consumidor de tokens pode usar um controlador de atualização para obter e atualizar automaticamente tokens com âmbito reduzido:

import com.google.auth.oauth2.AccessToken;
import com.google.auth.oauth2.OAuth2CredentialsWithRefresh;
import com.google.cloud.storage.Blob;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;
import java.io.IOException;
  public static String retrieveBlobWithDownscopedToken(
      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 DownscopedAccessTokenGenerator
                .getTokenFromBroker(bucketName, objectName);
          }
        };

    AccessToken downscopedToken = handler.refreshAccessToken();

    OAuth2CredentialsWithRefresh credentials =
        OAuth2CredentialsWithRefresh.newBuilder()
            .setAccessToken(downscopedToken)
            .setRefreshHandler(handler)
            .build();

    StorageOptions options = StorageOptions.newBuilder().setCredentials(credentials).build();
    Storage storage = options.getService();

    Blob blob = storage.get(bucketName, objectName);
    if (blob == null) {
      return null;
    }
    return new String(blob.getContent());
  }

Troca de tokens do lado do servidor

Esta secção descreve os seguintes métodos que pode usar para trocar tokens através da abordagem do lado do serviço:

Troque e atualize automaticamente a chave de acesso através da abordagem do lado do servidor

Se criar o agente de tokens e o consumidor de tokens com um dos seguintes idiomas, pode usar a biblioteca de autenticação da Google para trocar e atualizar tokens automaticamente através da abordagem de geração de tokens do lado do servidor:

Go

Para o Go, pode 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, execute o seguinte comando no diretório da aplicação:

go list -m golang.org/x/oauth2

O exemplo seguinte mostra como um agente de tokens pode gerar tokens com âmbito reduzido:


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: %w", 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: %w", 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: %w", err)
	}
	// Pass this token back to the token consumer.
	_ = tok
	return nil
}

O exemplo seguinte mostra como um consumidor de tokens pode usar um controlador de atualização para obter e atualizar automaticamente tokens com âmbito reduzido:


import (
	"context"
	"fmt"
	"io"

	"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: %w", 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: %w", 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: %w", 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: %w", 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: %w", err)
	}
	defer rc.Close()
	data, err := io.ReadAll(rc)
	if err != nil {
		return fmt.Errorf("could not read the object's contents: %w", err)
	}
	// Data now contains the contents of the requested object.
	output.Write(data)
	return nil
}

Java

Para Java, pode trocar e atualizar tokens automaticamente com a versão 1.1.0 ou posterior do artefacto com.google.auth:google-auth-library-oauth2-http.

Para verificar a versão do artefacto, execute o seguinte comando Maven no diretório da aplicação:

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

O exemplo seguinte mostra como um agente de tokens pode gerar tokens com âmbito reduzido:

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 seguinte mostra como um consumidor de tokens pode usar um controlador de atualização para obter e atualizar automaticamente tokens com âmbito reduzido:

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 o Node.js, pode 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, execute o seguinte comando no diretório da aplicação:

npm list google-auth-library

O exemplo seguinte mostra como um agente de tokens pode gerar tokens com âmbito reduzido:

// 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 seguinte mostra como um consumidor de tokens pode fornecer um controlador de atualização que obtém e atualiza automaticamente tokens com âmbito reduzido:

// 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 Python, pode trocar e atualizar tokens automaticamente com a versão 2.0.0 ou posterior do pacote google-auth.

Para verificar a versão do pacote, execute o seguinte comando no ambiente onde o pacote está instalado:

pip show google-auth

O exemplo seguinte mostra como um agente de tokens pode gerar tokens com âmbito reduzido:

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 seguinte mostra como um consumidor de tokens pode fornecer um controlador de atualização que obtém e atualiza automaticamente tokens com âmbito reduzido:

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"))

Troque e atualize a chave de acesso manualmente

Um agente de tokens pode usar a API Security Token Service para trocar um token de acesso por um token de acesso com âmbito reduzido. Em seguida, pode fornecer o token com âmbito reduzido a um consumidor de tokens.

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

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

Defina o cabeçalho Content-Type no pedido para application/x-www-form-urlencoded. Inclua os seguintes campos no corpo do pedido:

Campos
grant_type

string

Use o valor urn:ietf:params:oauth:grant-type:token-exchange.

options

string

Um limite de acesso às credenciais formatado em JSON, codificado com codificação percentual.

requested_token_type

string

Use o valor urn:ietf:params:oauth:token-type:access_token.

subject_token

string

A chave de acesso OAuth 2.0 que 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

Uma chave de acesso OAuth 2.0 com âmbito reduzido que respeita o limite de acesso das credenciais.

expires_in

number

O período de tempo até o token com âmbito reduzido expirar, em segundos.

Este campo só é incluído se o token de acesso original representar uma conta de serviço. Quando este campo não está incluído, a chave com âmbito reduzido tem o mesmo tempo de expiração que a chave 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 de credenciais formatado em JSON estiver armazenado no ficheiro ./access-boundary.json, pode usar o seguinte comando curl para trocar o token de acesso. Substitua original-token pela chave 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 é 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 tokens pede um token com âmbito reduzido, o agente de tokens responde com o token com âmbito reduzido e o número de segundos até expirar. Se o token tiver expirado, o servidor rejeita o pedido. Para atualizar o token com âmbito reduzido, o consumidor pode pedir um token com âmbito reduzido ao agente antes de o token existente expirar.

O que se segue?