Aceda a uma versão do Secret

Esta página descreve como aceder a uma versão secreta. O acesso a uma versão do Secret devolve o conteúdo do Secret e metadados adicionais sobre a versão do Secret. Para aceder a uma versão secreta através da CLI do Google Cloud ou da API Secret Manager, tem de especificar o respetivo ID da versão ou o respetivo alias, se atribuído. Também pode aceder à versão mais recente de um segredo especificando latest como o ID da versão.

Funções necessárias

Para receber as autorizações de que precisa para aceder a uma versão de um segredo, peça ao seu administrador para lhe conceder a função de Secret Manager Secret Accessor (roles/secretmanager.secretAccessor) do IAM num segredo. Para mais informações sobre a atribuição de funções, consulte o artigo Faça a gestão do acesso a projetos, pastas e organizações.

Também pode conseguir as autorizações necessárias através de funções personalizadas ou outras funções predefinidas.

Aceda a uma versão do Secret

Para aceder a um segredo, use um dos seguintes métodos:

Consola

  1. Na Google Cloud consola, aceda à página Secret Manager.

    Aceda ao Secret Manager

  2. Na página Secret Manager, clique num segredo para aceder às respetivas versões.

  3. Na página de detalhes do segredo, no separador Versões, selecione a versão do segredo à qual quer aceder.

  4. Clique no menu Ações associado à versão do segredo e, de seguida, clique em Ver valor do segredo.

  5. É apresentada uma caixa de diálogo com o valor da versão do Secret. Clique em Concluído para sair da caixa de diálogo.

gcloud

Aceda a uma versão do Secret

Antes de usar qualquer um dos dados de comandos abaixo, faça as seguintes substituições:

  • VERSION_ID: o nome do recurso da versão do segredo
  • SECRET_ID: o ID do segredo ou o identificador totalmente qualificado do segredo

Execute o seguinte comando:

Linux, macOS ou 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

Aceda a uma versão secreta binária

Para escrever bytes não processados num ficheiro, use a flag --out-file:

Antes de usar qualquer um dos dados de comandos abaixo, faça as seguintes substituições:

  • VERSION_ID: o ID da versão do segredo
  • SECRET_ID: o ID do segredo ou o identificador totalmente qualificado do segredo
  • PATH_TO_SECRET: o caminho completo (incluindo o nome do ficheiro) onde quer guardar o valor secreto obtido

Execute o seguinte comando:

Linux, macOS ou 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"

Obtenha os bytes não processados

Para obter os bytes não processados, faça com que o Cloud SDK imprima a resposta como codificada em base64 e descodifique-a:

Antes de usar qualquer um dos dados de comandos abaixo, faça as seguintes substituições:

  • VERSION_ID: o ID da versão do segredo
  • SECRET_ID: o ID do segredo ou o identificador totalmente qualificado do segredo

Execute o seguinte comando:

Linux, macOS ou 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

A resposta contém a versão do Secret.

REST

Aceda a uma versão do Secret

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

  • PROJECT_ID: o Google Cloud ID do projeto
  • SECRET_ID: o ID do segredo ou o identificador totalmente qualificado do segredo
  • VERSION_ID: o ID da versão do segredo

Método HTTP e URL: 

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

Corpo JSON do pedido: 

{}

Para enviar o seu pedido, escolha uma destas opções:

curl

Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte comando: 

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

Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte comando: 

$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

Deve receber uma resposta JSON semelhante à seguinte:

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

Extraia o segredo através da ferramenta jq

A resposta payload.data é o conteúdo codificado em base64 da versão do Secret. O comando seguinte é um exemplo de extração do segredo através da ferramenta 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#

Para executar este código, primeiro configure um ambiente de programação em C# e instale o SDK em C# do Secret Manager. No Compute Engine ou no GKE, tem de autenticar-se com o âmbito 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

Para executar este código, primeiro configure um ambiente de desenvolvimento Go e instale o SDK Go do Secret Manager. No Compute Engine ou no GKE, tem de autenticar-se com o âmbito 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

Para executar este código, primeiro configure um ambiente de desenvolvimento Java e instale o SDK Java do Secret Manager. No Compute Engine ou no GKE, tem de autenticar-se com o âmbito 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

Para executar este código, primeiro configure um ambiente de desenvolvimento do Node.js e instale o SDK do Node.js do Secret Manager. No Compute Engine ou no GKE, tem de autenticar-se com o âmbito 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

Para executar este código, saiba primeiro como usar o PHP no Google Cloud e instale o SDK PHP do Secret Manager. No Compute Engine ou no GKE, tem de autenticar-se com o âmbito 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

Para executar este código, primeiro configure um ambiente de desenvolvimento Python e instale o SDK Python do Secret Manager. No Compute Engine ou no GKE, tem de autenticar-se com o âmbito 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

Para executar este código, primeiro configure um ambiente de desenvolvimento Ruby e instale o SDK Ruby do Secret Manager. No Compute Engine ou no GKE, tem de autenticar-se com o âmbito 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}"

Consistência dos recursos

No Secret Manager, adicionar uma versão do secret e, em seguida, aceder imediatamente a essa versão do secret pelo número da versão é uma operação fortemente consistente.

Outras operações no Secret Manager acabam por ser consistentes. Normalmente, as operações de consistência eventual convergem em poucos minutos, mas podem demorar algumas horas.

A propagação das autorizações de IAM acaba por ser consistente. Isto significa que a concessão ou a revogação do acesso a segredos pode não ter efeito imediato. Para mais informações, consulte Propagação de alterações de acesso.

O que se segue?