Crear una credencial de duración reducida con permisos limitados

En esta página se explica cómo usar los límites de acceso de las credenciales para crear un token de acceso de OAuth 2.0 con permisos de Cloud Storage reducidos.

El proceso para crear un token con permisos de ámbito reducido incluye los siguientes pasos:

  1. Asigna los roles de IAM adecuados a un usuario o una cuenta de servicio.
  2. Define un límite de acceso a credenciales que establece un límite superior para los permisos disponibles para el usuario o la cuenta de servicio.
  3. Crea un token de acceso OAuth 2.0 para el usuario o la cuenta de servicio.
  4. Intercambia el token de acceso de OAuth 2.0 por un token nuevo que respete el límite de acceso de las credenciales.

Después, puedes usar el nuevo token de acceso de OAuth 2.0 con permisos limitados para autenticar las solicitudes a Cloud Storage.

Antes de empezar

Antes de usar los límites de acceso a credenciales, asegúrate de que cumples los siguientes requisitos:

  • Solo tienes que reducir los permisos de Cloud Storage, no de otros servicios deGoogle Cloud .

    Si necesitas reducir el alcance de los permisos de otros servicios, puedes crear varias cuentas de servicio y asignar un conjunto de roles diferente a cada una. Google Cloud

  • Puedes usar tokens de acceso OAuth 2.0 para la autenticación. Otros tipos de credenciales de corta duración no admiten límites de acceso a credenciales.

Además, debes habilitar las APIs necesarias:

  • Enable the IAM and Security Token Service APIs.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the APIs

Otorgar roles de gestión de identidades y accesos

Un límite de acceso de credenciales establece un límite superior para los permisos disponibles de un recurso. Puede restar permisos a un principal, pero no puede añadir permisos que el principal no tenga ya.

Por lo tanto, también debes asignar roles al principal que le proporcionen los permisos que necesita, ya sea en un segmento de Cloud Storage o en un recurso de nivel superior, como el proyecto.

Por ejemplo, supongamos que necesitas crear una credencial de duración reducida con permisos limitados que permita a una cuenta de servicio crear objetos en un contenedor:

  • Como mínimo, debes asignar a la cuenta de servicio un rol que incluya el permiso storage.objects.create, como el rol Creador de objetos de almacenamiento (roles/storage.objectCreator). El límite de acceso a las credenciales también debe incluir este permiso.
  • También puedes conceder un rol que incluya más permisos, como el rol Administrador de objetos de Storage (roles/storage.objectAdmin). La cuenta de servicio solo puede usar los permisos que aparecen tanto en la concesión de roles como en el límite de acceso de credenciales.

Para obtener información sobre los roles predefinidos de Cloud Storage, consulta Roles de Cloud Storage.

Definir el límite de acceso a credenciales

Un límite de acceso de credenciales es un objeto que contiene una lista de reglas de límite de acceso. Las reglas se componen de parámetros que especifican el límite superior de los permisos disponibles para el usuario o la cuenta de servicio. Para definir un límite de acceso de credenciales, crea un objeto JSON que incluya las reglas de límite de acceso y sus parámetros.

A continuación, se muestra un ejemplo de límite de acceso a credenciales:

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

Haz los cambios siguientes:

  • ROLE_ID: el ID de un rol predefinido o personalizado que define el límite superior de los permisos disponibles para el recurso. Por ejemplo, roles/storage.objectViewer. Para especificar varios roles, añade una línea nueva con el prefijo inRole: seguido del ID del rol. Solo estarán disponibles los permisos de los roles especificados.
  • BUCKET_NAME: nombre del segmento de Cloud Storage al que se aplica la regla.
  • CONDITION: opcional. Una expresión de condición que especifica los objetos de Cloud Storage en los que están disponibles los permisos. Por ejemplo, la siguiente condición hace que los permisos estén disponibles para los objetos cuyo nombre empiece por customer-a:

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

Para obtener más información sobre cómo crear y personalizar límites de acceso a credenciales, consulta Componentes de un límite de acceso a credenciales.

Para ver ejemplos de posibles casos prácticos de límites de acceso a credenciales, consulta Ejemplos de límites de acceso a credenciales.

Crear un token de acceso OAuth 2.0

Antes de crear una credencial de duración reducida con permisos limitados, debes crear un token de acceso de OAuth 2.0 normal. Después, puedes cambiar la credencial normal por una credencial con permisos limitados. Cuando crees el token de acceso, usa el ámbito de OAuth 2.0 https://www.googleapis.com/auth/cloud-platform.

Para crear un token de acceso para una cuenta de servicio, puedes completar el flujo de OAuth 2.0 de servidor a servidor o usar la API Service Account Credentials para generar un token de acceso de OAuth 2.0.

Para crear un token de acceso para un usuario, consulta Obtener tokens de acceso de OAuth 2.0. También puedes usar OAuth 2.0 Playground para crear un token de acceso para tu cuenta de Google.

Intercambiar el token de acceso de OAuth 2.0

Después de crear un token de acceso OAuth 2.0, puedes cambiarlo por un token con permisos limitados que respete el límite de acceso a las credenciales. Este proceso suele incluir un broker de tokens y un consumidor de tokens:

  • El broker de tokens se encarga de definir el límite de acceso a credenciales y de intercambiar un token de acceso por un token con permisos restringidos.

    El intermediario de tokens puede usar una biblioteca de autenticación compatible para intercambiar tokens de acceso automáticamente o puede llamar al servicio de tokens de seguridad para intercambiar tokens manualmente.

  • El consumidor de tokens solicita un token de acceso con permisos limitados al intermediario de tokens y, a continuación, utiliza el token de acceso con permisos limitados para realizar otra acción.

    El consumidor del token puede usar una biblioteca de autenticación compatible para actualizar automáticamente los tokens de acceso antes de que caduquen. También puede actualizar los tokens manualmente o permitir que caduquen sin actualizarlos.

Hay dos formas de intercambiar el token de acceso por un token con permisos limitados:

  • Intercambio de tokens del lado del cliente (opción recomendada): los clientes obtienen materiales criptográficos del servidor de la API del servicio de tokens de seguridad. Los materiales criptográficos permiten a los clientes generar tokens con ámbito reducido con diferentes reglas de límite de acceso a credenciales de forma independiente en el lado del cliente durante un periodo determinado (por ejemplo, 1 hora). Este enfoque reduce la latencia y mejora la eficiencia, sobre todo en los clientes que requieren actualizaciones frecuentes de las reglas de límites de acceso de credenciales. También es más eficiente para las aplicaciones que necesitan generar muchos tokens únicos con permisos limitados. Este es el enfoque recomendado porque ofrece un mejor rendimiento, escalabilidad y compatibilidad con futuras funciones.

  • Intercambio de tokens del lado del servidor: los clientes solicitan un nuevo token con permisos limitados al servidor de la API Security Token Service cada vez que cambia una regla de Credential Access Boundary. Este método es sencillo, pero requiere un viaje de ida y vuelta al servidor de la API del servicio de tokens de seguridad para cada solicitud de token con permisos limitados. Este enfoque solo se recomienda a los clientes que necesiten una biblioteca de cliente que no admita el intercambio de tokens del lado del cliente, debido al viaje de ida y vuelta a la API del servicio de tokens de seguridad para cada solicitud de token con permisos limitados.

Intercambio de tokens del lado del cliente

Si creas el intermediario de tokens y el consumidor de tokens con el siguiente lenguaje, puedes usar la biblioteca de autenticación de Google para intercambiar y actualizar tokens automáticamente mediante el enfoque del lado del cliente.

Java

En Java, puedes intercambiar y actualizar tokens automáticamente con la versión 1.32.1 o posterior del artefacto com.google.auth:google-auth-library-cab-token-generator.

Para comprobar la versión del artefacto, ejecuta el siguiente comando de Maven en el directorio de tu aplicación:

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

En el siguiente ejemplo se muestra cómo puede generar tokens con ámbito reducido un intermediario de tokens:

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

En el siguiente ejemplo se muestra cómo puede usar un controlador de actualización un consumidor de tokens para obtener y actualizar automáticamente tokens con permisos limitados:

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

Intercambio de tokens del lado del servidor

En esta sección se describen los siguientes métodos que puedes usar para intercambiar tokens mediante el enfoque del lado del servicio:

Intercambiar y actualizar el token de acceso automáticamente mediante el enfoque del lado del servidor

Si creas el intermediario de tokens y el consumidor de tokens con uno de los siguientes lenguajes, puedes usar la biblioteca de autenticación de Google para intercambiar y actualizar tokens automáticamente mediante el método de generación de tokens del lado del servidor:

Go

En Go, puedes intercambiar y actualizar tokens automáticamente con la versión v0.0.0-20210819190943-2bc19b11175f o posterior del paquete golang.org/x/oauth2.

Para comprobar la versión del paquete, ejecuta el siguiente comando en el directorio de tu aplicación:

go list -m golang.org/x/oauth2

En el siguiente ejemplo se muestra cómo puede generar tokens con ámbito reducido un intermediario de tokens:


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
}

En el siguiente ejemplo se muestra cómo puede usar un controlador de actualización un consumidor de tokens para obtener y actualizar automáticamente tokens con permisos limitados:


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

En Java, puedes intercambiar y actualizar tokens automáticamente con la versión 1.1.0 o posterior del artefacto com.google.auth:google-auth-library-oauth2-http.

Para comprobar la versión del artefacto, ejecuta el siguiente comando de Maven en el directorio de tu aplicación:

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

En el siguiente ejemplo se muestra cómo puede generar tokens con ámbito reducido un intermediario de tokens:

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

En el siguiente ejemplo se muestra cómo puede usar un controlador de actualización un consumidor de tokens para obtener y actualizar automáticamente tokens con permisos limitados:

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

En Node.js, puedes intercambiar y actualizar tokens automáticamente con la versión 7.9.0 o posterior del paquete google-auth-library.

Para comprobar la versión del paquete, ejecuta el siguiente comando en el directorio de tu aplicación:

npm list google-auth-library

En el siguiente ejemplo se muestra cómo puede generar tokens con ámbito reducido un intermediario de tokens:

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

En el siguiente ejemplo se muestra cómo puede proporcionar un controlador de actualización un consumidor de tokens para obtener y actualizar automáticamente tokens con permisos limitados:

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

En Python, puedes intercambiar y actualizar tokens automáticamente con la versión 2.0.0 o posterior del paquete google-auth.

Para comprobar la versión del paquete, ejecuta el siguiente comando en el entorno en el que está instalado el paquete:

pip show google-auth

En el siguiente ejemplo se muestra cómo puede generar tokens con ámbito reducido un intermediario de tokens:

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)

En el siguiente ejemplo se muestra cómo puede proporcionar un controlador de actualización un consumidor de tokens para obtener y actualizar automáticamente tokens con permisos limitados:

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

Intercambiar y actualizar el token de acceso manualmente

Un intermediario de tokens puede usar la API Security Token Service para intercambiar un token de acceso por un token de acceso con permisos limitados. Después, puede proporcionar el token con permisos limitados a un consumidor de tokens.

Para intercambiar el token de acceso, usa el siguiente método HTTP y la siguiente URL:

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

Asigna el valor application/x-www-form-urlencoded al encabezado Content-Type de la solicitud. Incluye los siguientes campos en el cuerpo de la solicitud:

Campos
grant_type

string

Usa el valor urn:ietf:params:oauth:grant-type:token-exchange.

options

string

Un límite de acceso a credenciales con formato JSON, codificado con codificación porcentaje.

requested_token_type

string

Usa el valor urn:ietf:params:oauth:token-type:access_token.

subject_token

string

El token de acceso OAuth 2.0 que quieres intercambiar.

subject_token_type

string

Usa el valor urn:ietf:params:oauth:token-type:access_token.

La respuesta es un objeto JSON que contiene los siguientes campos:

Campos
access_token

string

Un token de acceso OAuth 2.0 con permisos limitados que respeta el límite de acceso de credenciales.

expires_in

number

Tiempo que falta para que caduque el token con ámbito reducido, en segundos.

Este campo solo se incluye si el token de acceso original representa una cuenta de servicio. Si no se incluye este campo, el token con ámbito reducido tiene el mismo tiempo de vencimiento que el token de acceso original.

issued_token_type

string

Contiene el valor urn:ietf:params:oauth:token-type:access_token.

token_type

string

Contiene el valor Bearer.

Por ejemplo, si un límite de acceso de credenciales con formato JSON se almacena en el archivo ./access-boundary.json, puedes usar el siguiente comando curl para intercambiar el token de acceso. Sustituye original-token por el token de acceso 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)"

La respuesta es similar al siguiente ejemplo:

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

Cuando un consumidor de tokens solicita un token con permisos limitados, el intermediario de tokens responde con el token con permisos limitados y el número de segundos que faltan para que caduque. Si el token ha caducado, el servidor rechaza la solicitud. Para actualizar el token con permisos limitados, el consumidor puede solicitarlo al intermediario antes de que caduque el token actual.

Siguientes pasos