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.

Identificar 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. 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:

  1. 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.

  2. 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.

  3. 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.

  4. 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.

Información

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:

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

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

  3. Indica una URL de inicio de sesión; obtén más información sobre la URL de inicio de sesión aquí.

  4. 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:

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});

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

Variables y contenido condicional

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.

Firma solo en el backend

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:

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));

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 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.

  Última actualización