Funcionalidade 6: Integração com Gerenciador de Segredos em Nuvem

Visão Geral

Atualmente, o Semaphore armazena todas as credenciais em seu próprio banco de dados. Organizações que utilizam plataformas em nuvem precisam de uma forma de obter segredos diretamente do serviço de gerenciamento de segredos do seu provedor de nuvem em tempo de execução, evitando a duplicação de credenciais e aproveitando as políticas de rotação existentes. Esta funcionalidade adiciona integrações nativas com AWS Secrets Manager e Azure Key Vault como recursos exclusivos do plano Enterprise.

Motivação

Equipes corporativas já gerenciam segredos no AWS Secrets Manager ou Azure Key Vault com políticas de rotação estabelecidas, controles de acesso e trilhas de auditoria. Duplicar essas credenciais no banco de dados do Semaphore cria uma segunda fonte de verdade que pode ficar dessincronizada.
A rotação de credenciais no provedor de nuvem não se propaga automaticamente para o Semaphore — alguém precisa atualizar manualmente cada entrada do armazenamento de chaves afetada após cada rotação.
Políticas de conformidade e segurança em indústrias regulamentadas frequentemente exigem que segredos nunca saiam do perímetro do provedor de nuvem ou sejam armazenados em bancos de dados de terceiros.
O armazenamento de chaves integrado do Semaphore não possui os controles de acesso, a granularidade de auditoria e a automação de rotação que os gerenciadores de segredos em nuvem oferecem nativamente.

Especificação Detalhada

Enterprise

6.1 Integração com AWS Secrets Manager

Objetivo: Obter segredos em tempo de execução do AWS Secrets Manager, permitindo que equipes aproveitem sua infraestrutura de segredos AWS existente sem duplicar credenciais no banco de dados do Semaphore.

Requisitos:

Novo tipo de backend de segredos externo: aws_secrets_manager.
Métodos de autenticação:
- IAM role (recomendado para implantações EC2/ECS/EKS) — nenhuma credencial armazenada no Semaphore.
- Access key + secret key — armazenados no armazenamento de chaves do Semaphore (criptografado).
- Assumed role com external ID — para acesso entre contas.
Segredos são referenciados por ARN ou nome + versão/estágio opcional.
Suporte para segredos estruturados em JSON com um seletor field para extrair valores individuais (ex.: {"username": "admin", "password": "..."} → extrair password).
Suporte a rotação automática de segredos — quando a AWS rotaciona um segredo, o Semaphore obtém o novo valor na próxima execução de tarefa.
Modelo de configuração:

{
  "name": "Production AWS",
  "type": "aws_secrets_manager",
  "region": "us-east-1",
  "auth_method": "iam_role",
  "role_arn": "arn:aws:iam::123456789:role/semaphore-secrets",
  "external_id": "optional-external-id"
}

Referência de entrada do armazenamento de chaves:

{
  "type": "external",
  "backend": "aws_secrets_manager",
  "secret_name": "production/db_password",
  "field": "password",
  "aws_config_id": 1
}

Issues relacionadas: #2248

6.2 Integração com Azure Key Vault

Objetivo: Obter segredos em tempo de execução do Azure Key Vault, permitindo que organizações que utilizam Azure gerenciem e rotacionem credenciais de forma centralizada sem armazená-las no Semaphore.

Requisitos:

Novo tipo de backend de segredos externo: azure_key_vault.
Métodos de autenticação:
- Managed identity (recomendado para implantações Azure VM/AKS) — nenhuma credencial armazenada no Semaphore.
- Service principal com client secret.
- Service principal com certificado.
Segredos são referenciados por vault URL + nome do segredo + versão opcional.
Suporte para recuperação de segredos, chaves e certificados do vault.
Suporte a rotação automática de segredos — quando o Azure rotaciona um segredo, o Semaphore obtém o novo valor na próxima execução de tarefa.
Modelo de configuração:

{
  "name": "Production Azure",
  "type": "azure_key_vault",
  "vault_url": "https://my-vault.vault.azure.net",
  "auth_method": "managed_identity",
  "tenant_id": "...",
  "client_id": "..."
}

Referência de entrada do armazenamento de chaves:

{
  "type": "external",
  "backend": "azure_key_vault",
  "secret_name": "db-password",
  "version": "latest",
  "azure_config_id": 1
}

Issues relacionadas: #2248, #3170

6.3 Referência Unificada de Segredos Externos

Objetivo: Fornecer um tipo comum de entrada no armazenamento de chaves que aponta para um segredo em qualquer provedor de nuvem suportado.

Requisitos:

Novo tipo de armazenamento de chaves: “External Reference” que armazena um ponteiro para o segredo (ex.: AWS ARN, Azure vault URL + nome do segredo) em vez do segredo em si.
No momento da execução da tarefa, o Semaphore resolve a referência chamando a API do provedor de nuvem e recupera o valor atual.
O valor resolvido nunca é armazenado no banco de dados do Semaphore — ele existe apenas em memória durante a execução da tarefa.
A conexão com o gerenciador de segredos em nuvem é configurada no nível do projeto ou do sistema (URL, método de autenticação, namespace/prefixo).
A interface mostra referências externas com um emblema/ícone distinto e o tipo de backend (AWS/Azure).
Validação ao salvar: o Semaphore tenta resolver a referência e exibe um aviso se o segredo não estiver acessível (sem bloquear o salvamento).

6.4 Cache de Segredos

Objetivo: Reduzir chamadas de API para provedores de nuvem armazenando segredos resolvidos em cache na memória.

Requisitos:

Cache opcional em memória de curta duração (TTL configurável, padrão de 5 minutos) para reduzir chamadas de API ao provedor de nuvem.
O cache é apenas em memória e é invalidado ao reiniciar o Semaphore.
O cache é indexado por ID de configuração do backend + referência do segredo, de modo que o mesmo segredo usado por múltiplos templates é buscado apenas uma vez por janela de TTL.
O cache pode ser desabilitado por configuração de backend (definir TTL como 0) para segredos que devem ser sempre buscados atualizados (ex.: durante rotação ativa).
Configuração: campo cache_ttl na configuração do backend (ex.: "cache_ttl": "5m").

Alterações no Esquema do Banco de Dados

Novas tabelas:

secret_backend — armazena configurações de provedores de nuvem (project_id, type, name, config JSON, created_at, updated_at)

Tabelas modificadas:

access_key — adicionar colunas:
- external_backend_id (integer, nullable, FK para secret_backend) — vincula à configuração do provedor de nuvem
- external_reference (JSON, nullable) — armazena o ponteiro do segredo (ARN, vault URL, nome do segredo, field, version)

API Endpoints

GET/POST /api/project/{id}/secret-backends — listar/criar configurações de backend
PUT/DELETE /api/project/{id}/secret-backends/{backend_id} — atualizar/excluir backend
POST /api/project/{id}/secret-backends/{backend_id}/test — testar conectividade e autenticação
POST /api/project/{id}/secret-backends/{backend_id}/resolve — resolver uma referência de segredo (para validação)

Configuração

Novas opções de configuração:

Key	Env Var	Default	Descrição
`secret_cache_ttl`	`SEMAPHORE_SECRET_CACHE_TTL`	`5m`	TTL padrão do cache em memória para segredos externos resolvidos
`secret_resolve_timeout`	`SEMAPHORE_SECRET_RESOLVE_TIMEOUT`	`10s`	Tempo máximo de espera pela resposta da API do provedor de nuvem ao resolver um segredo