Herabgestufte, kurzlebige Anmeldedaten erstellen

Auf dieser Seite wird erläutert, wie Sie mit Zugriffsgrenzen für Anmeldedaten ein OAuth 2.0-Zugriffstoken mit herabgestuften Cloud Storage-Berechtigungen erstellen.

So erstellen Sie ein Token mit herabgestuften Berechtigungen:

  1. Weisen Sie einem Nutzer- oder Dienstkonto die entsprechenden IAM-Rollen zu.
  2. Definieren Sie eine Zugriffsgrenze für Anmeldedaten, die eine Obergrenze für die Berechtigungen festlegt, die dem Nutzer oder Dienstkonto zur Verfügung stehen.
  3. Erstellen Sie ein OAuth 2.0-Zugriffstoken für das Nutzer- oder Dienstkonto.
  4. Tauschen Sie das OAuth 2.0-Zugriffstoken gegen ein neues Token aus, das die Zugriffsgrenze für Anmeldedaten berücksichtigt.

Sie können dann mit dem neuen herabgestuften OAuth 2.0-Zugriffstoken Anfragen an Cloud Storage authentifizieren.

Hinweise

Achten Sie vor der Verwendung einer Zugriffsgrenze für Anmeldedaten darauf, dass Sie diese Anforderungen erfüllen:

  • Sie müssen die Berechtigungen nur für Cloud Storage herabstufen, nicht für andereGoogle Cloud -Dienste.

    Wenn Sie Berechtigungen für zusätzliche Google Cloud-Dienste einschränken müssen, können Sie mehrere Dienstkonten erstellen und jedem Dienstkonto einen anderen Rollensatz zuweisen.

  • Sie können OAuth 2.0-Zugriffstokens zur Authentifizierung verwenden. Andere Arten von kurzlebigen Anmeldedaten unterstützen keine Zugriffsgrenzen für Anmeldedaten.

Außerdem müssen Sie die erforderlichen APIs aktivieren:

  • Enable the IAM and Security Token Service APIs.

    Enable the APIs

IAM-Rollen zuweisen

Eine Zugriffsgrenze für Anmeldedaten legt eine Obergrenze für die verfügbaren Berechtigungen für eine Ressource fest. Es kann Berechtigungen von einem Hauptkonto eingrenzen, aber es kann keine Berechtigungen hinzufügen, die das Hauptkonto nicht bereits hat.

Daher müssen Sie dem Hauptkonto auch Rollen zuweisen, die die benötigten Berechtigungen bereitstellen, entweder in einem Cloud Storage-Bucket oder auf einer übergeordneten Ressource wie dem Projekt.

Nehmen wir beispielsweise an, Sie möchten herabgestufte, kurzlebige Anmeldedaten erstellen, mit denen ein Dienstkonto Objekte in einem Bucket erstellen kann:

  • Sie müssen dem Dienstkonto eine Rolle mit der Berechtigung storage.objects.create zuweisen, beispielsweise die Rolle "Storage Object-Ersteller" (roles/storage.objectCreator). Die Zugriffsgrenze für Anmeldedaten muss diese Berechtigung ebenfalls enthalten.
  • Sie können auch eine Rolle zuweisen, die mehr Berechtigungen enthält, beispielsweise die Rolle „Storage Object-Administrator“ (roles/storage.objectAdmin). Das Dienstkonto kann nur die Berechtigungen verwenden, die sowohl in der Rollenzuweisung als auch in der Zugriffsgrenze für Anmeldedaten angezeigt werden.

Informationen zu vordefinierten Rollen für Cloud Storage finden Sie unter Cloud Storage-Rollen.

Zugriffsgrenze für Anmeldedaten definieren

Eine Zugriffsgrenze für Anmeldedaten ist ein Objekt, das eine Liste von Zugriffsbegrenzungsregeln enthält. Die Regeln bestehen aus Parametern, die die Obergrenze der Berechtigungen festlegen, die dem Nutzer oder Dienstkonto zur Verfügung stehen. Wenn Sie eine Zugriffsgrenze für Anmeldedaten definieren möchten, erstellen Sie ein JSON-Objekt, in dem die Zugriffsbegrenzungsregeln und ihre Parameter aufgeführt sind.

Das folgende Beispiel zeigt eine Zugriffsgrenze für Anmeldedaten:

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

Ersetzen Sie Folgendes:

  • ROLE_ID: Die ID einer vordefinierten oder benutzerdefinierten Rolle, die die Obergrenze für die verfügbaren Berechtigungen für die Ressource definiert. Beispiel: roles/storage.objectViewer. Wenn Sie mehrere Rollen angeben möchten, fügen Sie eine neue Zeile mit dem Präfix inRole: und der Rollen-ID hinzu. Nur die Berechtigungen in den angegebenen Rollen sind verfügbar.
  • BUCKET_NAME: Der Name des Cloud Storage-Bucket, auf den sich die Regel bezieht.
  • CONDITION: Optional. Ein Bedingungsausdruck, der die Cloud Storage-Objekte angibt, in denen Berechtigungen verfügbar sind. Die folgende Bedingung macht beispielsweise Berechtigungen für Objekte verfügbar, deren Name mit customer-a beginnt:

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

Weitere Informationen zum Erstellen und Anpassen von Zugriffsgrenzen für Anmeldedaten finden Sie unter Komponenten einer Zugriffsgrenze für Anmeldedaten.

Beispiele für potenzielle Anwendungsfälle für Zugriffsgrenzen für Anmeldedaten finden Sie unter Beispiele für Zugriffsgrenzen für Anmeldedaten.

OAuth-2.0-Zugriffstoken erstellen

Bevor Sie herabgestufte, kurzlebige Anmeldedaten erstellen, müssen Sie ein normales OAuth 2.0-Zugriffstoken erstellen. Sie können dann die normalen Anmeldedaten gegen herabgestufte der Anmeldedaten austauschen. Verwenden Sie beim Erstellen des Zugriffstokens den OAuth 2.0-Bereich https://www.googleapis.com/auth/cloud-platform.

Zum Erstellen eines Zugriffstokens für ein Dienstkonto schließen Sie den OAuth 2.0-Ablauf von Server zu Server ab. Sie können auch die Service Account Credentials API zum Erstellen eines OAuth 2.0-Zugriffstokens verwenden.

Weitere Informationen zum Erstellen eines Zugriffstokens für einen Nutzer finden Sie unter OAuth 2.0-Zugriffstokens abrufen. Sie können auch mit OAuth 2.0 Playground ein Zugriffstoken für Ihr eigenes Google-Konto erstellen.

OAuth-2.0-Zugriffstoken austauschen

Nachdem Sie ein OAuth-2.0-Zugriffstoken erstellt haben, können Sie das Zugriffstoken gegen ein neues Token austauschen, das die Zugriffsgrenze für Anmeldedaten berücksichtigt. Dieser Vorgang umfasst in der Regel einen Token-Broker und einen Token-Nutzer:

  • Der Token-Broker ist für die Definition der Zugriffsgrenze für Anmeldedaten und den Austausch eines Zugriffstokens gegen ein herabgestuftes Token verantwortlich.

    Der Token-Broker kann eine unterstützte Authentifizierungsbibliothek verwenden, um Zugriffstokens automatisch auszutauschen. Er kann auch den Security Token Service aufrufen, um Tokens manuell auszutauschen.

  • Der Token-Nutzer fordert ein herabgestuftes Zugriffstoken vom Token-Broker an und verwendet dann das herabgestufte Zugriffstoken, um eine weitere Aktion auszuführen.

    Der Token-Nutzer kann eine unterstützte Authentifizierungsbibliothek verwenden, um Zugriffstokens automatisch zu aktualisieren, bevor sie ablaufen. Alternativ können er Tokens manuell aktualisieren oder Tokens ablaufen lassen, ohne sie zu aktualisieren.

Es gibt zwei Möglichkeiten, das Zugriffstoken gegen ein herabgestuftes Token einzutauschen:

  • Clientseitiger Tokenaustausch (empfohlen): Clients rufen kryptografische Materialien vom Security Token Service API-Server ab. Mit den kryptografischen Materialien können Clients für einen bestimmten Zeitraum (z. B. 1 Stunde) unabhängig auf der Clientseite herabgestufte Tokens mit unterschiedlichen Regeln für die Zugriffsgrenze für Anmeldedaten generieren. Dieser Ansatz verringert die Latenz und verbessert die Effizienz, insbesondere für Clients, die häufige Aktualisierungen der Regeln für die Credential Access Boundary erfordern. Außerdem ist es effizienter für Anwendungen, die viele eindeutige Tokens mit eingeschränktem Umfang generieren müssen. Dies ist der empfohlene Ansatz, da er eine bessere Leistung, Skalierbarkeit und Kompatibilität mit zukünftigen Funktionen bietet.

  • Serverseitiger Token-Austausch: Clients fordern immer dann ein neues herabgestuftes Token vom Security Token Service API-Server an, wenn sich eine Regel für die Credential Access Boundary ändert. Dieser Ansatz ist einfach, erfordert jedoch für jede Anfrage für ein eingeschränktes Token einen Roundtrip zum Security Token Service-API-Server. Dieser Ansatz wird nur für Kunden empfohlen, die eine Clientbibliothek benötigen, die keinen clientseitigen Tausch von Tokens unterstützt, da für jede Anfrage für ein Token mit eingeschränktem Umfang ein Roundtrip zur Security Token Service API erforderlich ist.

Clientseitiger Tokenaustausch

Wenn Sie den Token-Broker und den Token-Nutzer mit der folgenden Sprache erstellen, können Sie Tokens mithilfe der Authentifizierungsbibliothek von Google automatisch über den clientseitigen Ansatz austauschen und aktualisieren.

Java

Bei Java können Sie Tokens automatisch mit Version 1.32.1 oder höher des com.google.auth:google-auth-library-cab-token-generator-Artefakts austauschen und aktualisieren.

Führen Sie den folgenden Maven-Befehl in Ihrem Anwendungsverzeichnis aus, um die Version des Artefakts zu prüfen:

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

Das folgende Beispiel zeigt, wie ein Token-Broker herabgestufte Tokens generieren kann:

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

Das folgende Beispiel zeigt, wie ein Token-Nutzer einen Aktualisierungs-Handler verwenden kann, um herabgestufte Tokens automatisch abzurufen und zu aktualisieren:

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

Serverseitiger Tokenaustausch

In diesem Abschnitt werden die folgenden Methoden beschrieben, mit denen Sie Tokens über den serverseitigen Ansatz austauschen können:

Zugriffstoken automatisch austauschen und aktualisieren (serverseitig)

Wenn Sie den Token-Broker und den Token-Nutzer mit einer der folgenden Sprachen erstellen, können Sie Tokens mithilfe der Authentifizierungsbibliothek von Google automatisch austauschen und aktualisieren:

Go

Bei Go können Sie Tokens mit Version v0.0.0-20210819190943-2bc19b11175f oder höher automatisch dem Versionspaket golang.org/x/oauth2 austauschen und aktualisieren.

Führen Sie den folgenden Befehl in Ihrem Anwendungsverzeichnis aus, um die Version Ihres Pakets zu prüfen:

go list -m golang.org/x/oauth2

Das folgende Beispiel zeigt, wie ein Token-Broker herabgestufte Tokens generieren kann:


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
}

Das folgende Beispiel zeigt, wie ein Token-Nutzer einen Aktualisierungs-Handler verwenden kann, um herabgestufte Tokens automatisch abzurufen und zu aktualisieren:


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

Bei Java können Sie Tokens automatisch mit Version 1.1.0 oder höher des com.google.auth:google-auth-library-oauth2-http-Artefakts austauschen und aktualisieren.

Führen Sie den folgenden Maven-Befehl in Ihrem Anwendungsverzeichnis aus, um die Version des Artefakts zu prüfen:

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

Das folgende Beispiel zeigt, wie ein Token-Broker herabgestufte Tokens generieren kann:

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

Das folgende Beispiel zeigt, wie ein Token-Nutzer einen Aktualisierungs-Handler verwenden kann, um herabgestufte Tokens automatisch abzurufen und zu aktualisieren:

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

Bei Node.js können Sie Tokens mit Version 7.9.0 oder höher des google-auth-library-Pakets automatisch austauschen und aktualisieren.

Führen Sie den folgenden Befehl in Ihrem Anwendungsverzeichnis aus, um die Version Ihres Pakets zu prüfen:

npm list google-auth-library

Das folgende Beispiel zeigt, wie ein Token-Broker herabgestufte Tokens generieren kann:

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

Das folgende Beispiel zeigt, wie ein Token-Nutzer einen Aktualisierungs-Handler bereitstellen kann, der herabgestufte Tokens automatisch abruft und aktualisiert:

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

Bei Python können Sie Tokens mit Version 2.0.0 oder höher des google-auth-Pakets automatisch austauschen und aktualisieren.

Führen Sie den folgenden Befehl in der Umgebung aus, in der das Paket installiert ist, um die Paketversion zu prüfen:

pip show google-auth

Das folgende Beispiel zeigt, wie ein Token-Broker herabgestufte Tokens generieren kann:

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)

Das folgende Beispiel zeigt, wie ein Token-Nutzer einen Aktualisierungs-Handler bereitstellen kann, der herabgestufte Tokens automatisch abruft und aktualisiert:

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

Zugriffstoken manuell austauschen und aktualisieren

Ein Token-Broker kann die Security Token Service API verwenden, um ein Zugriffstoken gegen ein herabgestuftes Zugriffstoken auszutauschen. Es kann dann das herabgestufte Token einem Token-Nutzer bereitstellen.

Tauschen Sie das Zugriffstoken mit dieser HTTP-Methode und URL aus:

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

Setzen Sie den Header Content-Type in der Anfrage auf application/x-www-form-urlencoded. Fügen Sie im Anfragetext diese Felder ein:

Felder
grant_type

string

Verwenden Sie den Wert urn:ietf:params:oauth:grant-type:token-exchange.

options

string

Eine Zugriffsgrenze für Anmeldedaten im JSON-Format, die mit Prozentcodierung codiert ist.

requested_token_type

string

Verwenden Sie den Wert urn:ietf:params:oauth:token-type:access_token.

subject_token

string

Das OAuth 2.0-Zugriffstoken, das Sie austauschen möchten.

subject_token_type

string

Verwenden Sie den Wert urn:ietf:params:oauth:token-type:access_token.

Die Antwort ist ein JSON-Objekt mit diesen Feldern:

Felder
access_token

string

Ein herabgestuftes OAuth 2.0-Zugriffstoken, das die Zugriffsgrenze für Anmeldedaten berücksichtigt.

expires_in

number

Die Zeit in Sekunden, bis das herabgestufte Zugriffstoken abläuft.

Dieses Feld ist nur enthalten, wenn das ursprüngliche Zugriffstoken ein Dienstkonto darstellt. Wenn dieses Feld nicht vorhanden ist, läuft das herabgestufte Zugriffstoken genauso lange ab wie das ursprüngliche Zugriffstoken.

issued_token_type

string

Enthält den Wert urn:ietf:params:oauth:token-type:access_token.

token_type

string

Enthält den Wert Bearer.

Wenn beispielsweise eine Zugriffsgrenze für Anmeldedaten im JSON-Format in der Datei ./access-boundary.json gespeichert ist, können Sie mit diesem curl-Befehl das Zugriffstoken austauschen. Ersetzen Sie original-token durch das ursprüngliche Zugriffstoken:

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

Die Antwort ähnelt diesem Beispiel:

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

Wenn ein Token-Nutzer ein herabgestuftes Token anfordert, antwortet der Token-Broker sowohl mit dem herabgestuften Token als auch mit der Anzahl der Sekunden bis zum Ablauf. Wenn das Token abgelaufen ist, lehnt der Server die Anfrage ab. Zum Aktualisieren des herabgestuften Tokens kann der Nutzer ein herabgestuftes Token vom Broker anfordern, bevor das vorhandene Token abläuft.

Nächste Schritte