Inicio de sesión personalizado
El inicio de sesión personalizado para lectores en DeveloperHub se proporciona mediante JSON Web Tokens (JWT). Al usar el inicio de sesión con JWT:
Controlas quién tiene acceso a tu documentación sin tener que compartir una contraseña o un enlace global.
Puedes personalizar la documentación para el lector que ha iniciado sesión.
Controlas cuándo caduca el acceso.
El mismo token firmado puede identificar a los lectores en un proyecto público, donde no es necesario iniciar sesión y la identificación se usa únicamente para personalizar la documentación y aplicar audiencias. Consulta Contenido condicional.
Cómo funciona el inicio de sesión con JWT
Cuando el inicio de sesión con JWT está habilitado, el flujo de inicio de sesión es el siguiente:
El lector llegará al sitio de documentación sin autenticar y será redirigido a la URL de inicio de sesión, o bien partirá de tu propio sitio web para llegar a la URL de inicio de sesión.
Cuando llegue a la URL de inicio de sesión, tus servidores backend firmarán un token JWT usando una clave de API que tenga el permiso
access.write, construirán una URL que contenga el token JWT y redirigirán al lector a ella. La URL es la de tu sitio de documentación.Cuando el lector intente acceder al sitio de documentación sin autenticar con el token JWT en la URL, nuestros servidores backend verificarán el token y crearán un token de acceso con la caducidad definida en el token. A partir de ese momento, el lector podrá acceder al sitio de documentación.
Cuando el token de acceso del lector caduca, este deja de poder acceder al contenido y es redirigido de nuevo a la URL de inicio de sesión, donde el proceso se repite.
Proporcionamos la URL a la que el lector intentó acceder en un parámetro de consulta llamado redirect. Tus servidores pueden leer este parámetro de consulta y usarlo como URL de redirección en lugar de la página de inicio de tu documentación.
Cómo habilitar el inicio de sesión con JWT
Para configurar el inicio de sesión con JWT en DeveloperHub, sigue estos pasos:
Abre la configuración del proyecto → Acceso.
En la tarjeta Método de acceso, selecciona JWT.
Indica una URL de inicio de sesión; obtén más información sobre la URL de inicio de sesión aquí.
Haz clic en Guardar cambios en el menú superior.

Firmar el JWT
Para autorizar y autenticar el acceso a tu sitio de documentación, debes firmar un token JWT usando una clave de API que tenga el permiso access.write. Primero, asegúrate de haber generado la clave de API. Los algoritmos de firma compatibles son HS256 y HS512.
Existen numerosas bibliotecas para la mayoría de los lenguajes de programación para firmar JWT; consulta jwt.io para más detalles.
Código de ejemplo para firmar el JWT:
Una vez generada la URL, puedes redirigir a tu lector a ella para darle acceso a la documentación.
El objeto vars de la carga útil del JWT se usa para evaluar las audiencias de contenido del contenido condicional. Las variables se comparan con las condiciones de audiencia para determinar qué contenido es visible para cada lector, o puedes nombrar directamente las audiencias del lector con _audience.
Para firmar un JWT necesitas una clave de API con el permiso access.write. La clave de API es secreta y nunca debe compartirse en línea.
Para mayor comodidad, también puedes generar un JWT directamente desde la ventana Gestionar acceso haciendo clic en "Generate JWT" y seleccionando el valor de caducidad.
Aplicación Express de ejemplo
Un ejemplo de aplicación Express que puedes usar:
Limitar el acceso a un dispositivo
Para limitar un único token JWT de modo que dé acceso solo en un dispositivo, se puede añadir un jti único en la carga útil. Por ejemplo:
En este ejemplo se usó un UUID para dar unicidad al parámetro jti, pero se puede usar cualquier secuencia aleatoria.
Si el mismo JWT se usa para acceder de nuevo a un proyecto, se denegará el acceso al lector y se le mostrará el mensaje "Token has already been used".
Gestión de errores del inicio de sesión con JWT
Puedes incluir un error_redirect_url en la carga útil de tu JWT. Cuando se produce un error (porque el token ha caducado o falló la verificación de la firma), el usuario será redirigido a esa URL con un parámetro de consulta añadido dh_jwt_error que contiene el mensaje de error.
Need help? Visit our community forums or contact us.