Como gerenciar chaves HMAC para contas de serviço

Acessar conceitos

Esta página mostra como criar, desativar e excluir chaves de código de autenticação de mensagem baseadas em hash (HMAC) associadas a contas de serviço em seu projeto.

Pré-requisitos

Antes de usar este recurso no Cloud Storage, é necessário:

Ter permissão suficiente para trabalhar com chaves HMAC no projeto pretendido:
- Se você for o proprietário do projeto, provavelmente terá as permissões necessárias.
- É preciso ter as permissões do IAM com o prefixo storage.hmacKeys para o projeto. Consulte Como usar permissões do IAM para instruções sobre como conseguir um papel (como, por exemplo, Administrador de chaves HMAC do armazenamento) com essas permissões.
Tenha uma conta de serviço no seu projeto para a qual você pretende criar chaves HMAC. Consulte Como criar uma conta de serviço se você não tiver uma.

Como criar uma chave HMAC

A fim de criar uma chave HMAC para uma conta de serviço:

Console

No Console do Cloud, acesse a página Navegador do Cloud Storage.

Acessar o navegador
Clique em Settings.
Selecione a guia Interoperabilidade.
Clique em + Criar uma chave para uma conta de serviço.
Selecione a conta de serviço à qual você quer que a chave HMAC seja associada.
Clique em Criar chave.

Para informações detalhadas sobre erros de operações com falha no navegador do Cloud Storage, consulte Solução de problemas.

gsutil

Use o comando hmac create:

gsutil hmac create SERVICE_ACCOUNT_EMAIL

Em que SERVICE_ACCOUNT_EMAIL é o endereço de e-mail associado à conta de serviço. Por exemplo, service-7550275089395@my-pet-project.iam.gserviceaccount.com.

Se bem-sucedida, a resposta terá esta aparência:

AccessId: GOOGTS7C7FUP3AIRVJTE2BCDKINBTES3HC2GY5CBFJDCQ2SYHV6A6XXVTJFSA
SecretKey: de7c9b85b8b78aa6bc8a7a36f70a90701c9db4d9

Amostras de código

C++

Para mais informações, consulte a documentação de referência da API Cloud Storage para C++.

Veja no GitHub Feedback

namespace gcs = ::google::cloud::storage;
using ::google::cloud::StatusOr;
return [](gcs::Client client, std::string const& service_account_email) {
  StatusOr<std::pair<gcs::HmacKeyMetadata, std::string>> key_info =
      client.CreateHmacKey(service_account_email);
  if (!key_info) throw std::runtime_error(key_info.status().message());

  std::cout << "The base64 encoded secret is: " << key_info->second
            << "\nDo not miss that secret, there is no API to recover it."
            << "\nThe HMAC key metadata is: " << key_info->first << "\n";
  return key_info->first.access_id();
}

C#

Para mais informações, consulte a documentação de referência da API Cloud Storage para C#.

Veja no GitHub Feedback


using Google.Apis.Storage.v1.Data;
using Google.Cloud.Storage.V1;
using System;

public class CreateHmacKeySample
{
    public HmacKey CreateHmacKey(
        string projectId = "your-project-id",
        string serviceAccountEmail = "dev@iam.gserviceaccount.com")
    {
        var storage = StorageClient.Create();
        var key = storage.CreateHmacKey(projectId, serviceAccountEmail);

        var secret = key.Secret;
        var metadata = key.Metadata;

        Console.WriteLine($"The Base64 encoded secret is: {secret}");
        Console.WriteLine("Make sure to save that secret, there's no API to recover it.");
        Console.WriteLine("The HMAC key metadata is:");
        Console.WriteLine($"ID: {metadata.Id}");
        Console.WriteLine($"Access ID: {metadata.AccessId}");
        Console.WriteLine($"Project ID: {metadata.ProjectId}");
        Console.WriteLine($"Service Account Email: {metadata.ServiceAccountEmail}");
        Console.WriteLine($"State: {metadata.State}");
        Console.WriteLine($"Time Created: {metadata.TimeCreated}");
        Console.WriteLine($"Time Updated: {metadata.Updated}");
        Console.WriteLine($"ETag: {metadata.ETag}");
        return key;
    }
}

Go

Para mais informações, consulte a documentação de referência da API Cloud Storage para Go.

Veja no GitHub Feedback

import (
	"context"
	"fmt"
	"io"
	"time"

	"cloud.google.com/go/storage"
)

// createHMACKey creates a new HMAC key using the given project and service account.
func createHMACKey(w io.Writer, projectID string, serviceAccountEmail string) (*storage.HMACKey, error) {
	ctx := context.Background()

	// Initialize client.
	client, err := storage.NewClient(ctx)
	if err != nil {
		return nil, fmt.Errorf("storage.NewClient: %v", err)
	}
	defer client.Close() // Closing the client safely cleans up background resources.

	ctx, cancel := context.WithTimeout(ctx, time.Minute)
	defer cancel()
	key, err := client.CreateHMACKey(ctx, projectID, serviceAccountEmail)
	if err != nil {
		return nil, fmt.Errorf("CreateHMACKey: %v", err)
	}

	fmt.Fprintf(w, "%s\n", key)
	fmt.Fprintf(w, "The base64 encoded secret is %s\n", key.Secret)
	fmt.Fprintln(w, "Do not miss that secret, there is no API to recover it.")
	fmt.Fprintln(w, "The HMAC key metadata is")
	fmt.Fprintf(w, "%+v", key)

	return key, nil
}

Java

Para mais informações, consulte a documentação de referência da API Cloud Storage para Java.

Veja no GitHub Feedback

// Instantiate a Google Cloud Storage client
Storage storage = StorageOptions.getDefaultInstance().getService();

// The service account email for which the new HMAC key will be created.
// String serviceAccountEmail = "service-account@iam.gserviceaccount.com";
//
// The ID of the project to which the service account belongs.
// String projectId = "project-id";

ServiceAccount account = ServiceAccount.of(serviceAccountEmail);
HmacKey hmacKey =
    storage.createHmacKey(account, Storage.CreateHmacKeyOption.projectId(projectId));

String secret = hmacKey.getSecretKey();
HmacKeyMetadata metadata = hmacKey.getMetadata();

System.out.println("The Base64 encoded secret is: " + secret);
System.out.println("Do not miss that secret, there is no API to recover it.");
System.out.println("The HMAC key metadata is:");
System.out.println("ID: " + metadata.getId());
System.out.println("Access ID: " + metadata.getAccessId());
System.out.println("Project ID: " + metadata.getProjectId());
System.out.println("Service Account Email: " + metadata.getServiceAccount().getEmail());
System.out.println("State: " + metadata.getState().toString());
System.out.println("Time Created: " + new Date(metadata.getCreateTime()).toString());
System.out.println("Time Updated: " + new Date(metadata.getUpdateTime()).toString());
System.out.println("ETag: " + metadata.getEtag());

Node.js

Para mais informações, consulte a documentação de referência da API Cloud Storage para Node.js.

Veja no GitHub Feedback

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// The service account email for which the new HMAC key will be created
// const serviceAccountEmail = 'service-account@iam.gserviceaccount.com';

// The ID of the project to which the service account belongs
// const projectId = 'project-id';

// Imports the Google Cloud client library
const {Storage} = require('@google-cloud/storage');

// Creates a client
const storage = new Storage();

// Create HMAC SA Key
async function createHmacKey() {
  const [hmacKey, secret] = await storage.createHmacKey(serviceAccountEmail, {
    projectId,
  });

  console.log(`The base64 encoded secret is: ${secret}`);
  console.log('Do not miss that secret, there is no API to recover it.');
  console.log('The HMAC key metadata is:');
  for (const [key, value] of Object.entries(hmacKey.metadata)) {
    console.log(`${key}: ${value}`);
  }
}

PHP

Para mais informações, consulte a documentação de referência da API Cloud Storage para PHP.

Veja no GitHub Feedback

use Google\Cloud\Storage\StorageClient;

/**
 * Create a new HMAC key.
 *
 * @param string $projectId The ID of your Google Cloud Platform project.
 * @param string $serviceAccountEmail Service account email to associate with the new HMAC key.
 */
function create_hmac_key($projectId, $serviceAccountEmail)
{
    // $projectId = 'my-project-id';
    // $serviceAccountEmail = 'service-account@iam.gserviceaccount.com';

    $storage = new StorageClient();
    // By default createHmacKey will use the projectId used by StorageClient().
    $hmacKeyCreated = $storage->createHmacKey($serviceAccountEmail, ['projectId' => $projectId]);

    printf('The base64 encoded secret is: %s' . PHP_EOL, $hmacKeyCreated->secret());
    print('Do not miss that secret, there is no API to recover it.' . PHP_EOL);
    printf('HMAC key Metadata: %s' . PHP_EOL, print_r($hmacKeyCreated->hmacKey()->info(), true));
}

Python

Para mais informações, consulte a documentação de referência da API Cloud Storage para Python.

Veja no GitHub Feedback

from google.cloud import storage

def create_key(project_id, service_account_email):
    """
    Create a new HMAC key using the given project and service account.
    """
    # project_id = 'Your Google Cloud project ID'
    # service_account_email = 'Service account used to generate the HMAC key'

    storage_client = storage.Client(project=project_id)

    hmac_key, secret = storage_client.create_hmac_key(
        service_account_email=service_account_email, project_id=project_id
    )

    print("The base64 encoded secret is {}".format(secret))
    print("Do not miss that secret, there is no API to recover it.")
    print("The HMAC key metadata is:")
    print("Service Account Email: {}".format(hmac_key.service_account_email))
    print("Key ID: {}".format(hmac_key.id))
    print("Access ID: {}".format(hmac_key.access_id))
    print("Project ID: {}".format(hmac_key.project))
    print("State: {}".format(hmac_key.state))
    print("Created At: {}".format(hmac_key.time_created))
    print("Updated At: {}".format(hmac_key.updated))
    print("Etag: {}".format(hmac_key.etag))
    return hmac_key

Ruby

Para mais informações, consulte a documentação de referência da API Cloud Storage para Ruby.

Veja no GitHub Feedback

def create_hmac_key service_account_email:
  # The service account email used to generate an HMAC key
  # service_account_email = "service-my-project-number@gs-project-accounts.iam.gserviceaccount.com"

  require "google/cloud/storage"

  storage = Google::Cloud::Storage.new

  # By default Storage#create_hmac_key uses the Storage client project_id
  hmac_key = storage.create_hmac_key service_account_email

  puts "The base64 encoded secret is: #{hmac_key.secret}"
  puts "Do not miss that secret, there is no API to recover it."
  puts "\nThe HMAC key metadata is:"
  puts "Key ID:                #{hmac_key.id}"
  puts "Service Account Email: #{hmac_key.service_account_email}"
  puts "Access ID:             #{hmac_key.access_id}"
  puts "Project ID:            #{hmac_key.project_id}"
  puts "Active:                #{hmac_key.active?}"
  puts "Created At:            #{hmac_key.created_at}"
  puts "Updated At:            #{hmac_key.updated_at}"
  puts "Etag:                  #{hmac_key.etag}"
end

APIs REST

API JSON

Consiga um token de acesso de autorização do OAuth 2.0 Playground (em inglês). Configure o Playground para usar suas credenciais do OAuth.
Use cURL (em inglês) para chamar a API JSON com uma solicitação POST hmacKeys:
```
curl -X POST \
  -H "Authorization: Bearer OAUTH2_TOKEN" \
  "https://storage.googleapis.com/storage/v1/projects/PROJECT_IDENTIFIER/hmacKeys?serviceAccountEmail=SERVICE_ACCOUNT_EMAIL"
```
Em que:
- OAUTH2_TOKEN é o token de acesso gerado na Etapa 1.
- PROJECT_IDENTIFIER é o ID ou o número do projeto associado à chave que você quer criar; Por exemplo, my-pet-project.
- SERVICE_ACCOUNT_EMAIL é o endereço de e-mail associado à conta de serviço. Por exemplo, service-7550275089395@my-pet-project.iam.gserviceaccount.com.

API XML

Consiga um token de acesso de autorização do OAuth 2.0 Playground (em inglês). Configure o Playground para usar suas credenciais do OAuth.
Use cURL (em inglês) para chamar a API XML com uma solicitação de chave HMAC POST:
```
curl -X POST \
  -H "Authorization: Bearer OAUTH2_TOKEN" \
  "https://storage.googleapis.com/?Action=CreateAccessKey&UserName=SERVICE_ACCOUNT_EMAIL"
```
Em que:
- OAUTH2_TOKEN é o token de acesso gerado na etapa 1.
- SERVICE_ACCOUNT_EMAIL é o endereço de e-mail associado à conta de serviço. Por exemplo, service-7550275089395@my-pet-project.iam.gserviceaccount.com.

Como acessar informações da chave HMAC

Para listar as chaves HMAC de um projeto e acessar informações sobre elas:

Console

No Console do Cloud, acesse a página Navegador do Cloud Storage.

Acessar o navegador
Clique em Settings.
Selecione a guia Interoperabilidade.

gsutil

Use o comando hmac list para listar chaves hmac em seu projeto:
```
gsutil hmac list
```
Se funcionar, gsutil retornará uma lista de IDs de acesso da chave hmac com a conta de serviço associada a cada chave.
Use o comando hmac get para recuperar metadados de uma chave específica:
```
gsutil hmac get KEY_ACCESS_ID 
```
em que KEY_ACCESS_ID é o ID de acesso da chave pretendida.

Amostras de código

C++

Para mais informações, consulte a documentação de referência da API Cloud Storage para C++.

A amostra a seguir recupera uma lista de chaves HMAC associadas a um projeto:

google/cloud/storage/examples/storage_service_account_samples.cc

Como gerenciar chaves HMAC para contas de serviço

Pré-requisitos

Como criar uma chave HMAC

Console

gsutil

Amostras de código

C++

C#

Go

Java

Node.js

PHP

Python

Ruby

APIs REST

API JSON

API XML

Como acessar informações da chave HMAC

Console

gsutil

Amostras de código

C++

C#

Go

Java

Node.js

PHP

Python

Ruby

APIs REST

API JSON

API XML

Como atualizar o estado de uma chave HMAC

Console

gsutil

Amostras de código

C++

C#

Go

Java

Node.js

PHP

Python

Ruby

APIs REST

API JSON

API XML

Como excluir uma chave HMAC

Console

gsutil

Amostras de código

C++

C#

Go

Java

Node.js

PHP

Python

Ruby

APIs REST

API JSON

API XML

A seguir