Auf eine regionale Secret-Version zugreifen

Auf dieser Seite wird beschrieben, wie Sie auf eine Secret-Version zugreifen. Beim Zugriff auf eine Secret-Version werden die Secret-Inhalte sowie zusätzliche Metadaten zur Secret-Version zurückgegeben. Wenn Sie mit der Google Cloud CLI oder der Secret Manager API auf eine Secret-Version zugreifen möchten, müssen Sie entweder die Versions-ID oder den Alias angeben, falls zugewiesen. Sie können auch auf die neueste Version eines Secrets zugreifen, indem Sie latest als Versions-ID angeben.

Erforderliche Rollen

Bitten Sie Ihren Administrator, Ihnen die IAM-Rolle Secret Manager Secret Accessor (roles/secretmanager.secretAccessor) für ein Secret zu gewähren, um die Berechtigungen zu erhalten, die Sie für den Zugriff auf eine Secret-Version benötigen. Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

Sie können die erforderlichen Berechtigungen auch über benutzerdefinierte Rollen oder andere vordefinierte Rollen erhalten.

Auf eine Secret-Version zugreifen

Sie haben folgende Möglichkeiten, ein Secret zu bearbeiten:

Console

  1. Rufen Sie in der Google Cloud Console die Seite Secret Manager auf.

    Zu Secret Manager

  2. Klicken Sie auf der Seite Secret Manager auf den Tab Regionale Secrets und dann auf ein Secret, um auf seine Versionen zuzugreifen.

  3. Wählen Sie auf der Seite mit den Secret-Details auf dem Tab Versionen die Secret-Version aus, auf die Sie zugreifen möchten.

  4. Klicken Sie auf das Menü Aktionen, das mit der Secret-Version verknüpft ist, und dann auf Secret-Wert ansehen.

  5. Ein Dialogfeld mit dem Wert der Secret-Version wird angezeigt. Klicken Sie auf Fertig, um das Dialogfeld zu schließen.

gcloud

Auf eine Secret-Version zugreifen

Ersetzen Sie folgende Werte, bevor sie einen der Befehlsdaten verwenden:

  • VERSION_ID: der Ressourcenname der Secret-Version
  • SECRET_ID: die ID des Secrets oder die voll qualifizierte Kennzeichnung für das Secret
  • LOCATION: den Speicherort des Geheimnisses in Google Cloud

Führen Sie folgenden Befehl aus:

Linux, macOS oder Cloud Shell

gcloud secrets versions access VERSION_ID --secret=SECRET_ID --location=LOCATION

Windows (PowerShell)

gcloud secrets versions access VERSION_ID --secret=SECRET_ID --location=LOCATION

Windows (cmd.exe)

gcloud secrets versions access VERSION_ID --secret=SECRET_ID --location=LOCATION

Auf eine binäre Secret-Version zugreifen

Verwenden Sie das Flag „–out-file“, um Rohbytes in eine Datei zu schreiben:

Ersetzen Sie folgende Werte, bevor sie einen der Befehlsdaten verwenden:

  • VERSION_ID: die ID der Secret-Version
  • SECRET_ID: die ID des Secrets oder die voll qualifizierte Kennzeichnung für das Secret
  • LOCATION: den Speicherort des Geheimnisses in Google Cloud
  • PATH_TO_SECRET: Der vollständige Pfad (einschließlich Dateiname), unter dem Sie den abgerufenen Secret-Wert speichern möchten.

Führen Sie folgenden Befehl aus:

Linux, macOS oder Cloud Shell

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

Windows (PowerShell)

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

Windows (cmd.exe)

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

Rohbytes abrufen

Damit Sie die Rohbyte erhalten, muss das Cloud SDK die Antwort als base64-codiert und decodieren:

Ersetzen Sie folgende Werte, bevor sie einen der Befehlsdaten verwenden:

  • VERSION_ID: die ID der Secret-Version
  • SECRET_ID: die ID des Secrets oder die voll qualifizierte Kennzeichnung für das Secret
  • LOCATION: den Speicherort des Geheimnisses in Google Cloud

Führen Sie folgenden Befehl aus:

Linux, macOS oder Cloud Shell

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

Windows (PowerShell)

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

Windows (cmd.exe)

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

Die Antwort enthält die Secret-Version.

REST

Auf eine Secret-Version zugreifen

Ersetzen Sie diese Werte in den folgenden Anfragedaten:

  • LOCATION: den Speicherort des Geheimnisses in Google Cloud
  • PROJECT_ID: die Google Cloud-Projekt-ID
  • SECRET_ID: die ID des Secrets oder die voll qualifizierte Kennzeichnung für das Secret
  • VERSION_ID: die ID der Secret-Version

HTTP-Methode und URL:

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

JSON-Text der Anfrage:

{}

Wenn Sie die Anfrage senden möchten, wählen Sie eine der folgenden Optionen aus:

curl

Speichern Sie den Anfragetext in einer Datei mit dem Namen request.json und führen Sie den folgenden Befehl aus:

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

PowerShell

Speichern Sie den Anfragetext in einer Datei mit dem Namen request.json und führen Sie den folgenden Befehl aus:

$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.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/secrets/SECRET_ID/versions/VERSION_ID:access" | Select-Object -Expand Content

Sie sollten in etwa folgende JSON-Antwort erhalten:

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

Secret mit dem jq-Tool extrahieren

Die Antwort payload.data ist der base64-codierte Inhalt der Secret-Version. Der folgende Befehl ist ein Beispiel für das Extrahieren des Secrets mit dem jq-Tool.

  $ curl "https://secretmanager.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/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
  

Go

Um diesen Code auszuführen, müssen Sie zuerst eine Go-Entwicklungsumgebung einrichten und das Secret Manager Go SDK installieren. In Compute Engine oder GKE müssen Sie sich mit dem Bereich cloud-platform authentifizieren.

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

	secretmanager "cloud.google.com/go/secretmanager/apiv1"
	"cloud.google.com/go/secretmanager/apiv1/secretmanagerpb"
	"google.golang.org/api/option"
)

// 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 AccessRegionalSecretVersion(w io.Writer, projectId, locationId, secretId, versionId string) error {
	// name := "projects/my-project/locations/my-location/secrets/my-secret/versions/5"
	// name := "projects/my-project/locations/my-location/secrets/my-secret/versions/latest"

	// Create the client.
	ctx := context.Background()

	// Endpoint to call the regional secret manager sever
	endpoint := fmt.Sprintf("secretmanager.%s.rep.googleapis.com:443", locationId)
	client, err := secretmanager.NewClient(ctx, option.WithEndpoint(endpoint))
	if err != nil {
		return fmt.Errorf("failed to create secretmanager client: %w", err)
	}
	defer client.Close()

	name := fmt.Sprintf("projects/%s/locations/%s/secrets/%s/versions/%s", projectId, locationId, secretId, versionId)

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

Um diesen Code auszuführen, müssen Sie zuerst eine Java-Entwicklungsumgebung einrichten und das Secret Manager Java SDK installieren. In Compute Engine oder GKE müssen Sie sich mit dem Bereich cloud-platform authentifizieren.

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

public class AccessRegionalSecretVersion {

  public static void main(String[] args)throws Exception {
    // TODO(developer): Replace these variables before running the sample.

    // Your GCP project ID.
    String projectId = "your-project-id";
    // Location of the secret.
    String locationId = "your-location-id";
    // Resource ID of the secret.
    String secretId = "your-secret-id";
    // Version of the Secret ID you want to access.
    String versionId = "your-version-id";
    accessRegionalSecretVersion(projectId, locationId, 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 SecretPayload accessRegionalSecretVersion(
      String projectId, String locationId, String secretId, String versionId)
      throws Exception {

    // Endpoint to call the regional secret manager sever
    String apiEndpoint = String.format("secretmanager.%s.rep.googleapis.com:443", locationId);
    SecretManagerServiceSettings secretManagerServiceSettings =
        SecretManagerServiceSettings.newBuilder().setEndpoint(apiEndpoint).build();

    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests.
    try (SecretManagerServiceClient client = 
        SecretManagerServiceClient.create(secretManagerServiceSettings)) {
      SecretVersionName secretVersionName = 
          SecretVersionName.ofProjectLocationSecretSecretVersionName(
              projectId, locationId, secretId, versionId);
      // Access the secret version.
      AccessSecretVersionResponse response = client.accessSecretVersion(secretVersionName);

      // Verify checksum. The used library is available in Java 9+.
      // For Java 8, use:
      // 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.");
        throw new Exception("Data corruption detected.");
      }

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

      return response.getPayload();
    }
  }
}

Node.js

Um diesen Code auszuführen, müssen Sie zuerst eine Node.js-Entwicklungsumgebung einrichten und das Cloud KMS Node.js SDK installieren. In Compute Engine oder GKE müssen Sie sich mit dem Bereich cloud-platform authentifizieren.

/**
 * TODO(developer): Uncomment these variables before running the sample.
 */
// const projectId = 'my-project';
// const locationId = 'location-id';
// const secretId = 'my-secret'
// const version = 'secret-version';

const name = `projects/${projectId}/locations/${locationId}/secrets/${secretId}/versions/${version}`;

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

// Adding the endpoint to call the regional secret manager sever
const options = {};
options.apiEndpoint = `secretmanager.${locationId}.rep.googleapis.com`;

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

async function accessRegionalSecretVersion() {
  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}`);
}

accessRegionalSecretVersion();

Python

Um diesen Code auszuführen, müssen Sie zuerst eine Python-Entwicklungsumgebung einrichten und das Secret Manager Python SDK installieren. In Compute Engine oder GKE müssen Sie sich mit dem Bereich cloud-platform authentifizieren.

from google.cloud import secretmanager_v1
import google_crc32c


def access_regional_secret_version(
    project_id: str,
    location_id: str,
    secret_id: str,
    version_id: str,
) -> secretmanager_v1.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").
    """

    # Endpoint to call the regional secret manager sever.
    api_endpoint = f"secretmanager.{location_id}.rep.googleapis.com"

    # Create the Secret Manager client.
    client = secretmanager_v1.SecretManagerServiceClient(
        client_options={"api_endpoint": api_endpoint},
    )

    # Build the resource name of the secret version.
    name = f"projects/{project_id}/locations/{location_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}")

    return response

Ressourcenkonsistenz

Das Hinzufügen einer Secret-Version und das sofortige Zugreifen auf diese Secret-Version anhand der Versionsnummer ist im Secret Manager ein strikt konsistenter Vorgang.

Andere Vorgänge im Secret Manager sind letztendlich konsistent. Vorgänge mit Eventual Consistency werden in der Regel innerhalb von Minuten ausgeführt, können aber ein paar Stunden dauern.

Die Propagierung von IAM-Berechtigungen ist letztendlich konsistent. Das bedeutet, dass die Gewährung oder Aufhebung des Zugriffs auf Secrets möglicherweise nicht sofort wirksam wird. Weitere Informationen finden Sie unter Zugriffsänderungsverteilung.

Nächste Schritte