Inicio de sesión personalizado

Herramientas de IA

El inicio de sesión personalizado para los lectores en DeveloperHub se proporciona mediante JSON Web Tokens (JWT). Al usar el inicio de sesión con JWT:

  • Usted controla quién tiene acceso a su documentación sin tener que compartir una contraseña o enlace global.

  • Puede personalizar la documentación para el lector que ha iniciado sesión.

  • Usted controla cuándo caduca el acceso.

Identificación de lectores en un sitio de documentación público

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. Consulte 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 sería el siguiente:

  1. El lector llegaría al sitio de documentación sin autenticarse y sería redirigido a la URL de inicio de sesión, o bien partiría de su propio sitio web para llegar a la URL de inicio de sesión.

  2. Cuando llegan a la URL de inicio de sesión, sus servidores backend firmarían un token JWT usando una clave de API que tenga el permiso access.write, construirían una URL que contenga el token JWT y redirigirían al lector a ella. La URL es la de su sitio de documentación.

  3. Cuando el lector intenta acceder al sitio de documentación sin autenticarse 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. El lector ya puede acceder al sitio de documentación.

  4. Cuando el token de acceso del lector caduca, ya no puede acceder al contenido y sería redirigido de nuevo a la URL de inicio de sesión, donde este proceso se repite.

Información

Proporcionamos la URL a la que el lector intentó acceder en un parámetro de consulta llamado redirect. Sus servidores pueden leer este parámetro de consulta y usarlo como URL de redirección en lugar de la página de inicio de su documentación.

Cómo habilitar el inicio de sesión con JWT

Para configurar el inicio de sesión con JWT en DeveloperHub, siga estos pasos:

  1. Abra la configuración del proyecto → Acceso.

  2. En la tarjeta Método de acceso, seleccione JWT.

  3. Proporcione una URL de inicio de sesión; obtenga más información sobre la URL de inicio de sesión aquí.

  4. Haga clic en Guardar cambios en el menú superior.


Firma del JWT

Para autorizar y autenticar el acceso a su sitio de documentación, debe firmar un token JWT usando una clave de API que tenga el permiso access.write. Primero, asegúrese 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; consulte jwt.io para más detalles,

Código de ejemplo para firmar el JWT:

const sign = require('jsonwebtoken').sign; const apiKey = '689c3ce8e7c68b7c7f86acca6a028e6f8656eb792b19a334f8e3f2a56ca8f561'; function getSignedDeveloperHubUrl() { const docsUrl = 'https://docs.pied-piper.com'; // Your docs site URL. It may be a URL to a specific page or API Reference. const payload = { version: 1, // Controls the version of custom login. Do not remove. vars: { // Personalise documentation by injecting variables here if needed userId: 1234 }, error_redirect_url: 'https://pied-piper.com' // Optional: Redirects to this URL on error }; // Place here any variables you want to inject to personalise the docs. const expiresIn = 24 * 60 * 60; // Expiry, preferably 1 day, the shorter the more secure. Expiry must be defined. const token = sign(payload, apiKey, {expiresIn: expiresIn}); return `${docsUrl}?jwt=${token}`; }

Una vez generada la URL, puede redirigir a su lector a ella para darle acceso a la documentación.

Variables y contenido condicional

El objeto vars en 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 bien puede indicar directamente las audiencias del lector con _audience.

Firme solo en el backend

Para firmar un JWT, necesita una clave de API con el permiso access.write. La clave de API es un secreto y nunca debe compartirse en línea.

Para un acceso sencillo, también puede 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

Una aplicación express de ejemplo que puede usar:

const express = require('express'); const app = express(); const sign = require('jsonwebtoken').sign; const port = 1234; const apiKey = '689c3ce8e7c68b7c7f86acca6a028e6f8656eb792b19a334f8e3f2a56ca8f561'; function getSignedDeveloperHubUrl(url) { const docsUrl = url || 'https://docs.pied-piper.com'; const payload = { version: 1, vars: { user: { id: 1234, name: "John" } } }; const expiresIn = 24 * 60 * 60; const token = sign(payload, apiKey, {expiresIn: expiresIn}); return `${docsUrl}?jwt=${token}`; } app.get('/login', (req, res) => { res.redirect(getSignedDeveloperHubUrl(req.query.redirect)); }); app.listen(port, () => { console.log(`Reader login app listening at http://localhost:${port}`) });

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:

function getSignedDeveloperHubUrl(url) { const docsUrl = url || 'https://docs.pied-piper.com'; const payload = { jti: require('uuid').v4(), version: 1, vars: { user: { id: 1234, name: "John" } } }; const expiresIn = 24 * 60 * 60; const token = sign(payload, apiKey, {expiresIn: expiresIn}); return `${docsUrl}?jwt=${token}`; }

En este ejemplo, se usó un UUID para dar unicidad al parámetro jti, pero se puede usar cualquier secuencia aleatoria.

Si se usara el mismo JWT para acceder de nuevo a un proyecto, se denegaría el acceso al lector y se mostraría el mensaje "Token has already been used".

Gestión de errores del inicio de sesión con JWT

Puede proporcionar un error_redirect_url en la carga útil de su 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.

  Última actualización el Sep 28, 2026
Creado con DeveloperHub

Need help? Visit our community forums or contact us.

Editar en GitHub
Tabla de Contenido
Inicio de sesión personalizadoCómo funciona el inicio de sesión con JWTCómo habilitar el inicio de sesión con JWTFirma del JWTAplicación Express de ejemploLimitar el acceso a un dispositivoGestión de errores del inicio de sesión con JWT