Creare una credenziale di breve durata con ambito ridotto

Questa pagina spiega come utilizzare i limiti di accesso delle credenziali per creare un token di accesso OAuth 2.0 con autorizzazioni di Cloud Storage con ambito ridotto.

La procedura per creare un token con autorizzazioni con ambito ridotto include i seguenti passaggi:

  1. Concedi i ruoli IAM appropriati a un utente o a un account di servizio.
  2. Definisci un limite di accesso delle credenziali che imposta un limite superiore per le autorizzazioni disponibili per l'utente o il account di servizio.
  3. Crea un token di accesso OAuth 2.0 per l'utente o il account di servizio.
  4. Scambia il token di accesso OAuth 2.0 con un nuovo token che rispetti il limite di accesso delle credenziali.

Puoi quindi utilizzare il nuovo token di accesso OAuth 2.0 con ambito ridotto per autenticare le richieste a Cloud Storage.

Prima di iniziare

Prima di utilizzare i limiti di accesso delle credenziali, assicurati di soddisfare i seguenti requisiti:

  • Devi ridurre l'ambito delle autorizzazioni solo per Cloud Storage, non per altri Google Cloud servizi.

    Se devi ridurre l'ambito delle autorizzazioni per altri Google Cloud servizi, puoi creare più service account e concedere un insieme di ruoli diverso a ogni account di servizio.

  • Puoi utilizzare i token di accesso OAuth 2.0 per l'autenticazione. Altri tipi di credenziali di breve durata non supportano i limiti di accesso delle credenziali.

Inoltre, devi abilitare le API richieste:

  • Abilita le API IAM e Security Token Service.

    Ruoli richiesti per abilitare le API

    Per abilitare le API, devi disporre dell'autorizzazione serviceusage.services.enable. Se hai creato il progetto, probabilmente hai già questa autorizzazione tramite il ruolo Proprietario (roles/owner). In caso contrario, puoi ottenere questa autorizzazione tramite il ruolo Amministratore utilizzo servizio (roles/serviceusage.serviceUsageAdmin). Scopri come concedere i ruoli.

    Abilita le API

Concedi ruoli IAM

Un limite di accesso delle credenziali imposta un limite superiore per le autorizzazioni disponibili per una risorsa. Può sottrarre le autorizzazioni da un'entità, ma non può aggiungere autorizzazioni che l'entità non ha già.

Di conseguenza, devi anche concedere all'entità i ruoli che forniscono le autorizzazioni di cui ha bisogno, su un bucket Cloud Storage o su una risorsa di livello superiore, come il progetto.

Ad esempio, supponiamo che tu debba creare una credenziale di breve durata con ambito ridotto che consenta a un account di servizio di creare oggetti in un bucket:

  • Come minimo, devi concedere al account di servizio un ruolo che includa l'autorizzazione storage.objects.create, ad esempio il ruolo Creatore oggetti Storage (roles/storage.objectCreator). Il limite di accesso delle credenziali deve includere anche questa autorizzazione.
  • Puoi anche concedere un ruolo che includa più autorizzazioni, ad esempio il ruolo Amministratore oggetti Storage (roles/storage.objectAdmin). Il account di servizio può utilizzare solo le autorizzazioni che appaiono sia nella concessione del ruolo sia nel limite di accesso delle credenziali.

Per scoprire di più sui ruoli predefiniti per Cloud Storage, consulta Ruoli di Cloud Storage.

Definisci il limite di accesso delle credenziali

Un limite di accesso delle credenziali è un oggetto che contiene un elenco di regole relative ai limiti di accesso. Le regole sono costituite da parametri che specificano il limite superiore delle autorizzazioni disponibili per l'utente o il account di servizio. Per definire un limite di accesso delle credenziali, crea un oggetto JSON che elenca le regole relative ai limiti di accesso e i relativi parametri.

Di seguito è riportato un esempio di limite di accesso delle credenziali:

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

Sostituisci quanto segue:

  • ROLE_ID: l'ID di un ruolo predefinito o personalizzato che definisce il limite superiore per le autorizzazioni disponibili per la risorsa. Ad esempio, roles/storage.objectViewer. Per specificare più ruoli, aggiungi una nuova riga con il prefisso inRole: seguito dall'ID del ruolo. Saranno disponibili solo le autorizzazioni nei ruoli specificati.
  • BUCKET_NAME: il nome del bucket Cloud Storage a cui si applica la regola.

  • CONDITION: (facoltativo) Un'espressione di condizione che specifica gli oggetti Cloud Storage in cui sono disponibili le autorizzazioni. Ad esempio, la seguente condizione rende disponibili le autorizzazioni per gli oggetti il cui nome inizia con customer-a:

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

Per scoprire di più su come creare e personalizzare i limiti di accesso delle credenziali, consulta Componenti di un limite di accesso delle credenziali.

Per esempi di potenziali casi d'uso per i limiti di accesso delle credenziali, consulta Esempi di limiti di accesso delle credenziali.

Crea un token di accesso OAuth 2.0

Prima di creare una credenziale di breve durata con ambito ridotto, devi creare una normale credenziale di accesso OAuth 2.0. Puoi quindi scambiare la credenziale normale con una credenziale con ambito ridotto. Quando crei il token di accesso, utilizza l'ambito OAuth 2.0 https://www.googleapis.com/auth/cloud-platform.

Per creare un token di accesso per un account di servizio, puoi completare il flusso OAuth 2.0 da server a serveroppure utilizzare l'API Service Account Credentials per generare un token di accesso OAuth 2.0.

Per creare un token di accesso per un utente, consulta Ottenere token di accesso OAuth 2.0. Puoi anche utilizzare OAuth 2.0 Playground per creare un token di accesso per il tuo Account Google.

Scambia il token di accesso OAuth 2.0

Dopo aver creato un token di accesso OAuth 2.0, puoi scambiarlo con un token con ambito ridotto che rispetti il limite di accesso delle credenziali. In genere, questa procedura coinvolge un broker di token e un consumatore di token:

  • Il broker di token è responsabile della definizione del limite di accesso delle credenziali e dello scambio di un token di accesso con un token con ambito ridotto.

    Il broker di token può utilizzare una libreria di autenticazione supportata per scambiare automaticamente i token di accesso oppure può chiamare Security Token Service per scambiare i token manualmente.

  • Il consumatore di token richiede un token di accesso con ambito ridotto al broker di token, quindi utilizza il token di accesso con ambito ridotto per eseguire un'altra azione.

    Il consumatore di token può utilizzare una libreria di autenticazione supportata per aggiornare automaticamente i token di accesso prima della scadenza. In alternativa, può aggiornare i token manualmente oppure consentire la scadenza dei token senza aggiornarli.

Esistono due modi per scambiare il token di accesso con un token con ambito ridotto:

  • Scambio di token lato client (consigliato): i client ottengono materiale crittografico dal server dell'API Security Token Service. Il materiale crittografico consente ai client di generare token con ambito ridotto con regole relative ai limiti di accesso delle credenziali diverse in modo indipendente lato client per una durata impostata (ad esempio, 1 ora). Questo approccio riduce la latenza e migliora l'efficienza, soprattutto per i client che richiedono aggiornamenti frequenti delle regole relative ai limiti di accesso delle credenziali. È anche più efficiente per le applicazioni che devono generare molti token con ambito ridotto univoci. Questo è l'approccio consigliato perché offre prestazioni, scalabilità e compatibilità con le funzionalità future migliori.

  • Scambio di token lato server: i client richiedono un nuovo token con ambito ridotto da il server dell'API Security Token Service ogni volta che cambia una regola relativa ai limiti di accesso delle credenziali. Questo approccio è semplice, ma richiede un andata e ritorno al server dell'API Security Token Service per ogni richiesta di token con ambito ridotto. Questo approccio è consigliato solo per i clienti che richiedono una libreria client che non supporta lo scambio di token lato client, a causa dell'andata e ritorno all'API Security Token Service per ogni richiesta di token con ambito ridotto.

Scambio di token lato client

Se crei il broker di token e il consumatore di token con il seguente linguaggio, puoi utilizzare la libreria di autenticazione di Google per scambiare e aggiornare automaticamente i token tramite l'approccio lato client.

Java

Per Java, puoi scambiare e aggiornare automaticamente i token con la versione 1.32.1 o successive dell' com.google.auth:google-auth-library-cab-token-generator artefatto.

Per controllare la versione dell'artefatto, esegui il seguente comando Maven nella directory dell'applicazione:

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

Il seguente esempio mostra come un broker di token può generare token con ambito ridotto:

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);
    }
  }

Il seguente esempio mostra come un consumatore di token può utilizzare un gestore di aggiornamento per ottenere e aggiornare automaticamente i token con ambito ridotto:

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());
  }

Scambio di token lato server

Questa sezione descrive i seguenti metodi che puoi utilizzare per scambiare i token tramite l'approccio lato server:

Scambia e aggiorna automaticamente il token di accesso utilizzando l'approccio lato server

Se crei il broker di token e il consumatore di token con uno dei seguenti linguaggi, puoi utilizzare la libreria di autenticazione di Google per scambiare e aggiornare automaticamente i token utilizzando l'approccio di generazione di token lato server:

Go

Per Go, puoi scambiare e aggiornare automaticamente i token con la versione v0.0.0-20210819190943-2bc19b11175f o successive del golang.org/x/oauth2 pacchetto.

Per controllare la versione del pacchetto, esegui il seguente comando nella directory dell'applicazione:

go list -m golang.org/x/oauth2

Il seguente esempio mostra come un broker di token può generare token con ambito ridotto:


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
}

Il seguente esempio mostra come un consumatore di token può utilizzare un gestore di aggiornamento per ottenere e aggiornare automaticamente i token con ambito ridotto:


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

Per Java, puoi scambiare e aggiornare automaticamente i token con la versione 1.1.0 o successive dell' com.google.auth:google-auth-library-oauth2-http artefatto.

Per controllare la versione dell'artefatto, esegui il seguente comando Maven nella directory dell'applicazione:

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

Il seguente esempio mostra come un broker di token può generare token con ambito ridotto:

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;
}

Il seguente esempio mostra come un consumatore di token può utilizzare un gestore di aggiornamento per ottenere e aggiornare automaticamente i token con ambito ridotto:

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

Per Node.js, puoi scambiare e aggiornare automaticamente i token con la versione 7.9.0 o successive del google-auth-library pacchetto.

Per controllare la versione del pacchetto, esegui il seguente comando nella directory dell'applicazione:

npm list google-auth-library

Il seguente esempio mostra come un broker di token può generare token con ambito ridotto:

// 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;
}

Il seguente esempio mostra come un consumatore di token può fornire un gestore di aggiornamento che ottiene e aggiorna automaticamente i token con ambito ridotto:

// 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

Per Python, puoi scambiare e aggiornare automaticamente i token con la versione 2.0.0 o successive del google-auth pacchetto.

Per controllare la versione del pacchetto, esegui il seguente comando nell'ambiente in cui è installato il pacchetto:

pip show google-auth

Il seguente esempio mostra come un broker di token può generare token con ambito ridotto:

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)

Il seguente esempio mostra come un consumatore di token può fornire un gestore di aggiornamento che ottiene e aggiorna automaticamente i token con ambito ridotto:

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

Scambia e aggiorna manualmente il token di accesso

Un broker di token può utilizzare l'API Security Token Service per scambiare un token di accesso con un token di accesso con ambito ridotto. Può quindi fornire il token con ambito ridotto a un consumatore di token.

Per scambiare il token di accesso, utilizza il seguente metodo HTTP e URL:

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

Imposta l'intestazione Content-Type nella richiesta su application/x-www-form-urlencoded. Includi i seguenti campi nel corpo della richiesta:

Campi
grant_type

string

Utilizza il valore urn:ietf:params:oauth:grant-type:token-exchange.

options

string

Un limite di accesso delle credenziali in formato JSON, codificato con la codifica percentuale.

requested_token_type

string

Utilizza il valore urn:ietf:params:oauth:token-type:access_token.

subject_token

string

Il token di accesso OAuth 2.0 che vuoi scambiare.

subject_token_type

string

Utilizza il valore urn:ietf:params:oauth:token-type:access_token.

La risposta è un oggetto JSON che contiene i seguenti campi:

Campi
access_token

string

Un token di accesso OAuth 2.0 con ambito ridotto che rispetta il limite di accesso delle credenziali.

expires_in

number

La quantità di tempo, in secondi, prima della scadenza del token con ambito ridotto.

Questo campo è incluso solo se il token di accesso originale rappresenta un account di servizio. Quando questo campo non è incluso, il token con ambito ridotto ha lo stesso tempo di scadenza del token di accesso originale.

issued_token_type

string

Contiene il valore urn:ietf:params:oauth:token-type:access_token.

token_type

string

Contiene il valore Bearer.

Ad esempio, se un limite di accesso delle credenziali in formato JSON è archiviato nel file ./access-boundary.json, puoi utilizzare il seguente curl comando per scambiare il token di accesso. Sostituisci original-token con il token di accesso originale:

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

La risposta è simile al seguente esempio:

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

Quando un consumatore di token richiede un token con ambito ridotto, il broker di token risponde con il token con ambito ridotto e il numero di secondi prima della scadenza. Se il token è scaduto, il server rifiuta la richiesta. Per aggiornare il token con ambito ridotto, il consumatore può richiedere un token con ambito ridotto al broker prima della scadenza del token esistente.

Passaggi successivi