A tab Segredos é um repositório encriptado para os valores de configuração sensíveis de que uma aplicação Node.js necessita, tais como chaves de API, segredos de assinatura e tokens de terceiros, mantidos por ambiente para que as suas credenciais de produção e as suas credenciais de pré-visualização nunca se misturem.
Onde Vivem os Segredos
Abra Websites, clique no site, abra o grupo Environment no menu lateral esquerdo do site e escolha Segredos. O separador tem o nome Segredos.
O separador só aparece em sites Node.js. Os sites WordPress, PHP e estáticos não o mostram, porque a sua configuração reside em ficheiros no disco: wp-config.php para WordPress, e o que quer que a sua framework leia para uma aplicação PHP simples.
Como os Valores São Protegidos
Cada valor é encriptado antes de tocar na base de dados. Nada é guardado como texto legível, e a vista de lista nunca mostra um valor completo: mostra uma máscara com apenas os últimos quatro caracteres, para que possa distinguir duas chaves semelhantes sem expor nenhuma delas.
Cada linha tem um emblema Encrypted como lembrete disso. Ler um valor de volta é uma ação separada e deliberada, e não algo que acontece apenas ao abrir a página.
Definir, revelar e eliminar um segredo exigem todos a permissão sites:write. Um membro da equipa com acesso apenas de leitura consegue ver quais as chaves que existem e as suas máscaras, mas não os seus valores.
Os Dois Ambientes
Um controlo segmentado no topo da página alterna entre production e preview. São conjuntos de chaves completamente separados. Definir STRIPE_SECRET_KEY em produção não o cria em pré-visualização, e eliminá-lo de pré-visualização não afeta a produção.
Essa separação é o objetivo da funcionalidade. As compilações de pré-visualização são ambientes descartáveis que qualquer pessoa com acesso ao repositório pode despoletar, pelo que devem transportar credenciais de teste, não credenciais reais. Consulte Implementações de Pré-visualização Para Pull Requests para saber como os ambientes de pré-visualização são criados.
Adicionar ou Atualizar um Segredo
- Escolha o ambiente com o controlo segmentado.
- Digite o nome no campo KEY_NAME. O campo força maiúsculas à medida que escreve.
- Coloque o valor no segundo campo. É mascarado à medida que escreve.
- Clique em Set.
Definir uma chave que já existe sobrepõe-se a ela. Não existe uma ação de edição separada nem um passo de confirmação para uma sobreposição, por isso verifique o separador do ambiente antes de clicar em Set.
Regras de Nomenclatura de Chaves
Uma chave deve começar com uma letra maiúscula e pode depois conter letras maiúsculas, dígitos e underscores, até 128 caracteres. DATABASE_URL, API_KEY_V2 e SENTRY_DSN são todos válidos. Qualquer outra coisa é rejeitada com a mensagem Key deve estar em UPPER_SNAKE_CASE com letras/números/underscore.
Vale a pena conhecer mais dois limites:
- Um valor não pode estar vazio. Submeter um valor em branco devolve value obrigatório.
- Um valor não pode exceder 16 KB. Isso é generoso para um token, mas não é suficiente para, por exemplo, uma cadeia de certificados completa, que pertence a um ficheiro e não a um segredo.
Ler um Valor de Volta
Clique em Copy na linha. O KPanel desencripta o valor no lado do servidor e coloca-o diretamente na sua área de transferência, com uma confirmação Valor copiado para a área de transferência. O valor não é apresentado no ecrã, pelo que uma partilha de ecrã ou alguém a espreitar por cima do ombro não o consegue captar.
Cada revelação é registada no registo de auditoria do site, juntamente com quem o fez e qual a chave, e aparece no Registo de Atividade do Site.
Se precisar de verificar que um valor está correto sem o expor, compare a máscara em vez disso. Os últimos quatro caracteres são suficientes para confirmar que tem o token certo, e já estão no ecrã.
Usar um Segredo na Sua Aplicação
Copie o valor para onde quer que a sua aplicação leia a sua configuração no servidor. Para uma aplicação Node.js, isso é normalmente uma variável de ambiente definida pelo seu gestor de processos, ou um ficheiro .env na raiz da aplicação que o seu código carrega no arranque.
Não envie esse ficheiro para o seu repositório. Adicione .env a .gitignore antes de o criar. Um segredo que tenha sido enviado para um repositório git remoto tem de ser tratado como comprometido e rodado junto do fornecedor, porque permanece no histórico mesmo depois de eliminar o ficheiro.
O separador Secrets é o seu registo do que é o valor, mantido encriptado e auditado, em vez de uma nota num gestor de palavras-passe ou numa conversa de mensagens. Mantenha-o como a fonte de verdade: quando rodar uma chave junto do fornecedor, atualize-a aqui ao mesmo tempo, para que a próxima pessoa a implementar tenha o valor atual.
Eliminar um Segredo
Clique em Delete na linha. O KPanel pede-lhe para confirmar com Delete API_TOKEN? e avisa que a aplicação perderá o acesso a este valor no seu próximo reinício. Não há desfazer nem cópia guardada, por isso, se puder precisar do valor novamente, copie-o primeiro.
Elimine um segredo quando a credencial subjacente tiver sido revogada junto do fornecedor, ou quando o código que a usava tiver sido removido. Deixar chaves obsoletas por aí torna mais difícil perceber, mais tarde, quais delas realmente importam.
Rodar uma Credencial em Segurança
A ordem segura é sempre: criar a nova credencial junto do fornecedor, atualizá-la aqui, implementar, confirmar que a aplicação funciona e só depois revogar a credencial antiga junto do fornecedor.
Fazê-lo pela ordem inversa, revogando primeiro, dá-lhe uma janela em que a aplicação em execução fica com uma credencial morta e todos os pedidos que precisam dela falham. Se a alteração for arriscada, faça primeiro uma cópia de segurança para poder voltar a um estado conhecido e funcional: consulte Fazer uma Cópia de Segurança.
Resolução de Problemas
O separador Secrets não aparece no menu. O site não é um site Node.js. Verifique o emblema da stack junto ao nome do site no topo da página.
O botão Set não faz nada. Ambos os campos são obrigatórios. O botão mostra Chave + valor obrigatórios se algum deles estiver vazio.
A chave foi rejeitada. Letras minúsculas, hífenes, pontos e espaços não são permitidos. api-key e Api_Key falham ambos; API_KEY passa.
O Copy não colocou nada na área de transferência. Alguns browsers bloqueiam as escritas na área de transferência num separador inativo. Clique primeiro na página e depois clique novamente em Copy.
Para Onde Ir a Seguir
- Implementações de Pré-visualização Para Pull Requests, a outra metade da divisão entre produção e pré-visualização.
- Implementação Git Para um Site para enviar o código que lê estes valores.
- Registo de Atividade do Site para ver quem definiu, revelou ou eliminou um segredo.