Docsbook
Visão geral

Documentação privada: palavra-passe e SSO

Por predefinição, um site Docsbook é público — qualquer pessoa com o link pode lê-lo. Pode mudar um espaço de trabalho para privado e exigir que os leitores o desbloqueiem primeiro, seja com uma palavra-passe partilhada ou iniciando sessão através do seu próprio fornecedor de identidade.

O controlo de acesso não utiliza nenhum modelo de IA, portanto restringir o acesso a um espaço de trabalho não consome o saldo do projeto.

Como funciona o modo privado#

  • Público (padrão) — qualquer pessoa com o link pode ler o site, assim como hoje.
  • Privado — um leitor anônimo vê uma tela de desbloqueio em vez do seu conteúdo. Nada sobre a documentação (estrutura, páginas, índice de pesquisa) é exposto até que ele a desbloqueie.
  • O proprietário sempre tem acesso total, independentemente da visibilidade — a barreira se aplica apenas a todas as outras pessoas.
  • Você pode configurar uma senha, SSO ou ambos ao mesmo tempo. Se ambos estiverem configurados, o leitor escolhe aquele que tiver.

Opção 1: proteção por senha#

A opção mais simples — defina uma senha compartilhada para todo o espaço de trabalho.

  1. Abra sua documentação enquanto estiver conectado
  2. Clique no Float Widget no canto inferior direito → Configurações → Privacidade & Acesso
  3. Altere a visibilidade para Privado
  4. Digite uma senha (com pelo menos 8 caracteres) e clique em Definir

Os leitores que inserirem a senha correta permanecem desbloqueados por um tempo, portanto não precisam inseri-la novamente a cada visita. Para alterar a senha, defina uma nova da mesma maneira. Para remover a proteção por senha, clique em Remover ao lado do campo de senha.

Opção 2: SSO com seu próprio provedor de identidade#

O SSO do Docsbook é exclusivamente OIDC. Você registra um aplicativo OIDC com seu próprio provedor de identidade e insere os detalhes abaixo; os leitores então entram com a conta de trabalho que já possuem, em vez de uma senha compartilhada. O Docsbook nunca vê nem armazena as credenciais de administrador do seu provedor — apenas os detalhes do aplicativo OAuth que você insere.

SAML não é compatível. Se o seu provedor de identidade estiver configurado para SAML e não puder emitir um registro de aplicativo OIDC, a proteção por senha é a opção disponível para você hoje. O Docsbook lista SAML como planejado, não lançado, e esta página descreve apenas o que funciona agora.

Você precisará dos seguintes dados, obtidos no registro do aplicativo do seu provedor de identidade:

Campo O que é
URL do emissor O identificador do emissor OIDC do seu provedor
ID do cliente O identificador público do registro do aplicativo
Segredo do cliente O segredo do registro do aplicativo (armazenado criptografado e nunca exibido novamente após ser salvo)
Endpoint de autorização Para onde os leitores são enviados para entrar
Endpoint de token Onde o Docsbook troca o código de entrada por um token de identidade
URI do JWKS Onde o Docsbook verifica a assinatura do token de identidade
Domínio permitido (opcional) Restringe a entrada a um domínio de e-mail, por exemplo, acme.com — qualquer pessoa fora dele é rejeitada mesmo com credenciais válidas do IdP

Configurar o Google Workspace#

  1. No Google Cloud Console, crie um ID do cliente OAuth 2.0 (tipo: aplicativo da Web)
  2. Adicione o URI de redirecionamento: https://docsbook.io/api/workspaces/<workspace_id>/access/sso/callback (seu ID do workspace é exibido no painel Privacidade & Acesso)
  3. Use estes endpoints padrão do Google:
    • Emissor: https://accounts.google.com
    • Endpoint de autorização: https://accounts.google.com/o/oauth2/v2/auth
    • Endpoint de token: https://oauth2.googleapis.com/token
    • URI do JWKS: https://www.googleapis.com/oauth2/v3/certs
  4. Defina o Domínio permitido como o domínio do seu Google Workspace (por exemplo, acme.com) para restringir o login à sua organização

Configurar o Microsoft Entra ID#

  1. No Centro de administração do Entra, registre um novo aplicativo
  2. Adicione o URI de redirecionamento: https://docsbook.io/api/workspaces/<workspace_id>/access/sso/callback
  3. Crie um segredo do cliente em Certificados & segredos
  4. Use os endpoints OIDC do seu locatário (encontrados em Endpoints na visão geral do aplicativo), normalmente:
    • Emissor: https://login.microsoftonline.com/<tenant-id>/v2.0
    • Endpoint de autorização: https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/authorize
    • Endpoint de token: https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token
    • URI do JWKS: https://login.microsoftonline.com/<tenant-id>/discovery/v2.0/keys

Configurar o Okta#

  1. No console de administração do Okta, crie uma nova integração OIDC – Aplicação Web
  2. Adicione o URI de redirecionamento de início de sessão: https://docsbook.io/api/workspaces/<workspace_id>/access/sso/callback
  3. Use os endpoints do seu domínio Okta, normalmente:
    • Emissor: https://<your-org>.okta.com
    • Endpoint de autorização: https://<your-org>.okta.com/oauth2/v1/authorize
    • Endpoint de token: https://<your-org>.okta.com/oauth2/v1/token
    • URI do JWKS: https://<your-org>.okta.com/oauth2/v1/keys

Salve suas configurações de SSO#

  1. Abra o Float Widget → Configurações → Privacidade & acesso
  2. Alterne a visibilidade para Privado se ainda não tiver feito isso
  3. Clique em Configurar Google Workspace / Entra ID / Okta… em SSO
  4. Preencha os campos acima e clique em Salvar SSO

Para remover o SSO, clique em Remover ao lado do status do SSO. A remoção do SSO não afeta uma senha configurada separadamente, e vice-versa.

Configurar o acesso a partir de um agente de IA#

Um agente de IA conectado ao servidor MCP do seu espaço de trabalho pode definir a visibilidade, a senha e os detalhes de SSO com a ferramenta update_access — os mesmos campos acima, passados como visibility, password e sso (com client_id, client_secret, authorization_endpoint, token_endpoint, jwks_uri, allowed_domain).

Solução de problemas#

Um leitor recebe "Senha incorreta"#

As senhas diferenciam maiúsculas de minúsculas. Defina uma nova se não tiver certeza do que foi configurado — a senha atual não pode ser revelada, apenas substituída.

O início de sessão SSO falha com "domain_not_allowed"#

O domínio de e-mail da conta com sessão iniciada não corresponde a Domínio permitido. Inicie sessão com uma conta no domínio correto ou limpe a restrição de Domínio permitido se quiser admitir qualquer conta autenticada pelo seu provedor de identidade.

O login SSO falha com "token_exchange_failed" ou "id_token_verification_failed"#

Verifique novamente o segredo do cliente e as três URLs dos endpoints — um erro de digitação em qualquer uma delas interrompe o handshake. Os endpoints devem ser exatamente os emitidos pelo seu provedor de identidade para o seu tenant/organização, e não espaços reservados genéricos.

Próximos passos#

Updated

Esta página foi útil?

Desenvolvido por Docsbook