Restringe los permisos de Cloud Storage de una credencial

En esta página, se explica cómo usar los límites de acceso a credenciales a disminuir el alcance o restringir los permisos de administración de identidades y accesos (IAM) que puede usar una credencial de corta duración.

Puedes usar límites de acceso a las credenciales para generar tokens de acceso de OAuth 2.0 que representen a una cuenta de servicio, pero que tengan menos permisos que la cuenta de servicio. Por ejemplo, si uno de tus clientes necesita acceder a los datos de Cloud Storage que controlas, puedes hacer lo siguiente:

  1. Crea una cuenta de servicio que pueda acceder a cada bucket de Cloud Storage que te pertenezca.
  2. Genera un token de acceso de OAuth 2.0 para la cuenta de servicio.
  3. Aplica un límite de acceso a las credenciales que solo permita el acceso al bucket que contiene los datos de tu cliente.

Cómo funcionan los límites de acceso a las credenciales

A fin de disminuir el alcance de los permisos, debes definir un límite de acceso a las credenciales que especifica a qué recursos puede acceder la credencial de corta duración, así como un límite superior en los permisos disponibles para cada recurso. A continuación, puedes crear una credencial de corta duración y, luego, cambiarla por una nueva credencial que respete el límite de acceso a las credenciales.

Si necesitas otorgarles a las principales un conjunto distinto de permisos para cada sesión, puede ser más eficiente usar límites de acceso a las credenciales que crear muchas cuentas de servicio diferentes y otorgar a cada una un conjunto diferente de funciones.

Ejemplos de límites de acceso a las credenciales

En las siguientes secciones, se muestran ejemplos de límites de acceso a las credenciales para casos de uso comunes. Usa el límite de acceso a credenciales cuando intercambias un token de acceso de OAuth 2.0 por un token de alcance reducido.

Limita los permisos para un bucket

En el siguiente ejemplo, se muestra un límite de acceso a las credenciales simple. Se aplica al depósito de Cloud Storage example-bucket y establece el límite superior de los permisos que se incluyen en la función de visualizador de objetos de almacenamiento (roles/storage.objectViewer):

{
  "accessBoundary": {
    "accessBoundaryRules": [
      {
        "availablePermissions": [
          "inRole:roles/storage.objectViewer"
        ],
        "availableResource": "//storage.googleapis.com/projects/_/buckets/example-bucket"
      }
    ]
  }
}

Limita los permisos para varios depósitos

En el siguiente ejemplo, se muestra un límite de acceso a las credenciales que incluye reglas para varios depósitos:

  • El depósito de Cloud Storage example-bucket-1: para este depósito, solo están disponibles los permisos de la función de visualizador de objetos de almacenamiento (roles/storage.objectViewer).
  • El depósito de Cloud Storage example-bucket-2: para este depósito, solo están disponibles los permisos de la función de creador de objetos de almacenamiento (roles/storage.objectCreator).
{
  "accessBoundary": {
    "accessBoundaryRules": [
      {
        "availablePermissions": [
          "inRole:roles/storage.objectViewer"
        ],
        "availableResource": "//storage.googleapis.com/projects/_/buckets/example-bucket-1"
      },
      {
        "availablePermissions": [
          "inRole:roles/storage.objectCreator"
        ],
        "availableResource": "//storage.googleapis.com/projects/_/buckets/example-bucket-2"
      }
    ]
  }
}

Limita los permisos para objetos específicos

También puedes usar condiciones de IAM para especificar a qué objetos de Cloud Storage puede acceder una principal. Por ejemplo, puedes agregar una condición que permita que los permisos estén disponibles para los objetos cuyo nombre comience con customer-a:

{
  "accessBoundary": {
    "accessBoundaryRules": [
      {
        "availablePermissions": [
          "inRole:roles/storage.objectViewer"
        ],
        "availableResource": "//storage.googleapis.com/projects/_/buckets/example-bucket",
        "availabilityCondition": {
          "expression" : "resource.name.startsWith('projects/_/buckets/example-bucket/objects/customer-a')"
        }
      }
    ]
  }
}

Limita los permisos cuando se genera una lista de objetos

Cuando generas una lista de objetos en un bucket de Cloud Storage, llamas a un método en un recurso de bucket, no en un recurso de objeto. Como resultado, si se evalúa una condición para una solicitud de lista y la condición hace referencia al nombre del recurso, el nombre del recurso identifica el depósito, no un objeto dentro del depósito. Por ejemplo, cuando generas una lista de objetos en example-bucket, el nombre del recurso es projects/_/buckets/example-bucket.

Esta convención de nombres puede dar lugar a un comportamiento inesperado cuando generas listas de objetos. Por ejemplo, supongamos que deseas un límite de acceso a las credenciales que permite el acceso de lectura a los objetos de example-bucket con el prefijo customer-a/invoices/. Puede intentar usar la siguiente condición en el límite de acceso a las credenciales:

Incompleto: condición que solo verifica el nombre del recurso

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

Esta condición funciona para leer objetos, pero no para generar listas de objetos:

  • Cuando una principal intenta leer un objeto en example-bucket con el prefijo customer-a/invoices/, la condición se evalúa como true.
  • Cuando una principal intenta generar listas de objetos con ese prefijo, la condición se evalúa como false. El valor de resource.name es projects/_/buckets/example-bucket, que no comienza con projects/_/buckets/example-bucket/objects/customer-a/invoices/.

Para evitar este problema, además de usar resource.name.startsWith(), la condición puede verificar un atributo de API llamado storage.googleapis.com/objectListPrefix. Este atributo contiene el valor del parámetro prefix que se usó para filtrar la lista de objetos. Como resultado, puedes escribir una condición que haga referencia al valor del parámetro prefix.

En el siguiente ejemplo, se muestra cómo usar el atributo de la API en una condición. Permite leer y generar una lista de los objetos en example-bucket con el prefijo customer-a/invoices/:

Completo: condición que verifica el nombre del recurso y el prefijo

resource.name.startsWith('projects/_/buckets/example-bucket/objects/customer-a/invoices/')  ||
    api.getAttribute('storage.googleapis.com/objectListPrefix', '')
                     .startsWith('customer-a/invoices/')

Ahora puedes usar esta condición en un límite de acceso a las credenciales:

{
  "accessBoundary": {
    "accessBoundaryRules": [
      {
        "availablePermissions": [
          "inRole:roles/storage.objectViewer"
        ],
        "availableResource": "//storage.googleapis.com/projects/_/buckets/example-bucket",
        "availabilityCondition": {
          "expression":
            "resource.name.startsWith('projects/_/buckets/example-bucket/objects/customer-a/invoices/') || api.getAttribute('storage.googleapis.com/objectListPrefix', '').startsWith('customer-a/invoices/')"
        }
      }
    ]
  }
}

Antes de comenzar

Antes de usar los límites de acceso a las credenciales, asegúrate de cumplir con los siguientes requisitos:

  • Debes disminuir el alcance de los permisos solo para Cloud Storage, no para otros servicios de Google Cloud.

    Si necesitas disminuir el alcance de los permisos para servicios de Google Cloud adicionales, puedes crear varias cuentas de servicio y otorgar un conjunto diferente de funciones a cada una.

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

Además, debes habilitar las API requeridas:

  • Enable the IAM and Security Token Service APIs.

    Enable the APIs

Crea una credencial de corta duración de alcance reducido

Para crear un token de acceso de OAuth 2.0 con permisos reducidos, sigue estos pasos:

  1. Otorga las funciones adecuadas de IAM a una cuenta de usuario o de servicio.
  2. Define un límite de acceso a las credenciales que establezca un límite superior en los permisos que están disponibles para el usuario o la cuenta de servicio.
  3. Crea un token de acceso de 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 a las credenciales.

Luego, puedes usar el nuevo token de acceso de OAuth 2.0 de alcance reducido para autenticar las solicitudes a Cloud Storage.

Asigna funciones de IAM

Un límite de acceso a las credenciales establece un límite superior en los permisos disponibles para un recurso. Puede quitar permisos a una principal, pero no puede agregar permisos que esta aún no tiene.

Como resultado, también debes otorgarle funciones a la principal que proporcionen los permisos que necesita, ya sea en un bucket de Cloud Storage o en un recurso de nivel superior, como el proyecto.

Por ejemplo, supongamos que necesitas crear una credencial de corta duración de alcance reducido que permita que una cuenta de servicio cree objetos en un bucket:

  • Como mínimo, debes otorgar una función a la cuenta de servicio que incluya el permiso storage.objects.create, como la función de creador de objetos de Store (roles/storage.objectCreator). El límite de acceso a las credenciales también debe incluir este permiso.
  • También puedes otorgar una función que incluya más permisos, como la función de administrador de objetos de Storage (roles/storage.objectAdmin). La cuenta de servicio solo puede usar los permisos que aparecen en la asignación de funciones y en el límite de acceso a las credenciales.

Para obtener información sobre las funciones predefinidas de Cloud Storage, consulta Funciones de Cloud Storage.

Componentes de un límite de acceso a las credenciales

Un límite de acceso a las credenciales es un objeto que contiene una lista de reglas de límites de acceso. Cada regla contiene la siguiente información:

  • El recurso al que se aplica la regla
  • El límite superior de los permisos que están disponibles en ese recurso
  • Una condición que restringe aún más los permisos (opcional) Una condición incluye lo siguiente:
    • Una expresión de condición que se evalúa como true o false. Si se evalúa como true, se permite el acceso; de lo contrario, se niega el acceso
    • Un título que identifique la condición (opcional)
    • Una descripción con más información sobre la condición (opcional)

Si aplicas un límite de acceso a las credenciales a una credencial de corta duración, esta solo podrá acceder a los recursos dentro del límite de acceso a las credenciales. No hay permisos disponibles en otros recursos.

Un límite de acceso a las credenciales puede contener hasta 10 reglas de límite de acceso. Solo puedes aplicar un límite de acceso a las credenciales a cada credencial de corta duración.

Cuando se representa como un objeto JSON, un límite de acceso a las credenciales contiene los siguientes campos:

Campos
accessBoundary

object

Un contenedor para el límite de acceso a credenciales.

accessBoundary.accessBoundaryRules[]

object

Una lista de reglas de límites de acceso para aplicar a una credencial de corta duración.
accessBoundary.accessBoundaryRules[].availablePermissions[]

string

Una lista que define el límite superior de los permisos disponibles para el recurso.

Cada valor es el identificador de una función predefinida o función personalizada de IAM, con el prefijo inRole:. Por ejemplo: inRole:roles/storage.objectViewer. Solo estarán disponibles los permisos de estas funciones.

accessBoundary.accessBoundaryRules[].availableResource

string

El nombre completo del recurso del bucket de Cloud Storage al que se aplica la regla. Usa el formato //storage.googleapis.com/projects/_/buckets/bucket-name.

accessBoundary.accessBoundaryRules[].availabilityCondition

object

Opcional. Una condición que restringe la disponibilidad de permisos para objetos específicos de Cloud Storage.

Usa este campo si deseas que los permisos estén disponibles para objetos específicos, en lugar de que estén disponibles para todos los objetos en un bucket de Cloud Storage.

accessBoundary.accessBoundaryRules[].availabilityCondition.expression

string

Una expresión de condición que especifica los objetos de Cloud Storage en los que están disponibles los permisos.

Para aprender a hacer referencia a objetos específicos en una expresión de condición, consulta Atributo resource.name.

accessBoundary.accessBoundaryRules[].availabilityCondition.title

string

Opcional. Una string corta que identifica el propósito de la condición.

accessBoundary.accessBoundaryRules[].availabilityCondition.description

string

Opcional. Detalles sobre el propósito de la condición.

Para obtener ejemplos en formato JSON, consulta Ejemplos de límites de acceso a las credenciales en esta página.

Crea un token de acceso de OAuth 2.0

Antes de crear una credencial de corta duración de alcance reducido, debes crear un token de acceso de OAuth 2.0 normal. A continuación, puedes intercambiar la credencial normal por una credencial de alcance reducido. Cuando crees el token de acceso, usa el permiso de OAuth 2.0 https://www.googleapis.com/auth/cloud-platform.

Si deseas crear un token de acceso para una cuenta de servicio, puedes completar el flujo de OAuth 2.0 de servidor a servidor o puede usar la API de credenciales de la cuenta de servicio a fin de generar un token de acceso de OAuth 2.0.

Si deseas crear un token de acceso para un usuario, consulta Obtén tokens de acceso de OAuth 2.0. También puedes usar OAuth 2.0 Playground a fin de crear un token de acceso para tu propia Cuenta de Google.

Intercambia el token de acceso de OAuth 2.0

Después de crear un token de acceso de OAuth 2.0, puedes intercambiarlo por un token de alcance reducido que respete el límite de acceso a las credenciales. Este proceso suele implicar un agente de tokens y un consumidor de tokens:

Intercambia y actualiza el token de acceso de forma automática

Si creas el agente 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 de forma automática:

Go

Para Go, puedes intercambiar y actualizar tokens de forma automática con la versión v0.0.0-20210819190943-2bc19b11175f (o una posterior) del paquete golang.org/x/oauth2.

Para verificar qué versión de este paquete usas, 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 un agente de tokens puede generar tokens de alcance reducido:


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 un consumidor de tokens puede usar un controlador de actualización para obtener y actualizar automáticamente los tokens de alcance reducido:


import (
	"context"
	"fmt"
	"io"

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

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

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

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

	return remoteToken, nil
}

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

	ctx := context.Background()

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

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

Java

Para Java, puedes intercambiar y actualizar tokens de forma automática con la versión 1.1.0 (o una posterior) del artefacto com.google.auth:google-auth-library-oauth2-http.

Para verificar qué versión de este artefacto estás usando, 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 un agente de tokens puede generar tokens de alcance reducido:

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 un consumidor de tokens puede usar un controlador de actualización para obtener y actualizar automáticamente los tokens de alcance reducido:

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

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

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

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

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

Node.js

Para Node.js, puedes intercambiar y actualizar tokens de forma automática con la versión 7.9.0 (o una posterior) del paquete google-auth-library.

Para verificar qué versión de este paquete usas, ejecuta el siguiente comando en el directorio de tu aplicación:

npm list google-auth-library

En el siguiente ejemplo, se muestra cómo un agente de tokens puede generar tokens de alcance reducido:

// 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 un consumidor de tokens puede proporcionar un controlador de actualización que obtiene y actualiza de forma automática los tokens de alcance reducido:

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

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

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

Python

Para Python, puedes intercambiar y actualizar tokens de forma automática con la versión 2.0.0 (o una posterior) del paquete google-auth.

Para verificar qué versión de este paquete usas, 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 un agente de tokens puede generar tokens de alcance reducido:

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 un consumidor de tokens puede proporcionar un controlador de actualización que obtiene y actualiza de forma automática los tokens de alcance reducido:

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

Intercambia y actualiza el token de acceso de forma manual

Un agente de tokens puede usar la API de Security Token Service a fin de intercambiar un token de acceso por un token de acceso de alcance reducido. Luego, puede proporcionar el token de alcance reducido a un consumidor de tokens.

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

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

Configura el encabezado Content-Type en la solicitud a application/x-www-form-urlencoded. 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 código por ciento.

requested_token_type

string

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

string

El token de acceso de OAuth 2.0 que deseas 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 de OAuth 2.0 de alcance reducido que respeta el límite de acceso a las credenciales.

expires_in

number

Cantidad de tiempo que transcurre hasta que vence el token de alcance reducido, expresada en segundos.

Este campo solo está presente si el token de acceso original representa una cuenta de servicio. Cuando este campo no está presente, el token de alcance 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 se almacena un límite de acceso a las credenciales en formato JSON en el archivo ./access-boundary.json, puedes usar el siguiente comando curl para intercambiar el token de acceso. Reemplaza original-token con 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 de alcance reducido, el agente de tokens debe responder con el token de alcance reducido y la cantidad de segundos hasta que venza. Para actualizar el token de alcance reducido, el consumidor puede solicitar un token de alcance reducido del agente antes de que venza el token existente.

¿Qué sigue?