Accedere a una versione del secret

In questa pagina viene descritto come accedere a una versione del secret. L'accesso a una versione del secret restituisce i contenuti del secret e metadati aggiuntivi sulla versione del secret. Per accedere a una versione del secret utilizzando il Google Cloud CLI o l'API Secret Manager, devi specificare l'ID versione o l'alias, se assegnato. Puoi anche accedere all'ultima versione di un secret specificando latest come ID versione.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per accedere a una versione del secret, chiedi all'amministratore di concederti il ruolo IAM Secret Manager Secret Accessor (roles/secretmanager.secretAccessor) su un secret. Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Accedere a una versione del secret

Per accedere a un secret, utilizza uno dei seguenti metodi:

Console

  1. Nella Google Cloud console, vai alla pagina Secret Manager.

    Vai a Secret Manager

  2. Nella pagina Secret Manager, fai clic su un secret per accedere alle relative versioni.

  3. Nella pagina dei dettagli del secret, nella scheda Versioni, seleziona la versione del secret a cui vuoi accedere.

  4. Fai clic sul menu Azioni associato alla versione del secret, quindi fai clic su Visualizza valore secret.

  5. Viene visualizzata una finestra di dialogo che mostra il valore della versione del secret. Fai clic su Fine per uscire dalla finestra di dialogo.

gcloud

Accedere a una versione del secret

Prima di utilizzare i dati dei comandi riportati di seguito, effettua le seguenti sostituzioni:

  • VERSION_ID: il nome della risorsa della versione del secret
  • SECRET_ID: l'ID del secret

Esegui il comando seguente:

Linux, macOS o Cloud Shell

gcloud secrets versions access VERSION_ID --secret=SECRET_ID

Windows (PowerShell)

gcloud secrets versions access VERSION_ID --secret=SECRET_ID

Windows (cmd.exe)

gcloud secrets versions access VERSION_ID --secret=SECRET_ID

Accedere a una versione del secret binario

Per scrivere byte non elaborati in un file, utilizza il flag --out-file:

Prima di utilizzare i dati dei comandi riportati di seguito, effettua le seguenti sostituzioni:

  • VERSION_ID: l'ID della versione del secret
  • SECRET_ID: l'ID del secret
  • PATH_TO_SECRET: il percorso completo (incluso il nome del file) in cui vuoi salvare il valore del secret recuperato

Esegui il comando seguente:

Linux, macOS o Cloud Shell

gcloud secrets versions access VERSION_ID --secret=SECRET_ID --out-file="PATH_TO_SECRET"

Windows (PowerShell)

gcloud secrets versions access VERSION_ID --secret=SECRET_ID --out-file="PATH_TO_SECRET"

Windows (cmd.exe)

gcloud secrets versions access VERSION_ID --secret=SECRET_ID --out-file="PATH_TO_SECRET"

Recuperare i byte non elaborati

Per recuperare i byte non elaborati, fai in modo che Cloud SDK stampi la risposta come codificata in base64 e la decodifichi:

Prima di utilizzare i dati dei comandi riportati di seguito, effettua le seguenti sostituzioni:

  • VERSION_ID: l'ID della versione del secret
  • SECRET_ID: l'ID del secret

Esegui il comando seguente:

Linux, macOS o Cloud Shell

gcloud secrets versions access VERSION_ID --secret=SECRET_ID --format='get(payload.data)' | tr '_-' '/+' | base64 -d

Windows (PowerShell)

gcloud secrets versions access VERSION_ID --secret=SECRET_ID --format='get(payload.data)' | tr '_-' '/+' | base64 -d

Windows (cmd.exe)

gcloud secrets versions access VERSION_ID --secret=SECRET_ID --format='get(payload.data)' | tr '_-' '/+' | base64 -d

La risposta contiene la versione del secret.

REST

Accedere a una versione del secret

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

  • PROJECT_ID: l' Google Cloud ID progetto
  • SECRET_ID: l'ID del secret
  • VERSION_ID: l'ID della versione del secret

Metodo HTTP e URL:

GET https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID/versions/VERSION_ID:access

Corpo JSON della richiesta:

{}

Per inviare la richiesta, scegli una di queste opzioni:

curl

Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente:

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID/versions/VERSION_ID:access"

PowerShell

Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method GET `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID/versions/VERSION_ID:access" | Select-Object -Expand Content

Dovresti ricevere una risposta JSON simile alla seguente:

{
  "name": "projects/PROJECT_ID/locations/LOCATION/secrets/SECRET_ID/versions/VERSION_ID",
  "payload": {
    "data": "c2VDcjN0Cg==",
    "dataCrc32c": "3131222104"
  }
}

Estrarre il secret utilizzando lo strumento jq

La risposta payload.data è il contenuto della versione del secret codificato in base64. Il comando seguente è un esempio di estrazione del secret utilizzando lo strumento jq.

    $ curl "https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID/versions/VERSION_ID:access" \
       --request "GET" \
       --header "authorization: Bearer $(gcloud auth print-access-token)" \
       --header "content-type: application/json" \
       | jq -r ".payload.data" | base64 --decode
  

C#

Per eseguire questo codice, devi innanzitutto configurare un ambiente di sviluppo C# e installare l'SDK C# di Secret Manager. Su Compute Engine o GKE, devi eseguire l'autenticazione con l'ambito cloud-platform.


using System;
using Google.Cloud.SecretManager.V1;

public class AccessSecretVersionSample
{
    public String AccessSecretVersion(
      string projectId = "my-project", string secretId = "my-secret", string secretVersionId = "123")
    {
        // Create the client.
        SecretManagerServiceClient client = SecretManagerServiceClient.Create();

        // Build the resource name.
        SecretVersionName secretVersionName = new SecretVersionName(projectId, secretId, secretVersionId);

        // Call the API.
        AccessSecretVersionResponse result = client.AccessSecretVersion(secretVersionName);

        // Convert the payload to a string. Payloads are bytes by default.
        String payload = result.Payload.Data.ToStringUtf8();
        return payload;
    }
}

Go

Per eseguire questo codice, devi innanzitutto configurare un ambiente di sviluppo Go e installare l'SDK Go di Secret Manager. Su Compute Engine o GKE, devi eseguire l'autenticazione con l'ambito cloud-platform.

import (
	"context"
	"fmt"
	"hash/crc32"
	"io"

	secretmanager "cloud.google.com/go/secretmanager/apiv1"
	"cloud.google.com/go/secretmanager/apiv1/secretmanagerpb"
)

// accessSecretVersion accesses the payload for the given secret version if one
// exists. The version can be a version number as a string (e.g. "5") or an
// alias (e.g. "latest").
func accessSecretVersion(w io.Writer, name string) error {
	// name := "projects/my-project/secrets/my-secret/versions/5"
	// name := "projects/my-project/secrets/my-secret/versions/latest"

	// Create the client.
	ctx := context.Background()
	client, err := secretmanager.NewClient(ctx)
	if err != nil {
		return fmt.Errorf("failed to create secretmanager client: %w", err)
	}
	defer client.Close()

	// Build the request.
	req := &secretmanagerpb.AccessSecretVersionRequest{
		Name: name,
	}

	// Call the API.
	result, err := client.AccessSecretVersion(ctx, req)
	if err != nil {
		return fmt.Errorf("failed to access secret version: %w", err)
	}

	// Verify the data checksum.
	crc32c := crc32.MakeTable(crc32.Castagnoli)
	checksum := int64(crc32.Checksum(result.Payload.Data, crc32c))
	if checksum != *result.Payload.DataCrc32C {
		return fmt.Errorf("Data corruption detected.")
	}

	// WARNING: Do not print the secret in a production environment - this snippet
	// is showing how to access the secret material.
	fmt.Fprintf(w, "Plaintext: %s\n", string(result.Payload.Data))
	return nil
}

Java

Per eseguire questo codice, devi innanzitutto configurare un ambiente di sviluppo Java e installare l'SDK Java di Secret Manager. Su Compute Engine o GKE, devi eseguire l'autenticazione con l'ambito cloud-platform.

import com.google.cloud.secretmanager.v1.AccessSecretVersionResponse;
import com.google.cloud.secretmanager.v1.SecretManagerServiceClient;
import com.google.cloud.secretmanager.v1.SecretVersionName;
import java.io.IOException;
import java.util.zip.CRC32C;
import java.util.zip.Checksum;

public class AccessSecretVersion {

  public static void accessSecretVersion() throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "your-project-id";
    String secretId = "your-secret-id";
    String versionId = "your-version-id";
    accessSecretVersion(projectId, secretId, versionId);
  }

  // Access the payload for the given secret version if one exists. The version
  // can be a version number as a string (e.g. "5") or an alias (e.g. "latest").
  public static void accessSecretVersion(String projectId, String secretId, String versionId)
      throws IOException {
    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests. After completing all of your requests, call
    // the "close" method on the client to safely clean up any remaining background resources.
    try (SecretManagerServiceClient client = SecretManagerServiceClient.create()) {
      SecretVersionName secretVersionName = SecretVersionName.of(projectId, secretId, versionId);

      // Access the secret version.
      AccessSecretVersionResponse response = client.accessSecretVersion(secretVersionName);

      // Verify checksum. The used library is available in Java 9+.
      // If using Java 8, you may use the following:
      // https://github.com/google/guava/blob/e62d6a0456420d295089a9c319b7593a3eae4a83/guava/src/com/google/common/hash/Hashing.java#L395
      byte[] data = response.getPayload().getData().toByteArray();
      Checksum checksum = new CRC32C();
      checksum.update(data, 0, data.length);
      if (response.getPayload().getDataCrc32C() != checksum.getValue()) {
        System.out.printf("Data corruption detected.");
        return;
      }

      // Print the secret payload.
      //
      // WARNING: Do not print the secret in a production environment - this
      // snippet is showing how to access the secret material.
      String payload = response.getPayload().getData().toStringUtf8();
      System.out.printf("Plaintext: %s\n", payload);
    }
  }
}

Node.js

Per eseguire questo codice, devi innanzitutto configurare un ambiente di sviluppo Node.js e installare l'SDK Node.js di Secret Manager. Su Compute Engine o GKE, devi eseguire l'autenticazione con l'ambito cloud-platform.

/**
 * TODO(developer): Uncomment these variables before running the sample.
 */
// const name = 'projects/my-project/secrets/my-secret/versions/5';
// const name = 'projects/my-project/secrets/my-secret/versions/latest';

// Imports the Secret Manager library
const {SecretManagerServiceClient} = require('@google-cloud/secret-manager');

// Instantiates a client
const client = new SecretManagerServiceClient();

async function accessSecretVersion() {
  const [version] = await client.accessSecretVersion({
    name: name,
  });

  // Extract the payload as a string.
  const payload = version.payload.data.toString();

  // WARNING: Do not print the secret in a production environment - this
  // snippet is showing how to access the secret material.
  console.info(`Payload: ${payload}`);
}

accessSecretVersion();

PHP

Per eseguire questo codice, devi prima scoprire come utilizzare PHP su Google Cloud e installare l'SDK PHP di Secret Manager. Su Compute Engine o GKE, devi eseguire l'autenticazione con l'ambito cloud-platform.

// Import the Secret Manager client library.
use Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient;
use Google\Cloud\SecretManager\V1\AccessSecretVersionRequest;

/**
 * @param string $projectId Your Google Cloud Project ID (e.g. 'my-project')
 * @param string $secretId  Your secret ID (e.g. 'my-secret')
 * @param string $versionId Your version ID (e.g. 'latest' or '5');
 */
function access_secret_version(string $projectId, string $secretId, string $versionId): void
{
    // Create the Secret Manager client.
    $client = new SecretManagerServiceClient();

    // Build the resource name of the secret version.
    $name = $client->secretVersionName($projectId, $secretId, $versionId);

    // Build the request.
    $request = AccessSecretVersionRequest::build($name);

    // Access the secret version.
    $response = $client->accessSecretVersion($request);

    // Print the secret payload.
    //
    // WARNING: Do not print the secret in a production environment - this
    // snippet is showing how to access the secret material.
    $payload = $response->getPayload()->getData();
    printf('Plaintext: %s', $payload);
}

Python

Per eseguire questo codice, devi innanzitutto configurare un ambiente di sviluppo Python e installare l'SDK Python di Secret Manager. Su Compute Engine o GKE, devi eseguire l'autenticazione con l'ambito cloud-platform.

from google.cloud import secretmanager
import google_crc32c


def access_secret_version(
    project_id: str, secret_id: str, version_id: str
) -> secretmanager.AccessSecretVersionResponse:
    """
    Access the payload for the given secret version if one exists. The version
    can be a version number as a string (e.g. "5") or an alias (e.g. "latest").
    """

    # Create the Secret Manager client.
    client = secretmanager.SecretManagerServiceClient()

    # Build the resource name of the secret version.
    name = f"projects/{project_id}/secrets/{secret_id}/versions/{version_id}"

    # Access the secret version.
    response = client.access_secret_version(request={"name": name})

    # Verify payload checksum.
    crc32c = google_crc32c.Checksum()
    crc32c.update(response.payload.data)
    if response.payload.data_crc32c != int(crc32c.hexdigest(), 16):
        print("Data corruption detected.")
        return response

    # Print the secret payload.
    #
    # WARNING: Do not print the secret in a production environment - this
    # snippet is showing how to access the secret material.
    payload = response.payload.data.decode("UTF-8")
    print(f"Plaintext: {payload}")

Ruby

Per eseguire questo codice, devi innanzitutto configurare un ambiente di sviluppo Ruby e installare l'SDK Ruby di Secret Manager. Su Compute Engine o GKE, devi eseguire l'autenticazione con l'ambito cloud-platform.

# project_id = "YOUR-GOOGLE-CLOUD-PROJECT"  # (e.g. "my-project")
# secret_id  = "YOUR-SECRET-ID"             # (e.g. "my-secret")
# version_id = "YOUR-VERSION"               # (e.g. "5" or "latest")

# Require the Secret Manager client library.
require "google/cloud/secret_manager"

# Create a Secret Manager client.
client = Google::Cloud::SecretManager.secret_manager_service

# Build the resource name of the secret version.
name = client.secret_version_path(
  project:        project_id,
  secret:         secret_id,
  secret_version: version_id
)

# Access the secret version.
version = client.access_secret_version name: name

# Print the secret payload.
#
# WARNING: Do not print the secret in a production environment - this
# snippet is showing how to access the secret material.
payload = version.payload.data
puts "Plaintext: #{payload}"

Coerenza delle risorse

In Secret Manager, l'aggiunta di una versione del secret e l'accesso immediato a questa versione del secret tramite il numero di versione è un'operazione con coerenza elevata.

Le altre operazioni all'interno di Secret Manager sono coerenti a livello di coerenza finale. In genere, le operazioni con coerenza finale convergono in pochi minuti, ma potrebbero richiedere alcune ore.

La propagazione delle autorizzazioni IAM è coerente a livello di coerenza finale. Ciò significa che la concessione o la revoca dell'accesso ai secret potrebbe non avere effetto immediatamente. Per scoprire di più, consulta Propagazione della modifica di accesso.

Passaggi successivi