<?xml version="1.0" encoding="utf-8" standalone="yes"?><rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:webfeeds="http://webfeeds.org/rss/1.0"><channel><title>totp | Self-Hosted!</title><link>https://blog.brumarino.com/tags/totp/</link><description>Post novo no “Rack” de segunda a sexta, às 7AM. Proxmox, rede, backup, UPS, IA e tudo o que tenho estudado.</description><language>pt-BR</language><managingEditor>Bruno Marino</managingEditor><image><url>https://blog.brumarino.com/brand/icon-144.png</url><title>totp | Self-Hosted!</title><link>https://blog.brumarino.com/tags/totp/</link><width>144</width><height>144</height></image><webfeeds:icon>https://blog.brumarino.com/brand/icon-192.png</webfeeds:icon><webfeeds:logo>https://blog.brumarino.com/brand/symbol.svg</webfeeds:logo><webfeeds:accentColor>2B3036</webfeeds:accentColor><lastBuildDate>Tue, 17 Nov 2026 07:00:00 -0300</lastBuildDate><atom:link href="https://blog.brumarino.com/tags/totp/index.xml" rel="self" type="application/rss+xml"/><item><title>2FA no Proxmox: TOTP e chaves de recuperação no login</title><link>https://blog.brumarino.com/proxmox-2fa-totp/</link><pubDate>Tue, 17 Nov 2026 07:00:00 -0300</pubDate><guid>https://blog.brumarino.com/proxmox-2fa-totp/</guid><category>Backup e segurança</category><description>Como ligar o 2FA com TOTP no Proxmox VE 9, gerar as chaves de recuperação e voltar pelo pveum se você perder o celular ou o login for bloqueado.</description><content:encoded><![CDATA[<p>A interface web do Proxmox é a chave do homelab inteiro. Quem entra nela como <code>root@pam</code> pode apagar containers, restaurar backups por cima, abrir um console em qualquer guest e mexer na rede. E, por padrão, ela pede só usuário e senha.</p>
<p>O Proxmox já traz <strong>autenticação em dois fatores (2FA)</strong> pronta, sem instalar nada. Neste post mostro como ligar o TOTP, por que gerar as chaves de recuperação logo em seguida e o que fazer se o celular sumir. Tudo pela documentação oficial do Proxmox VE 9.</p>
<h2 id="os-tipos-de-segundo-fator">Os tipos de segundo fator <a class="anchor" href="#os-tipos-de-segundo-fator" aria-label="Link para esta seção">#</a></h2>
<p>Pela documentação, cada usuário pode configurar sozinho três tipos:</p>
<table>
	<thead>
			<tr>
					<th>Tipo</th>
					<th>O que é</th>
					<th>Precisa de preparo no servidor?</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><strong>TOTP</strong></td>
					<td>Código de 6 dígitos que muda a cada 30 segundos, num app do celular</td>
					<td>Não</td>
			</tr>
			<tr>
					<td><strong>WebAuthn</strong></td>
					<td>Chave física (YubiKey e similares) ou o próprio aparelho, como passkey</td>
					<td>Sim: certificado HTTPS confiável e configuração do WebAuthn</td>
			</tr>
			<tr>
					<td><strong>Chaves de recuperação</strong></td>
					<td>Lista de códigos de uso único, para emergência</td>
					<td>Não</td>
			</tr>
	</tbody>
</table>
<p>Existe ainda o <strong>YubiKey OTP</strong>, mas ele é configurado no <em>realm</em> inteiro e exige uma API da Yubico ou um servidor próprio de validação. Para um homelab, eu começaria pelo TOTP mais as chaves de recuperação, que não exigem nada além de um app de autenticação.</p>
<h2 id="ligando-o-totp">Ligando o TOTP <a class="anchor" href="#ligando-o-totp" aria-label="Link para esta seção">#</a></h2>
<p>O caminho na interface:</p>
<ol>
<li>Entre como o usuário que vai ganhar o segundo fator.</li>
<li>Abra <strong>Datacenter → Permissions → Two Factor</strong>.</li>
<li>Clique em <strong>Add → TOTP</strong>.</li>
<li>Dê uma <strong>Description</strong> (por exemplo, o nome do celular). Em <strong>Secret</strong>, use <strong>Randomize</strong> para gerar a chave. O campo <strong>Issuer Name</strong> é opcional e ajuda a identificar a conta no app (por exemplo, <code>pve-casa</code>).</li>
<li>Leia o <strong>QR code</strong> com o app de autenticação do celular.</li>
<li>Digite o código que o app mostrar em <strong>Verify Code</strong>. Fora do <code>root</code>, o Proxmox também pede a senha atual.</li>
<li>Clique em <strong>Add</strong>.</li>
</ol>
<figure class="prose-figure">
  <img src="/proxmox-2fa-totp/totp_hu_6a5ffedc25be4336.webp" alt="Janela Add a TOTP login factor do Proxmox VE, com usuário, descrição, chave secreta, QR code e código de verificação" loading="lazy" width="512" height="506"><figcaption>Janela de cadastro do TOTP. Imagem: Proxmox VE (GNU FDL).</figcaption>
</figure><p>A documentação cita o FreeOTP como exemplo de app, mas qualquer app TOTP padrão funciona. Se você já usa um gerenciador de senhas que gera códigos TOTP, como o Vaultwarden, ele também serve. Só pense bem antes de colocar o segundo fator no mesmo lugar da senha: se esse cofre vazar, os dois fatores vazam juntos. Falei do cofre da família no post sobre <a href="/vaultwarden-familia-homelab/">o Vaultwarden no homelab</a>.</p>
<aside class="alert alert--tip">
  <p class="alert__title">Dica</p>
  <p>Antes de fechar a aba, abra uma janela anônima e faça login de novo. Se o código não for aceito, você ainda tem a sessão antiga aberta para desfazer. Relógio errado no servidor é a causa mais comum, porque o TOTP depende da hora.</p>
</aside><h2 id="as-chaves-de-recuperação-logo-em-seguida">As chaves de recuperação, logo em seguida <a class="anchor" href="#as-chaves-de-recupera%c3%a7%c3%a3o-logo-em-seguida" aria-label="Link para esta seção">#</a></h2>
<p>Este é o passo que muita gente pula. Se o celular quebrar ou for perdido, o TOTP vai junto, e você fica do lado de fora.</p>
<p>As chaves de recuperação não exigem preparo. No mesmo painel, <strong>Datacenter → Permissions → Two Factor</strong>, clique em <strong>Add → Recovery Keys</strong>. O Proxmox mostra uma lista de códigos:</p>
<ul>
<li>cada código <strong>funciona uma vez só</strong>;</li>
<li>cada usuário tem <strong>um conjunto de cada vez</strong>: gerar outro substitui o anterior.</li>
</ul>
<p>Guarde essa lista longe do celular: impressa numa gaveta, num cofre de senhas que não dependa do celular ou nos dois. É a mesma lógica do backup: a cópia de emergência não pode estar no mesmo lugar do original, como contei no post sobre <a href="/raid-nao-e-backup/">RAID e backup</a>.</p>
<h2 id="o-bloqueio-por-tentativas">O bloqueio por tentativas <a class="anchor" href="#o-bloqueio-por-tentativas" aria-label="Link para esta seção">#</a></h2>
<p>O segundo fator protege contra senha vazada, mas um código de 6 dígitos poderia ser descoberto por força bruta. Por isso o Proxmox bloqueia depois de muitas tentativas erradas. Pela documentação:</p>
<ul>
<li><strong>TOTP:</strong> depois de <strong>8 tentativas erradas</strong>, os fatores TOTP do usuário são desativados. Eles voltam quando o usuário entra com uma <strong>chave de recuperação</strong>.</li>
<li><strong>WebAuthn e chaves de recuperação:</strong> o limite é maior, <strong>100 tentativas</strong>, mas quando estoura, <strong>todos os segundos fatores</strong> ficam bloqueados por <strong>uma hora</strong>.</li>
</ul>
<p>Se o TOTP era o único fator e foi bloqueado, só um administrador resolve. A própria documentação recomenda, nesse caso, pedir a troca de senha na hora: 8 erros seguidos no código, depois de a senha estar certa, é um bom sinal de que alguém tem a sua senha.</p>
<h2 id="perdi-o-celular-como-voltar">Perdi o celular: como voltar <a class="anchor" href="#perdi-o-celular-como-voltar" aria-label="Link para esta seção">#</a></h2>
<p>Se você ainda tem as chaves de recuperação, entre com uma delas no lugar do código e configure um TOTP novo.</p>
<p>Se não tem, o caminho é pelo <strong>shell do host</strong>. O 2FA da interface web não vale para o SSH, que segue as regras do <code>sshd</code>. Por isso, acesso por SSH com chave é o seu plano B. No meu caso, o SSH do host passa pelo Cloudflare Tunnel, como contei no post sobre <a href="/ssh-cloudflare-tunnel-proxyjump/">SSH sem porta 22 aberta</a>.</p>
<p>Pelo terminal do host, o <code>pveum</code> resolve:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Ver os segundos fatores configurados</span>
</span></span><span class="line"><span class="cl">pveum user tfa list root@pam
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Destravar um usuário bloqueado por tentativas</span>
</span></span><span class="line"><span class="cl">pveum user tfa unlock root@pam
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Remover os segundos fatores do usuário (todos, se não passar --id)</span>
</span></span><span class="line"><span class="cl">pveum user tfa delete root@pam
</span></span></code></pre></div><p>O <code>unlock</code> só tira o bloqueio por tentativas. O <code>delete</code> remove o fator, e aí você configura um novo pela interface.</p>
<aside class="alert alert--caution">
  <p class="alert__title">Cuidado</p>
  <p>O <code>pveum user tfa delete</code> sem <code>--id</code> apaga <strong>todos</strong> os segundos fatores do usuário, inclusive as chaves de recuperação. Rode o <code>list</code> antes, confira o ID e, se puder, remova só o que perdeu.</p>
</aside><h2 id="exigir-2fa-para-todo-mundo">Exigir 2FA para todo mundo <a class="anchor" href="#exigir-2fa-para-todo-mundo" aria-label="Link para esta seção">#</a></h2>
<p>Se mais alguém tem acesso ao Proxmox, dá para tornar o segundo fator <strong>obrigatório</strong> por realm. Ao editar o realm (em <strong>Datacenter → Permissions → Realms</strong>), escolha o tipo no campo <strong>TFA</strong>. A partir daí, só entra quem já tiver o segundo fator configurado.</p>
<p>Cuidado com a ordem: configure o 2FA dos usuários <strong>antes</strong> de exigir. Se você exigir primeiro, quem ainda não configurou fica do lado de fora, possivelmente incluindo você.</p>
<h2 id="e-o-webauthn">E o WebAuthn? <a class="anchor" href="#e-o-webauthn" aria-label="Link para esta seção">#</a></h2>
<p>O WebAuthn é mais forte contra phishing, porque a chave confere o endereço do site. Mas ele pede duas coisas:</p>
<ul>
<li><strong>certificado HTTPS confiável</strong>, como um da Let&rsquo;s Encrypt. Com o certificado autoassinado padrão, alguns navegadores avisam ou recusam;</li>
<li>a configuração em <strong>Datacenter → Options → WebAuthn Settings</strong>, com o domínio pelo qual você acessa o Proxmox.</li>
</ul>
<p>A documentação avisa: <strong>mudar essa configuração depois pode invalidar todas as chaves já registradas</strong>. Se você acessa o Proxmox por IP hoje e pensa em trocar para um nome, decida o nome antes de registrar as chaves.</p>
<h2 id="resumindo">Resumindo <a class="anchor" href="#resumindo" aria-label="Link para esta seção">#</a></h2>
<ul>
<li><strong>O 2FA já vem no Proxmox.</strong> TOTP não exige nada no servidor.</li>
<li><strong>Caminho:</strong> Datacenter → Permissions → Two Factor → Add → TOTP.</li>
<li><strong>Gere as chaves de recuperação na mesma hora</strong> e guarde longe do celular.</li>
<li><strong>Bloqueio:</strong> 8 erros no TOTP desativam o fator. 100 erros nos outros bloqueiam tudo por uma hora.</li>
<li><strong>Plano B:</strong> SSH com chave no host e <code>pveum user tfa unlock</code> ou <code>delete</code>.</li>
<li><strong>WebAuthn:</strong> só com HTTPS confiável e o domínio decidido antes.</li>
</ul>
<p>Para um painel que controla todos os serviços da casa, são cinco minutos de configuração bem gastos.</p>
]]></content:encoded></item></channel></rss>