Control de acceso
Elige cómo acceden los lectores a tus docs: público, con contraseña, mixto, con tu propio login JWT o con SSO. Elige la opción según tu audiencia.
Jamdesk te ofrece cinco formas de controlar quién puede leer tus docs. La mayoría de los equipos elige una y se queda con ella; algunos combinan varias.
Elige el enfoque adecuado
| Enfoque | Cuándo usarlo | Configuración |
|---|---|---|
| Totalmente público | Documentación de producto de cara al exterior, proyectos de código abierto, cualquier contenido que quieras indexado y compartible. | Predeterminado; no requiere configuración. |
| Contraseña para todo el sitio | Todo es interno: runbooks de ingeniería, docs solo para partners, un producto aún no publicado. Una frase de contraseña compartida protege todo el sitio. | auth.password.enabled: true en docs.json + establece la contraseña en el dashboard. Consulta Protección con contraseña. |
| Mixto (algunas páginas privadas) | La mayoría de las docs son públicas; unas pocas son internas (un runbook, una función beta, una referencia de API interna). | Agrega private: true al frontmatter de las páginas internas, o inclúyelas en auth.password.private[]. Consulta Protección con contraseña. |
| Tu propio inicio de sesión (JWT) | Los lectores ya inician sesión en tu producto. Tu backend firma un token de corta duración para cada uno, Jamdesk lo convierte en una sesión, y las páginas pueden limitarse a los grupos que nombres en el token. | auth.jwt.enabled: true más una loginUrl en docs.json, y una clave de firma desde el dashboard. Incluido en todos los planes. Consulta Autenticación JWT. |
| SSO (Enterprise) | Los lectores deben iniciar sesión con tu proveedor de identidad existente: sin contraseñas compartidas, con un registro de auditoría, y con la baja del acceso al eliminar al usuario. | Plan Enterprise. Consulta SSO. |
Puedes cambiar de enfoque en cualquier momento editando docs.json y haciendo push. Pasar del modo de todo el sitio al modo mixto (o al revés) solo necesita un build.
Patrones comunes
Docs internas y externas en un solo proyecto
La mayoría de los equipos quiere una documentación interna extensa detrás de un inicio de sesión, junto con un sitio público más pequeño para los clientes. No necesitas dos proyectos. Usa el modo mixto en un solo proyecto de Jamdesk:
---
title: Incident Runbook
private: true
---Las páginas con private: true quedan protegidas; todo lo demás sigue siendo público. Todo vive en un único repo con un solo build y un solo dashboard. La pantalla de desbloqueo solo aparece cuando un lector llega a una página protegida.
Para secciones internas más grandes, lista las rutas en docs.json en lugar de marcar cada archivo. Nota: auth.password.private[] activa automáticamente el modo de páginas específicas. No agregues enabled: true junto con él (eso es el modo de todo el sitio, lo opuesto de lo que quieres aquí).
{
"auth": {
"password": {
"hint": "Ask the on-call engineer",
"private": ["/internal/**", "/admin/runbook"]
}
}
}Dos proyectos separados
Usa dos proyectos solo cuando las audiencias necesiten una marca totalmente diferente, dominios personalizados separados, analítica separada, o niveles de plan distintos. Ejemplos: un sitio de docs público en docs.acme.com y una wiki interna separada en internal.acme.com. El costo de mantenimiento es más alto: dos builds, dos dashboards, dos dominios.
Acceso por usuario a través de tu propio inicio de sesión
Si tus clientes ya tienen cuentas contigo, una contraseña compartida es un paso atrás: se reenvía, nunca expira por sí sola, y no puede distinguir a un cliente de otro. Con la autenticación JWT, un usuario que ha iniciado sesión y abre tus docs es redirigido a una URL de tu lado, tu backend firma un token, y Jamdesk crea una sesión para esa persona. Los lectores no necesitan ninguna cuenta de Jamdesk, y no hay ningún secreto compartido que haya que hacer circular.
El token también puede llevar grupos. Agrega groups: ["admin"] al frontmatter de una página y solo los visitantes cuyo token incluya admin podrán abrirla o verla en la navegación. Todos los demás reciben un 404, así que la página no revela que existe.
---
title: Enterprise audit log API
groups: ["enterprise"]
---Combínalo con rutas public para las partes del sitio que deban permanecer abiertas, como un changelog o una página de estado.
SSO para el sitio de documentación
En los planes Enterprise, los lectores inician sesión con tu proveedor de identidad (Okta, Google Workspace, Azure AD, etc.) en lugar de escribir una contraseña compartida. Es la mejor opción cuando necesitas un registro de auditoría de quién leyó qué, o cuando dar de baja a un usuario debe revocar de inmediato su acceso a las docs. Consulta SSO para una visión general y cómo iniciar una conversación con el equipo de ventas.
Editores y lectores
A veces se confunden tres conceptos de acceso diferentes:
| Rol | Qué hacen | Cómo se otorga el acceso |
|---|---|---|
| Editores | Escriben y actualizan el contenido MDX. | Las docs se editan haciendo commit de MDX en tu repo de GitHub conectado, así que los permisos de tu repo de GitHub son los permisos de editor. No hay un rol de editor de Jamdesk separado por encima: cualquiera que pueda hacer push a tu rama de docs puede publicar un cambio. |
| Lectores | Ven el sitio de docs publicado. | Todo el mundo (público), cualquiera con la contraseña (modo contraseña), cualquiera para quien tu flujo de inicio de sesión firme un token (JWT), o cualquiera autenticado a través de tu IdP (SSO). |
| Miembros del equipo del dashboard | Gestionan builds, analítica y la configuración del proyecto en el dashboard de Jamdesk. | Se les invita mediante Settings → Team en el dashboard. No redactan contenido directamente. Consulta Miembros del equipo. |
Un miembro del equipo puede ser cualquier combinación de los tres. Son ejes independientes.