גישה לגרסה של סוד

בדף הזה מוסבר איך לגשת לגרסה של סוד. כשניגשים לגרסה סודית, מקבלים את התוכן הסודי ומטא-נתונים נוספים על הגרסה הסודית. כדי לגשת לגרסת סוד באמצעות Google Cloud CLI או Secret Manager API, צריך לציין את מזהה הגרסה או את הכינוי שלה, אם הוקצה לה כינוי. אפשר לגשת לגרסה האחרונה של סוד גם על ידי ציון latest כמזהה הגרסה.

התפקידים הנדרשים

כדי לקבל את ההרשאות שדרושות לגישה לגרסה של סוד, צריך לבקש מהאדמין להקצות לכם את תפקיד ה-IAM‏ Secret Manager Secret Accessor ‏ (roles/secretmanager.secretAccessor) בסוד. כדי לקרוא הסבר על מתן תפקידים, ראו איך מנהלים את הגישה ברמת הפרויקט, התיקייה והארגון.

יכול להיות שאפשר לקבל את ההרשאות הנדרשות גם באמצעות תפקידים בהתאמה אישית או תפקידים מוגדרים מראש.

גישה לגרסה של סוד

כדי לגשת לסוד, משתמשים באחת מהשיטות הבאות:

המסוף

  1. נכנסים לדף Secret Manager במסוף Google Cloud .

    מעבר אל Secret Manager

  2. בדף Secret Manager, לוחצים על סוד כדי לגשת לגרסאות שלו.

  3. בדף הפרטים של הסוד, בכרטיסייה גרסאות, בוחרים את גרסת הסוד שרוצים לגשת אליה.

  4. לוחצים על התפריט פעולות שמשויך לגרסת הסוד, ואז לוחצים על הצגת ערך הסוד.

  5. מופיעה תיבת דו-שיח עם הערך של גרסת הסוד. לוחצים על סיום כדי לצאת מתיבת הדו-שיח.

gcloud

גישה לגרסה של סוד

לפני השימוש בנתוני הפקודה הבאים, צריך להחליף את הנתונים הבאים:

  • ‫VERSION_ID: שם המשאב של גרסת הסוד
  • ‫SECRET_ID: מזהה הסוד

מריצים את הפקודה הבאה:

‫Linux,‏ macOS או 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

גישה לגרסה בינארית של סוד

כדי לכתוב בייטים גולמיים לקובץ, משתמשים בדגל ‎--out-file:

לפני השימוש בנתוני הפקודה הבאים, צריך להחליף את הנתונים הבאים:

  • ‫VERSION_ID: המזהה של גרסת הסוד
  • ‫SECRET_ID: מזהה הסוד
  • ‫PATH_TO_SECRET: הנתיב המלא (כולל שם הקובץ) שבו רוצים לשמור את ערך הסוד שאוחזר

מריצים את הפקודה הבאה:

‫Linux,‏ macOS או 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"

קבלת הבייטים הגולמיים

כדי לקבל את הבייטים הגולמיים, צריך להגדיר את Cloud SDK להדפסת התגובה בקידוד base64 ולפענח אותה:

לפני השימוש בנתוני הפקודה הבאים, צריך להחליף את הנתונים הבאים:

  • ‫VERSION_ID: המזהה של גרסת הסוד
  • ‫SECRET_ID: מזהה הסוד

מריצים את הפקודה הבאה:

‫Linux,‏ macOS או 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

התשובה מכילה את הגרסה של הסוד.

REST

גישה לגרסה של סוד

לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הנתונים הבאים:

  • ‫PROJECT_ID: מזהה הפרויקט Google Cloud
  • ‫SECRET_ID: מזהה הסוד
  • ‫VERSION_ID: המזהה של גרסת הסוד

ה-method של ה-HTTP וכתובת ה-URL: 

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

גוף בקשת JSON: 

{}

כדי לשלוח את הבקשה עליכם לבחור אחת מהאפשרויות הבאות:

curl

שומרים את גוף הבקשה בקובץ בשם request.json ומריצים את הפקודה הבאה: 

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

שומרים את גוף הבקשה בקובץ בשם request.json ומריצים את הפקודה הבאה: 

$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

אתם אמורים לקבל תגובת JSON שדומה לזו:

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

שליפת הסוד באמצעות הכלי jq

התשובה payload.data היא התוכן של גרסת הסוד בקידוד base64. הפקודה הבאה היא דוגמה לחילוץ הסוד באמצעות הכלי 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#

כדי להריץ את הקוד הזה, קודם צריך להגדיר סביבת פיתוח בשפת C# ‎ ולהתקין את Secret Manager C# SDK. ב-Compute Engine או ב-GKE, צריך לעבור אימות באמצעות ההיקף 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

כדי להריץ את הקוד הזה, קודם צריך להגדיר סביבת פיתוח של Go ולהתקין את Secret Manager Go SDK. ב-Compute Engine או ב-GKE, צריך לעבור אימות באמצעות ההיקף 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

כדי להריץ את הקוד הזה, קודם צריך להגדיר סביבת פיתוח ב-Java ולהתקין את Secret Manager Java SDK. ב-Compute Engine או ב-GKE, צריך לעבור אימות באמצעות ההיקף 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

כדי להריץ את הקוד הזה, קודם צריך להגדיר סביבת פיתוח של Node.js ולהתקין את Secret Manager Node.js SDK. ב-Compute Engine או ב-GKE, צריך לעבור אימות באמצעות ההיקף 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

כדי להריץ את הקוד הזה, קודם צריך לקרוא על שימוש ב-PHP ב-Google Cloud ולהתקין את Secret Manager PHP SDK. ב-Compute Engine או ב-GKE, צריך לעבור אימות באמצעות ההיקף 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

כדי להריץ את הקוד הזה, קודם צריך להגדיר סביבת פיתוח בשפת Python ולהתקין את Secret Manager Python SDK. ב-Compute Engine או ב-GKE, צריך לעבור אימות באמצעות ההיקף 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

כדי להריץ את הקוד הזה, קודם צריך להגדיר סביבת פיתוח של Ruby ולהתקין את Secret Manager Ruby SDK. ב-Compute Engine או ב-GKE, צריך לעבור אימות באמצעות ההיקף 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}"

עקביות המשאבים

ב-Secret Manager, הוספה של גרסת סוד וגישה מיידית לגרסת הסוד הזו לפי מספר הגרסה היא פעולה עקבית מאוד.

לפעולות אחרות ב-Secret Manager יש מודל עקביות הדרגתי. בדרך כלל, פעולות עם עקביות סופית מתכנסות תוך דקות, אבל יכול להיות שהתהליך יימשך כמה שעות.

הפצת הרשאות IAM היא עקבית באופן הדרגתי. כלומר, יכול להיות שיעבור זמן עד שהענקת גישה לסודות או ביטול הגישה לסודות ייכנסו לתוקף. מידע נוסף זמין במאמר הפצת שינוי גישה.

המאמרים הבאים