---
title: Proteção por senha
description: Proteja todo o seu site de documentação ou apenas algumas páginas com uma senha compartilhada, mantendo o restante do conteúdo aberto.
---
> **For AI agents:** the complete documentation index is at [llms.txt](/docs/llms.txt). Append `.md` to any page URL for its markdown version.
Às vezes, você quer uma documentação que permaneça no Git e online, mas não fique visível para todos. Exemplos comuns incluem runbooks, guias de pré-lançamento, documentação exclusiva para parceiros e recursos de acesso antecipado. A proteção por senha fornece uma única senha compartilhada que controla o acesso a todo o site ou a um conjunto específico de páginas, sem mover nada do seu repositório existente.
As capturas de tela mostram a interface em inglês.
Precisa de autenticação por usuário? A [autenticação JWT](/pt/setup/jwt-authentication) protege sua documentação usando seu próprio sistema de login em vez de uma senha compartilhada, com sessões por usuário e acesso a páginas baseado em grupos.
Você precisará de um projeto Jamdesk [conectado a um repositório Git](/pt/setup/connecting-github) antes de ativar a proteção por senha. A configuração fica em `docs.json`, então a proteção por senha aproveita seu fluxo normal de build e deploy.
## Qual modo devo escolher?
O Jamdesk tem dois modos de proteção por senha. Escolha um com base no que é público e no que não é.
| | **Modo para todo o site** | **Modo para páginas específicas** |
|---|---|---|
| **Use quando** | Tudo é privado: documentação interna de engenharia, uma cópia de staging do seu site público ou um produto ainda não lançado. | A maior parte da documentação é pública. Você só precisa ocultar algumas páginas (um runbook, um recurso beta ou uma referência de API interna). |
| **Como ativar** | Defina `auth.password.enabled: true` em `docs.json`. | Marque as páginas como privadas com `private: true` no frontmatter ou liste os caminhos em `auth.password.private[]`. |
| **Exceções públicas** | Sim: marque páginas individuais, grupos de navegação ou padrões glob como públicos. | N/A. Todas as páginas são públicas, a menos que você as marque como privadas. |
Ambos os modos compartilham o mesmo cartão no dashboard, a mesma tela de desbloqueio e os mesmos controles de rotação e revogação. Você pode alternar entre eles a qualquer momento editando `docs.json` e fazendo push.
## Proteja todo o seu site
Abra seu `docs.json` e declare a proteção de todo o site. O campo `hint` é opcional, mas altamente recomendado, pois é a única indicação na tela que seus leitores terão sobre como obter a senha.
```json docs.json
{
"$schema": "https://jamdesk.com/docs.json",
"name": "Acme Docs",
"theme": "jam",
"auth": {
"password": {
"enabled": true,
"hint": "Ask #docs-access on Slack"
}
}
}
```
As dicas são texto simples, com no máximo 200 caracteres e sem HTML.
Não coloque a senha em si no `docs.json`. Você define a senha no dashboard após o build. Seu repositório contém apenas a flag de ativação e uma dica opcional.
Faça push da alteração para sua branch configurada. O Jamdesk executa um build e, durante o build, ativa a proteção por senha no modo para todo o site.
```bash
git add docs.json
git commit -m "Turn on password protection"
git push
```
Após a conclusão do build, o cartão do dashboard muda de **Off** para **Password not set**, e o site retorna `401` para todas as páginas. Até que você defina uma senha, todas as requisições serão rejeitadas.
Abra **Project Settings** no dashboard e role até o cartão **Password Protection**. Digite uma senha forte (mínimo de 8 caracteres) e clique em **Set password**.
O cartão muda para o estado **On**. Agora, qualquer pessoa que tenha a senha pode navegar pelo site; as demais verão a tela de desbloqueio.
O Jamdesk nunca armazena sua senha em texto simples. Ela recebe hash com scrypt no banco de dados do dashboard e nunca é gravada no seu repositório ou em `docs.json`. Isso também significa que o Jamdesk não pode enviá-la por e-mail se você esquecê-la. Faça a rotação.
Abra seu site de documentação em uma janela privada do navegador (ou use `curl`) e confirme que a tela de desbloqueio é exibida. Tente uma senha incorreta para verificar o estado de erro e, em seguida, a senha correta para entrar.
```bash
# Should respond with HTTP/1.1 401 and the unlock HTML
curl -I https://acme.jamdesk.app/
# Submit the password. On success, sets the jd_auth_ cookie.
curl -i -X POST https://acme.jamdesk.app/jd/unlock \
-d "password=your-passphrase&from=/"
```
Um desbloqueio bem-sucedido retorna um redirecionamento `303` com um cabeçalho `Set-Cookie: jd_auth_acme=...; HttpOnly; Secure; SameSite=Lax; Max-Age=2592000`. Salve esse cookie para a próxima requisição e você estará dentro.
### Exceções públicas
O modo para todo o site tem uma alternativa: você pode manter páginas específicas públicas mesmo enquanto o restante do site está protegido. É assim que você publica uma landing page de marketing ou um formulário de cadastro junto com a documentação privada.
Você tem três maneiras de marcar uma página como pública, e todas são combinadas na mesma lista de permissões em cada build.
**Frontmatter** é a opção mais granular. Adicione `public: true` a qualquer arquivo `.mdx` e somente essa página ficará fora da proteção:
```yaml
---
title: Get started
public: true
---
```
**Grupos de navegação** abrangem uma seção inteira de uma só vez. Defina `public: true` em um `group` ou `tab` na navegação do `docs.json`, e todas as páginas abaixo dele serão públicas. Útil para uma aba "Marketing" ao lado da documentação privada de engenharia:
```json docs.json
{
"navigation": {
"tabs": [
{
"tab": "Marketing",
"public": true,
"groups": [
{
"group": "Overview",
"pages": ["landing", "pricing", "changelog"]
}
]
},
{
"tab": "Internal",
"groups": [
{ "group": "Runbooks", "pages": ["deploys", "oncall"] }
]
}
]
}
}
```
**Globs explícitos** em `auth.password.public[]` lidam com tudo que o frontmatter e a navegação não conseguem: landing pages no nível superior, rotas geradas dinamicamente ou uma árvore inteira que você prefere não reescrever.
```json docs.json
{
"auth": {
"password": {
"enabled": true,
"hint": "Ask #docs-access on Slack",
"public": [
"/landing",
"/pricing",
"/marketing/**",
"/blog/*"
]
}
}
}
```
Os globs aceitam `*` (um segmento de caminho) e `**` (qualquer profundidade). Uma `/` isolada é rejeitada na validação: se o Jamdesk a aceitasse, um simples erro de digitação poderia desbloquear silenciosamente todo o seu site. Após cada build, o cartão do dashboard mostra a lista de permissões resolvida, para que você possa verificar o que o build realmente identificou.
## Proteja apenas algumas páginas
O modo para páginas específicas usa o fluxo oposto: tudo é público por padrão, e você opta por incluir páginas individuais na proteção.
Adicione `private: true` ao frontmatter da página. Essa é a opção mais simples quando a decisão fica a cargo de quem é responsável pela página.
```yaml
---
title: Incident Runbook
description: What to do when the deploys dashboard is on fire.
private: true
---
```
Ou, se preferir manter a lista de caminhos protegidos em um único arquivo, adicione-os em `auth.password.private[]` no `docs.json`. As duas abordagens são cumulativas, então você pode combiná-las.
```json docs.json
{
"auth": {
"password": {
"hint": "Ask the on-call engineer",
"private": ["/admin/runbook", "/internal/api-keys"]
}
}
}
```
Observe que não há `enabled: true`. Definir `auth.password.private[]` sem `enabled` é o que ativa automaticamente o modo para páginas específicas.
Faça push das alterações. O próximo build detecta as páginas privadas, ativa a proteção no modo para páginas específicas e exibe no dashboard a solicitação para definir uma senha, exatamente como no modo para todo o site.
```bash
git add content/runbook.mdx docs.json
git commit -m "Gate the incident runbook"
git push
```
Abra **Project Settings**, encontre o cartão **Password Protection** e defina uma senha. O cabeçalho do cartão agora mostra **On** com **Specific pages** em vez de **Whole site**, além de exibir a lista de páginas privadas resolvida pelo build para que você possa auditá-la rapidamente.
Navegue normalmente pelo seu site de documentação. As páginas públicas devem carregar como antes; as páginas privadas devem redirecionar você para a tela de desbloqueio. Depois que inserir a senha, você ficará conectado por 30 dias nesse dispositivo e poderá ler qualquer página privada sem digitá-la novamente.
## O que os visitantes veem
Quando alguém acessa uma página protegida, vê um cartão de desbloqueio centralizado. Ele mostra apenas o nome do site e uma dica opcional, sem barra lateral ou navegação.
O cartão usa o logotipo e a cor primária do seu site definidos em `docs.json`. O campo de senha tem um controle para revelar o conteúdo e recebe foco automaticamente.
Senhas incorretas exibem o mesmo cartão com uma mensagem de erro, um campo vazio e um pequeno atraso entre as tentativas. Uma senha incorreta e uma requisição sem senha levam à mesma tela, portanto nada na página diferencia "senha incorreta" de "nenhuma senha inserida ainda".
Depois que o visitante insere a senha correta, recebe um cookie assinado e pode navegar normalmente até a sessão expirar ou você revogá-la.
## Rotação e revogação de sessões
Uma senha compartilhada eventualmente precisa ser alterada, por exemplo, depois de ser compartilhada com muitas pessoas ou quando alguém deixa a equipe.
Abra o cartão **Password Protection**, digite uma nova senha no campo **Rotate password** e clique em **Save new password**. Todas as pessoas com a senha antiga perderão o acesso na próxima requisição; quem tiver a nova senha poderá entrar. A rotação entra em vigor imediatamente e não exige um novo build.
Se quiser apenas forçar o logout de todas as sessões ativas sem alterar a senha (por exemplo, se o laptop de alguém desapareceu), clique em **Revoke all sessions**. Isso incrementa um contador de versão no servidor, invalidando todos os cookies emitidos antes do incremento. Os visitantes inserem novamente a senha atual e recuperam o acesso.
## Desativação da proteção
A proteção é controlada pelo `docs.json`, portanto desativá-la significa editar o arquivo e fazer push.
- **Todo o site:** remova `auth.password.enabled` (ou defina-o como `false`).
- **Páginas específicas:** remova todos os marcadores `private: true` e limpe `auth.password.private`.
No próximo build, o Jamdesk exclui o hash de senha armazenado e retorna o cartão ao estado **Off**. Nenhum estado "inativo" permanece. Se você reativar a proteção posteriormente, precisará escolher uma nova senha.
Seu repositório de origem não é protegido por senha. A proteção por senha controla o acesso ao site de documentação hospedado em `*.jamdesk.app` (ou no seu domínio personalizado). Se seu repositório do GitHub for público, o conteúdo MDX continuará legível lá. Torne o repositório privado se precisar de proteção completa do conteúdo.
## Regras de precedência
Uma única página pode ser afetada por vários sinais ao mesmo tempo. A ordem de resolução, da mais específica para a menos específica, é:
- Se `auth.password.enabled` for `true`, todo o site será protegido. `private: true` em páginas individuais se torna redundante.
- Se uma página for marcada como `public: true` e `private: true`, **public vence**. O padrão mais seguro é aquele que não expõe uma página por acidente.
- `public: true` no frontmatter, `public: true` em grupos de navegação e os globs de `auth.password.public[]` são combinados em uma única lista de permissões. Não existe uma regra de "vence o mais específico". Se qualquer sinal indicar que uma página é pública, ela será pública.
- Se `auth.password.private[]` estiver definido, mas `auth.password.enabled` não estiver, o Jamdesk ativará automaticamente o modo para páginas específicas. Você não precisa fazer mais nada.
## Como funcionam as sessões e a limitação de taxa
Esta seção aborda o cookie de sessão, os limites de taxa e o armazenamento da senha.
**O cookie de sessão.** Após um desbloqueio bem-sucedido, o Jamdesk define um cookie chamado `jd_auth_` (por exemplo, `jd_auth_acme`). Ele é `HttpOnly`, `Secure`, `SameSite=Lax`, limitado ao host e assinado com HMAC-SHA256. O payload inclui o slug do projeto, o contador de versão atual e um registro de data e hora de expiração, portanto qualquer adulteração falha na validação. A duração padrão é de **30 dias**, renovada a cada desbloqueio bem-sucedido.
**Limitação de taxa.** O endpoint de desbloqueio aplica dois contadores por hora: **10 tentativas por IP** e **100 tentativas por projeto**. Ambos são aplicados antes da verificação do hash scrypt, para que uma tentativa de força bruta não consuma CPU nem revele informações de tempo. Atingir qualquer um dos limites retorna `429 Too Many Requests` com um cabeçalho `Retry-After`.
**Armazenamento.** Sua senha recebe hash com scrypt e é armazenada no Firestore do dashboard. Ela nunca chega ao seu repositório, ao seu `docs.json` ou a um artefato de build. Se você perdê-la, faça a rotação. Não existe caminho de recuperação.
## Testes durante o desenvolvimento local
`jamdesk dev` executa sua documentação usando o conteúdo R2 ativo e a configuração ativa. A proteção por senha **não é aplicada** no servidor de desenvolvimento local, para que você possa visualizar páginas protegidas sem saber a senha. Isso é intencional: você é o autor, já tem as chaves do repositório, e bloquear a visualização local com uma barreira de senha criaria atrito sem benefício de segurança.
Se quiser verificar a proteção real, acesse o site publicado em `.jamdesk.app` (ou seu domínio personalizado) usando uma janela do navegador que ainda não tenha o cookie.
## Solução de problemas
O cartão do dashboard provavelmente está mostrando **Password not set**. A proteção só é ativada depois que você (1) faz push da configuração para `docs.json` e (2) define uma senha em **Project Settings**. Até que a segunda etapa seja concluída, todas as requisições retornam `401` com a tela de desbloqueio no corpo, o que pode dar a impressão de que a tela "não aparece" se você esperava um destino específico.
O navegador dele tem um cookie `jd_auth_` antigo, criado antes da rotação. Aguarde 30 dias até o cookie expirar, clique em **Revoke all sessions** no dashboard ou peça que ele limpe os cookies do domínio da documentação. Na próxima visita, será solicitada a senha atual.
Não diretamente. O Jamdesk usa uma única senha compartilhada por site. Se precisar de acesso por grupo, divida sua documentação em vários projetos (cada um com sua própria senha) ou use o modo para páginas específicas, com limites públicos e privados separados para cada público.
Sim para ambos. O cookie de desbloqueio é vinculado ao host, portanto cada host (o subdomínio `*.jamdesk.app` e seu domínio personalizado) é autenticado de forma independente. Leitores que desbloquearem um host não serão pré-autenticados no outro.
Configurações de subcaminho (documentação em `yoursite.com/docs` atrás do seu próprio proxy) funcionam imediatamente: o formulário de desbloqueio é enviado usando o prefixo de caminho `/_jd/`, que toda configuração de proxy documentada já encaminha. Nenhuma alteração no proxy é necessária ao ativar ou desativar a proteção por senha.
Se o proxy foi configurado antes de o encaminhamento de `/_jd/` fazer parte do guia de configuração, adicione `/_jd/*` aos caminhos encaminhados.
Não. Sites protegidos definem `noindex, nofollow` na tela de desbloqueio e retornam `401` para todas as páginas protegidas, portanto os rastreadores de busca não conseguem indexar nada atrás da proteção. Páginas públicas dentro de um site protegido continuam indexáveis normalmente.
## O que vem a seguir?
Compare a proteção por senha com SSO e o padrão de vários projetos.
Substitua a senha compartilhada por sessões por usuário do seu próprio sistema de login.
Substitua senhas compartilhadas pelo login por usuário usando seu provedor de identidade.
Coloque sua documentação no seu próprio domínio antes de compartilhar o link.
Referência completa dos campos `enabled`, `hint`, `public` e `private`.