Introdução

O Google Cloud Secret Manager é o serviço da Google Cloud Platform (GCP) responsável pelo armazenamento seguro de informações sensíveis, como senhas, tokens, chaves de API, certificados e demais credenciais utilizadas por aplicações.

O uso do Secret Manager reduz o risco de exposição de credenciais em código-fonte, arquivos de configuração, pipelines de CI/CD e repositórios Git, além de fornecer mecanismos de controle de acesso, auditoria, versionamento e rotação de segredos.

Este documento descreve o processo para criação, gerenciamento e consumo de segredos na plataforma.

Quando Utilizar

O Secret Manager deve ser utilizado para armazenar qualquer informação confidencial utilizada por aplicações ou processos automatizados, incluindo:

Senhas de banco de dados;
Chaves de API;
Tokens de autenticação;
Credenciais de integração com terceiros;
Certificados e chaves privadas;
Credenciais de serviços internos;
Tokens de acesso entre sistemas;
Chaves utilizadas para assinatura ou criptografia.

Informações sensíveis NÃO devem ser armazenadas diretamente em:

Código-fonte;
Arquivos .env versionados;
Repositórios Git;
Wikis ou documentações;
Ferramentas de gestão de tarefas;
Planilhas compartilhadas;
Mensagens de chat ou e-mails.

Fluxo de Utilização

O processo recomendado para utilização de segredos na plataforma segue o fluxo abaixo:

Um novo segredo é identificado como necessário para a aplicação.
O segredo é criado no Google Cloud Secret Manager.
Uma Service Account é criada ou reutilizada para a aplicação.
A permissão de acesso ao segredo é concedida à Service Account.
A aplicação recupera o segredo diretamente do Secret Manager durante sua execução.
O segredo é rotacionado através do versionamento quando necessário.

Desenvolvedor
      │
      ▼
Secret Manager
      │
      ▼
IAM / Service Account
      │
      ▼
Aplicação

Criando um Segredo

Acesso ao Serviço

Acesse o Google Cloud Console.
Navegue até Security > Secret Manager.
Clique em Create Secret.

Cadastro

Ao criar um novo segredo:

Defina um nome padronizado.
Informe o valor inicial do segredo.
Utilize a política de replicação automática.
Registre o propósito do segredo na documentação da aplicação.
Identifique qual aplicação ou serviço utilizará o segredo.
Defina quais Service Accounts deverão possuir acesso.

Convenção de Nomenclatura

Os segredos podem seguir o padrão:

SECRET_<SISTEMA>_<FINALIDADE>

Exemplos:

SECRET_HUBSPOT_API_KEY
SECRET_POSTGRES_PASSWORD
SECRET_STRIPE_TOKEN
SECRET_SENDGRID_API_KEY
SECRET_JWT_SIGNING_KEY

Nomes devem ser claros e refletir o propósito do segredo.

Controle de Acesso

O acesso aos segredos deve ser concedido exclusivamente através de contas de serviço (Service Accounts).

Não devem ser concedidas permissões diretamente para usuários, salvo em casos excepcionais devidamente aprovados.

Princípio do Menor Privilégio

Cada aplicação deve possuir apenas as permissões necessárias para acessar seus próprios segredos.

Exemplo:

Aplicação A
 └── Acessa SECRET_APP_A_DATABASE

Aplicação B
 └── Acessa SECRET_APP_B_DATABASE

Aplicações não devem compartilhar credenciais quando não houver necessidade operacional.

Utilizando Service Accounts

As aplicações não devem utilizar usuários para acessar segredos.

O acesso deve ser realizado através de Service Accounts específicas para cada sistema.

Exemplo:

app-api-prod@empresa.iam.gserviceaccount.com

Permissão recomendada:

Secret Manager Secret Accessor

Sempre que possível, cada aplicação deve possuir acesso apenas aos segredos estritamente necessários para sua operação.

Auditoria

Todos os acessos ao Secret Manager devem ser registrados através dos mecanismos nativos de auditoria da GCP.

Os logs devem permitir identificar:

Quem acessou o segredo;
Quando o acesso ocorreu;
Qual segredo foi acessado;
Qual serviço realizou a operação;
Qual conta executou a ação.

A equipe de segurança poderá utilizar esses registros para investigações de incidentes e atividades suspeitas.

Rotação de Segredos

O Secret Manager suporta versionamento nativo.

Sempre que um segredo precisar ser alterado:

Criar uma nova versão do segredo.
Atualizar a aplicação para consumir a versão mais recente.
Validar o funcionamento da aplicação.
Desabilitar ou remover versões antigas quando apropriado.

A rotação deve ocorrer obrigatoriamente quando:

Houver suspeita de comprometimento;
O fornecedor exigir renovação periódica;
Houver troca de responsáveis pelo sistema;
O segredo possuir data de expiração;
Houver incidente de segurança envolvendo credenciais.

Exemplo

SECRET_POSTGRES_PASSWORD

Versão 1 → Senha antiga
Versão 2 → Senha nova
Versão 1 → Desabilitada após validação

Consumo pelas Aplicações

As aplicações devem obter segredos diretamente do Secret Manager.

Fluxo recomendado:

Aplicação
    │
    ▼
Google Cloud Secret Manager
    │
    ▼
Segredo Recuperado

Não é recomendado:

Código-fonte
    └── Senha fixa

Arquivo versionado
    └── Credencial armazenada

Pipeline CI/CD
    └── Credencial exposta em texto puro

Sempre que possível, deve existir uma camada centralizada responsável por recuperar segredos dentro da aplicação.

Exemplo:

SecretManager.getSecret("SECRET_POSTGRES_PASSWORD")

Exemplo de Consumo em Node.js

Instalação da dependência

npm install @google-cloud/secret-manager

Recuperando um Segredo

const { SecretManagerServiceClient } = require('@google-cloud/secret-manager');

const client = new SecretManagerServiceClient();

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

  return version.payload.data.toString();
}

async function main() {
  const secret = await getSecret(
    'projects/meu-projeto/secrets/SECRET_POSTGRES_PASSWORD/versions/latest'
  );

  console.log(secret);
}

main();

Implementação Recomendada

As aplicações devem centralizar o acesso aos segredos em uma única classe ou módulo.

const { SecretManagerServiceClient } = require('@google-cloud/secret-manager');

const client = new SecretManagerServiceClient();

class SecretManager {
  static async getSecret(secretName) {
    const [version] = await client.accessSecretVersion({
      name: secretName,
    });

    return version.payload.data.toString();
  }
}

module.exports = SecretManager;

Utilização:

const SecretManager = require('./SecretManager');

const dbPassword = await SecretManager.getSecret(
  'projects/meu-projeto/secrets/SECRET_POSTGRES_PASSWORD/versions/latest'
);

Essa abordagem facilita auditoria, manutenção e futuras melhorias de segurança.

Exemplo de Utilização no Cloud Run

O Cloud Run permite consumir segredos diretamente do Secret Manager.

Adicionando um Segredo

Acesse o serviço no Cloud Run.
Clique em Edit and Deploy New Revision.
Abra a seção Variables & Secrets.
Clique em Reference a Secret.
Selecione o segredo desejado.
Escolha se ele será disponibilizado como variável de ambiente ou volume montado.
Realize o deploy da nova revisão.

Boas Práticas

Obrigatório

Utilizar o Secret Manager para armazenar credenciais.
Aplicar controle de acesso por Service Account.
Habilitar auditoria.
Utilizar nomenclatura padronizada.
Realizar rotação quando necessário.
Remover segredos não utilizados.
Revisar permissões periodicamente.
Utilizar o princípio do menor privilégio.

Benefícios

A adoção do Google Cloud Secret Manager proporciona:

Redução da exposição de credenciais;
Controle granular de acesso;
Auditoria centralizada;
Versionamento de segredos;
Facilidade de rotação;
Melhor rastreabilidade dos acessos;
Maior aderência às boas práticas de AppSec e DevSecOps.

Google Cloud Secret Manager

Introdução

Quando Utilizar

Fluxo de Utilização

Criando um Segredo

Acesso ao Serviço

Cadastro

Convenção de Nomenclatura

Controle de Acesso

Princípio do Menor Privilégio

Utilizando Service Accounts

Auditoria

Rotação de Segredos

Exemplo

Consumo pelas Aplicações

Exemplo de Consumo em Node.js

Instalação da dependência

Recuperando um Segredo

Implementação Recomendada

Exemplo de Utilização no Cloud Run

Adicionando um Segredo

Boas Práticas

Obrigatório

Benefícios

Referências