v2.0
Docs › Segurança › Cofre de Senhas

Cofre de Senhas

O repositório seguro de credenciais do browserMate: cadastre senhas, API Keys e tokens uma única vez e use-os nos processos sem nunca expor o valor.

📍No Menu, na opção Meu Cofre de Senhas.
Nesta página

O que é o Cofre

O Cofre é o repositório seguro de credenciais e segredos do browserMate. Em vez de colocar senhas, API Keys e tokens diretamente no código ou nas configurações visíveis, você os cadastra no Cofre e os referencia por nome nos processos.

Acesse o Cofre no Menu, na opção Meu Cofre de Senhas.

Todos os valores gravados no Cofre são criptografados com AES-256-GCM através do Google Cloud KMS antes de chegar ao banco de dados. O valor em texto puro nunca é armazenado.

Regra de ouro Nunca coloque credenciais em texto puro em campos de texto de etapas, código inline ou documentação de processo. Sempre use o Cofre.

O que armazenar no Cofre

Criar uma credencial

  1. No Menu, acesse Meu Cofre de Senhas e clique em + Nova Credencial.
  2. Informe o Nome Credencial, que é como você reconhece a credencial na lista (ex.: Login sistema ERP), e a Chave de Acesso, o identificador que o agente usa para buscá-la: ex.: ERP.LOGIN, usado no fluxo como {vault.ERP.LOGIN}. A chave precisa ser única.
  3. Informe o Valor (a credencial em si). O campo é mascarado como senha. Se o segredo muda conforme o ambiente, marque Valores diferentes por ambiente (veja Valores por ambiente).
  4. Clique em Salvar. O valor é criptografado antes de ser armazenado.

Após salvar, o valor nunca mais é exibido em tela: apenas o nome da credencial fica visível.

Cofre corporativo (somente admin) Por padrão, uma credencial do Cofre é privada, e só quem a criou consegue usá-la. Apenas um admin vê a opção Tornar visível para toda a empresa ao criar ou editar uma credencial: uma vez marcada, ela fica disponível para os processos de qualquer usuário da empresa, mas o valor continua mascarado, e ninguém além de quem a criou vê a credencial em texto puro.

Valores por ambiente

Uma credencial pode ter um valor diferente para cada ambiente do agente: Desenvolvimento, Homologação e Produção. A chave continua uma só. No fluxo você escreve {vault.ACESSO.SAP} uma vez, e o valor que vale é o do ambiente em que o agente está.

  1. Ao criar ou editar a credencial, marque Valores diferentes por ambiente.
  2. Preencha o valor de cada ambiente. Pode deixar um deles vazio: a credencial passa a não atender aquele ambiente.
  3. Salve. No card aparecem as letras D, H e P, acesas nos ambientes que têm valor.
Editar Credencial no painel do Cofre do Agent Builder: Nome Credencial Portal de Compras, Chave de Acesso PORTAL.COMPRAS, Valores diferentes por ambiente marcado e um campo mascarado para cada ambiente, D, H e P
A credencial PORTAL.COMPRAS com Valores diferentes por ambiente: uma chave só e um valor para cada ambiente (D, H e P). Aqui no painel do Cofre dentro do Agent Builder, que tem também a aba Neste fluxo.

Sem a opção marcada, a credencial tem um valor só, que vale em qualquer ambiente. Ao editar, um campo deixado como está não muda; para tirar o valor de um ambiente, apague o conteúdo do campo dele.

O mesmo ambiente escolhe a máquina: o runtime tem uma instalação por ambiente, e o agente em Produção roda na instalação de Produção do runtime dele e lê o valor de Produção da credencial. É a mesma ideia nos dois lados: uma credencial de valor único vale nos três ambientes, como um runtime novo, que começa com uma instalação só para os três. Um agendamento ou uma chamada de API que fixa um ambiente usa os valores desse ambiente, qualquer que seja o do agente. No Agent Builder, os botões de ambiente Dev, Homolog e Prod, ao lado do campo RUNTIME, ganham uma pequena marca amarela em cada ambiente onde uma credencial do fluxo não tem valor, e passar o mouse sobre o botão mostra falta credencial do Cofre neste ambiente (veja Os botões Dev, Homolog e Prod).

Ambiente sem valor é erro, nunca troca por outro Se o agente está em Produção e a credencial não tem valor para Produção, a etapa falha dizendo isso: ACESSO.SAP não tem valor para Produção. A plataforma nunca usa o valor de outro ambiente no lugar. No editor isso aparece antes, como pendência, e a publicação fica bloqueada até você preencher o valor ou trocar o agente de ambiente.
Neste fluxo O painel do Cofre dentro do Agent Builder tem a aba Neste fluxo: ela lista as chaves que o fluxo usa, nas etapas e nos conectores (inclusive, na Etapa Agêntica, a chave do conector do modelo e as dos conectores usados como ferramenta), com o que cada uma tem em D, H e P e se vale no ambiente atual do agente.

O Testar de um conector lê a credencial com valores por ambiente no ambiente do agente quando o painel de Conectores é aberto pelo editor dele, o mesmo valor que a execução usa. Aberto fora de um agente, na tela Meus Conectores, o Testar usa o valor de Desenvolvimento.

Runtime desatualizado Um runtime antigo não informa em que ambiente o agente está, então não consegue abrir uma credencial com valores por ambiente: a etapa falha pedindo para atualizar o runtime. Credenciais de valor único continuam funcionando nele.

Onde a credencial pode ser usada

A credencial vale em qualquer ponto do agente em que uma senha, token ou chave de API faça sentido. Em todos eles você escreve a referência, nunca o segredo: o valor só é decifrado no instante da chamada.

OndeComo escrever
Etapa Preencher, Objeto de Tela Valor do Cofre{vault.CHAVE} no Valor
Etapa Chamar API Rest{vault.CHAVE} na URL, Header, Query String, Parâmetro e Valor do Body
Mapeamento de conector na etapa{vault.CHAVE} no campo
Campos de credencial do conector{{vault.CHAVE}} no lugar da senha ou do token
Código Node.js e Pythonbm.secret('CHAVE')
Script de Sessãoawait bm.secret('CHAVE')
Campo inteiro ou no meio de um texto No mapeamento de conector na etapa e na Chamar API Rest, a referência pode ocupar o campo sozinha, {vault.CHAVE}, ou vir no meio de um texto: Bearer {vault.TOKEN}. A exceção são os Parâmetros de URL da Chamar API Rest, onde ela ocupa o campo inteiro. Nos campos do próprio conector, inclusive senha, token, Base URL e host, a referência leva chave dupla, {{vault.CHAVE}}, e também vale sozinha ou no meio de um texto.
Dentro de um script a sintaxe é outra Em Node.js e Python, {vault.CHAVE} não é substituído por nada: dentro de um script ninguém interpola {...}. Ali a credencial vem de bm.secret('CHAVE'), e a chave pode ser montada em tempo de execução, o que atende o agente que serve vários clientes com uma credencial para cada um. Veja Mini SDK.
Chave errada derruba a etapa, e isso é proposital Se a chave não existir, existir sem valor, ou não tiver valor para o ambiente em que o agente está, a etapa falha dizendo qual chave e qual campo. O contrário seria enviar a requisição sem credencial e receber um erro de autenticação genérico da outra ponta, com o usuário procurando o problema no lugar errado.

Usar uma credencial num mapeamento

No mapeamento de uma etapa Preencher, defina o Objeto de Tela como Valor do Cofre. O campo Valor passa a listar as chaves disponíveis, e a escolhida é gravada como {vault.nome_da_credencial}:

Mapeamento de uma etapa Preencher usando uma credencial do Cofre
Com o Objeto de Tela em Valor do Cofre e o Valor apontando para {vault.PORTAL.COMPRAS}, o runtime busca a credencial já decifrada e digita direto no campo.

Nesse momento, o runtime busca o valor decifrado da credencial PORTAL.COMPRAS e o digita no elemento do Seletor. O valor em claro passa direto para a página, sem nunca ser gravado numa variável do processo nem aparecer em log. Veja o campo Objeto de Tela em Mapeamento em Preencher.

Sem Valor do Cofre, a referência vira texto

Escrever {vault.chave} num campo cujo Objeto de Tela é outro não consulta o Cofre: o agente repassa o texto como está, e a página recebe {vault.chave} com chaves e tudo, no lugar da senha.

O segredo não vira variável do processo Em nenhum dos lugares da tabela acima o valor decifrado é gravado no fluxo. Ele existe apenas durante a chamada e desaparece com ela. É por isso que o segredo não aparece na massa de dados do debug, no retomar de uma tarefa, nem no arquivo que o script recebe. No log ele sai mascarado, inclusive quando a API do outro lado o repete na resposta.
E o dado que não é uma credencial? O Cofre guarda o que você já conhece antes de executar. Um CPF lido da tela ou um token que a API acabou de emitir não passam por ele. Para esses, marque a linha como dado sensível: veja Dados Sensíveis.

A decifragem acontece no servidor, no momento da execução. Detalhes em KMS.

Uso em Conectores

Campos de senha em conectores são protegidos pelo mesmo mecanismo. Quando você preenche um campo sensível em um conector (API Key, senha, refresh token) e salva, o valor é criptografado automaticamente antes de chegar ao banco de dados. Valor escrito como variável ({{senha}}, {{vault.CHAVE}}) é modelo, não credencial: fica em texto puro e legível, e o valor de verdade entra só na execução. Veja Criptografia em Conectores.

Além de digitar a credencial no conector, você pode apontá-la para o Cofre: escreva {{vault.CHAVE}} no campo de senha, token ou API Key, e o conector passa a buscar o valor no Cofre a cada execução. Vale a pena quando a mesma credencial é usada por vários conectores ou agentes, porque a troca acontece num lugar só.

Conector compartilhado usa o Cofre de quem é dono do conector Se o conector foi publicado para a empresa por um admin, a credencial é procurada no Cofre dele, não no de quem executa. É o comportamento certo: quem publicou o conector é quem responde pela credencial dele.

O campo Mapear da etapa também aceita {vault.CHAVE}, para quando o segredo é um dado de entrada da ação e não a credencial de conexão.

O que pode estar na documentação interna

Ao criar documentação interna dos seus processos, é seguro registrar:

Pode documentarNÃO documente
Nome da credencial no Cofre (openai_api_key) O valor da credencial em si
Qual conector é usado e para quê API Keys, tokens, senhas de conectores
URLs de sistemas integrados Senhas de login dos sistemas
Descrição do fluxo e regras de negócio Credenciais AWS (Access Key / Secret)
Parâmetros esperados pelo processo Refresh Tokens OAuth
Resultado esperado e logs de sucesso Chaves privadas ou certificados