--- { "title": "Introspección de tokens en FHIR: una guía completa para la validación moderna de tokens", "description": "La introspección de tokens es el puente fundamental entre la autenticación y la autorización. Cuando un cliente presenta un token para acceder a recursos FHIR, el servidor debe comprobar si el token es válido.", "date": "2025-08-19", "author": "Rostislav Antonov", "reading-time": "8 min", "tags": [ "Infrastructure", "Compliance" ] } --- > For the complete documentation index, see [llms.txt](https://www.health-samurai.io/llms.txt). > Use it to discover all available pages before guessing URLs. --- ## 1. Autenticación, autorización e introspección de tokens En el mundo de la seguridad de las API, dos conceptos fundamentales trabajan conjuntamente para proteger los recursos: la **autenticación** y la **autorización**. La **autenticación** responde a la pregunta «¿Quién es usted?». Es el proceso de verificar la identidad, confirmando que los usuarios son quienes afirman ser. Esto ocurre normalmente en su proveedor de identidad (IdP) cuando los usuarios inician sesión con credenciales, biometría u otros factores. El resultado es un token que representa la identidad autenticada. La **autorización** responde a «¿Qué puede hacer usted?». Una vez establecida la identidad, la autorización determina a qué recursos puede acceder el usuario autenticado y qué operaciones puede realizar. En los servidores FHIR, aquí es donde entran en juego los recursos *AccessPolicy*. La **introspección de tokens** es el puente fundamental entre estos dos conceptos. Cuando un cliente presenta un token para acceder a recursos FHIR, el servidor debe comprobar si el token es válido. Este proceso también revela a quién pertenece el token y qué información contiene, de modo que el servidor pueda tomar decisiones de autorización. ## 2. ¿Por qué la introspección de tokens? Los ecosistemas digitales modernos, especialmente en el ámbito sanitario, son complejos. A menudo se componen de numerosas aplicaciones, desde portales para pacientes y HCE hasta aplicaciones móviles para clínicos, cada una potencialmente conectada a distintos sistemas de gestión de identidades y accesos (IAM) o IdPs. Cuando se introduce un servidor FHIR en esta arquitectura, no debería obligar a cambiar los flujos de autenticación ya establecidos. Rediseñar el sistema IAM para un nuevo servicio es costoso y disruptivo. El objetivo es la integración, no la sustitución. [El servidor FHIR](https://www.health-samurai.io/fhir-server) debe ser capaz de confiar en los tokens emitidos por estos sistemas de autenticación externos y validarlos. Aquí es donde la introspección de tokens resulta esencial. Permite que su servidor FHIR actúe como un **servidor de recursos** seguro, delegando el proceso de autenticación de vuelta a sus IdPs de confianza. Cuando un cliente presenta un token, el servidor FHIR utiliza la introspección para responder a una pregunta crítica: «¿Es auténtico este token?». Este proceso permite al servidor FHIR proteger sus recursos sin convertirse él mismo en un IdP. ## 3. Introspección de tokens en Aidbox Aidbox proporciona el recurso *TokenIntrospector* para validar tokens emitidos por IdPs externos. Puede gestionar dos tipos distintos de tokens: - **JWT (JSON Web Token):** Un token autocontenido que lleva las reclamaciones del usuario y está firmado. *TokenIntrospector* verifica la firma localmente y lee las reclamaciones; no se necesita ningún viaje de ida y vuelta al servidor de autenticación. - **Token opaco:** Una cadena de aspecto aleatorio sin reclamaciones incorporadas. Para verificarlo, Aidbox llama al *introspection_endpoint* del emisor (según [RFC 7662](https://datatracker.ietf.org/doc/html/rfc7662)) y pregunta si el token está activo y a quién representa. *TokenIntrospector* valida el token utilizando el método correcto según su formato. Después, Aidbox aplica las reglas de *AccessPolicy* para decidir a qué puede acceder el solicitante. ### 3.1 Endpoint de introspección de tokens opacos Técnicamente, el endpoint de introspección podría utilizarse para cualquier tipo de token, pero se usa más comúnmente con tokens opacos, ya que los tokens JWT son autocontenidos y disponen de diferentes opciones para ser validados localmente. Aidbox implementa el estándar de introspección de tokens OAuth 2.0 (RFC 7662). Cuando llega un token opaco, *TokenIntrospector* realiza una petición HTTP POST al *introspection_endpoint* configurado, enviando el token para su validación. ```javascript { "resourceType": "TokenIntrospector", "id": "opaque-example", "type": "opaque", "introspection_endpoint": { "url": "https://auth.example.com/oauth/introspect", "authorization": "Basic Y2xpZW50OnNlY3JldA==" } } ``` El servidor de autenticación externo responde con un objeto JSON que indica si el token está activo e incluye las reclamaciones pertinentes: ```javascript { "active": true, "sub": "user123", "scope": "read write", "exp": 1684567890, "client_id": "my-client" } ``` Aidbox recibe esta respuesta y pone las reclamaciones a disposición de los recursos *AccessPolicy* bajo el contexto del token. Este enfoque delega toda la lógica de validación de tokens en su infraestructura de identidad existente, manteniendo Aidbox como un servidor de recursos puro. ### 3.2 Tres maneras de validar un JWT Para los tokens JWT, Aidbox ofrece tres métodos de validación, cada uno adecuado para distintos escenarios. Elija en función de sus requisitos de seguridad, las restricciones de infraestructura y las necesidades operativas. #### 3.2.1 Validación basada en secreto La validación basada en secreto utiliza un secreto compartido para firmas basadas en HMAC (HS256). Su IdP firma los tokens con este secreto, y Aidbox los verifica utilizando la misma clave. ```javascript { "resourceType": "TokenIntrospector", "id": "simple-secret", "type": "jwt", "jwt": { "iss": "https://myidp.example.com", "secret": "your-256-bit-secret-here" } } ``` Este método funciona bien para desarrollo o implementaciones sencillas. Sin embargo, requiere que el mismo secreto esté almacenado tanto en su IdP como en Aidbox, lo que puede suponer un problema de seguridad. #### 3.2.2 Validación mediante JWKS URI La validación mediante URI de JSON Web Key Set (JWKS) obtiene las claves públicas del endpoint conocido de su IdP. Este enfoque estándar permite la rotación automática de claves sin necesidad de actualizar la configuración de Aidbox. ```javascript { "resourceType": "TokenIntrospector", "id": "jwks-example", "type": "jwt", "jwt": { "iss": "https://myidp.example.com", "jwks_uri": "https://myidp.example.com/.well-known/jwks.json" } } ``` Su IdP publica sus claves públicas en el endpoint JWKS. Aidbox obtiene estas claves y las almacena en caché, actualizándolas automáticamente cuando cambian. Este enfoque funciona con proveedores estándar de OAuth 2.0/OIDC y es compatible con algoritmos RSA y de curva elíptica como RS256 y ES256. #### 3.2.3 Claves criptográficas (novedad en Aidbox desde la versión 2505) Este método le permite especificar múltiples claves criptográficas directamente en la configuración de *TokenIntrospector*. Permite gestionar las claves explícitamente dentro de Aidbox, con soporte simultáneo para múltiples algoritmos y tipos de claves. ```javascript { "resourceType": "TokenIntrospector", "id": "multi-key-example", "type": "jwt", "jwt": { "iss": "https://myidp.example.com", "keys": [ { "alg": "RS256", "format": "PEM", "pub": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...\n-----END PUBLIC KEY-----\n" }, { "alg": "ES256", "format": "PEM", "pub": "-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE...\n-----END PUBLIC KEY-----\n" } ] } } ``` Este método resulta especialmente útil en entornos donde se prefiere la gestión directa de claves o cuando los endpoints JWKS no están disponibles. ## 4. Análisis en profundidad: configuración de claves criptográficas ### 4.1 ¿Por qué múltiples claves? El soporte de múltiples claves en un único *TokenIntrospector* resuelve varios desafíos del mundo real: - **Rotación de claves**: Durante la rotación de claves, a menudo es necesario admitir simultáneamente las claves antigua y nueva. Algunos tokens pueden estar firmados con la clave anterior, mientras que los nuevos utilizan la clave actualizada. - **Algoritmos mixtos**: Las distintas aplicaciones de su ecosistema pueden utilizar diferentes algoritmos criptográficos. Las aplicaciones móviles pueden preferir ES256 por su rendimiento, mientras que las aplicaciones web usan RS256 por compatibilidad. - **IdPs en paralelo**: Las grandes organizaciones suelen disponer de múltiples IdPs o entornos. Un único *TokenIntrospector* puede validar tokens de distintas fuentes, cada una con sus propias claves. - **Migración gradual**: Al realizar la transición entre tipos de claves o proveedores, puede añadir nuevas claves sin eliminar inmediatamente las antiguas, garantizando actualizaciones sin tiempo de inactividad. ### 4.2 Tipos y formatos de claves compatibles Aidbox admite los siguientes tipos de claves criptográficas y algoritmos: | Tipo de clave ([kty](https://datatracker.ietf.org/doc/html/rfc7518#section-6.1)) | Algoritmos (alg) | Formato | Campo de clave | Caso de uso | | --- | --- | --- | --- | --- | | RSA | RS256, RS384 | PEM | pub | Amplia compatibilidad, estándar establecido | | EC | ES256 | PEM | pub | Claves más pequeñas, mejor rendimiento | | OCT | HS256 | plain | [k](https://datatracker.ietf.org/doc/html/rfc7518#section-6.4.1) | Secretos compartidos, firma simétrica | **Reglas de configuración de claves:** - **Claves asimétricas** (RSA, EC): Utilice el campo *pub* con formato *PEM* - **Claves simétricas** (OCT): Utilice el campo *k* con formato *plain* - **Requisitos de formato**: *PEM* es obligatorio para algoritmos asimétricos, *plain* para algoritmos simétricos ### 4.3 Ejemplo JSON completo A continuación se muestra un ejemplo exhaustivo con cuatro claves distintas en un único *TokenIntrospector*: ```javascript { "resourceType": "TokenIntrospector", "id": "comprehensive-keys", "type": "jwt", "jwt": { "iss": "https://myidp.example.com", "keys": [ { "kty": "RSA", "alg": "RS256", "format": "PEM", "pub": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA4f5wg5l2hKsTeNem/V41fGnJm6gOdrj8ym3rFkEjWT2btf0hEkNKsP8d9xwnSsWLXY0vhU7LWNBTSwJjJGrQ6cOq5m4eUzjbRpLo8Oez7UyO8vRrGI7w2E1+BZrFf6rZ0KS8yDJ8nKnEWP+a5CKJmLkZqzZ8oVMODbqPG6fOj8+qr5VZ6jJ7XzB9W8qR2s7LQ+5t9W8vq2XZ4gPw5Vp9X7+Wz6B+o8C3k7Q3g+t8D7h9+4e7u7Bp9E+P0Q0q4g8OO7L8qO5x5D7aF3R9g+O2OP3O+D3q+t5/yb1nRO8UuE3WO0u1xZ4qP1HJE3K+Tl+vE/Pt6Cw2EPz1EOpJu6F/JO9H8XQIDAQAB\n-----END PUBLIC KEY-----\n" }, { "kty": "RSA", "alg": "RS384", "format": "PEM", "pub": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA7Z8...\n-----END PUBLIC KEY-----\n" }, { "kty": "EC", "alg": "ES256", "format": "PEM", "pub": "-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE4f5wg5l2hKsTeNem/V41fGnJm6gOdrj8ym3rFkEjWT2btf0hEkNKsP8d9xwnSsWLXY0vhU7LWNBTSwJjJGrQ==\n-----END PUBLIC KEY-----\n" }, { "kty": "OCT", "alg": "HS256", "format": "plain", "k": "your-256-bit-secret-key-here-must-be-long-enough" } ] } } ``` ### 4.4 Cómo Aidbox selecciona la clave correcta Al validar un JWT, Aidbox sigue un algoritmo específico para seleccionar la clave adecuada: - **Coincidencia de algoritmo**: Aidbox extrae la reclamación *alg* de la cabecera del JWT y busca claves con algoritmos coincidentes. - **Prueba secuencial**: Aidbox prueba cada clave con el algoritmo coincidente, comprobando al mismo tiempo el formato de la clave y el *kty* (tipo de clave), hasta que una valide correctamente la firma. Este enfoque garantiza que los tokens se validen correctamente incluso cuando la rotación de claves está en curso o cuando se utilizan múltiples algoritmos. ### 4.5 Errores comunes que deben evitarse **Formato incorrecto**: El error más frecuente es la discrepancia entre el campo *format* y la codificación real de la clave. Las claves PEM deben incluir cabeceras y saltos de línea correctos, mientras que el formato *plain* espera el material de clave en bruto. **Emisor ausente**: Olvidar establecer el campo *jwt.iss* implica que los tokens no coincidirán con este *TokenIntrospector*, lo que provocará fallos de validación. **Discrepancia de algoritmo**: Usar `alg: "RS256"` con una clave de curva elíptica, o especificar ES256 con una clave RSA, causará errores criptográficos. **Codificación de clave incorrecta**: Los problemas de codificación Base64 son frecuentes con las claves en formato *plain*. Asegúrese de que el material de clave esté correctamente codificado. ## 5. Ejemplo de AccessPolicy La validación del token solo confirma que un JWT es legítimo; no determina a qué puede acceder el usuario. Para eso están los recursos *AccessPolicy*. Tras la validación exitosa del token, Aidbox extrae las reclamaciones del JWT y las pone a disposición para las decisiones de autorización. Una *AccessPolicy* sencilla podría tener este aspecto: ```javascript { "id": "external-auth-server", "engine": "json-schema", "schema": { "required": [ "jwt" ], "properties": { "jwt": { "required": [ "iss" ], "properties": { "iss": { "constant": "https://auth.example.com" } } } } } } ``` Esta política garantiza que solo los tokens con el emisor correcto puedan acceder a los recursos. Puede crear políticas más sofisticadas basadas en roles de usuario, scopes u otras reclamaciones del JWT. Recuerde: **validación ≠ autorización**. Un token válido no concede acceso automáticamente; son sus *AccessPolicies* las que determinan qué puede hacer cada usuario. ## 6. Buenas prácticas y consejos para la introspección de tokens **Rote las claves con regularidad**: Implemente un calendario de rotación de claves, especialmente en entornos de producción. Utilice la función de múltiples claves para habilitar una rotación sin interrupciones. **Prefiera algoritmos asimétricos**: Cuando sea posible, utilice RS256 o ES256 en lugar de HS256. Las claves asimétricas eliminan la necesidad de compartir secretos entre sistemas. **Mantenga las reclamaciones de emisor coherentes**: Asegúrese de que su IdP utilice siempre el mismo valor de *iss* en todos los tokens. Cambiar los emisores requiere actualizar las configuraciones de *TokenIntrospector*. **Use introspectores específicos por entorno**: [Cree recursos](https://www.health-samurai.io/docs/aidbox/configuration/init-bundle) *TokenIntrospector* independientes para los entornos de desarrollo, preproducción y producción. Esto evita la aceptación cruzada de tokens entre entornos. **Supervise la expiración de las claves**: Realice un seguimiento de cuándo expiran sus claves criptográficas y planifique la rotación en consecuencia. Las claves caducadas provocarán fallos de validación. ## 7. Próximos pasos para la seguridad de su FHIR El *TokenIntrospector* de Aidbox ofrece opciones completas de validación de tokens para su infraestructura FHIR. Tanto si elige la introspección de tokens opacos, la validación basada en secreto, el JWKS URI o la configuración directa de claves criptográficas, cada método ofrece ventajas diferenciadas para distintos casos de uso y requisitos arquitectónicos. Al admitir simultáneamente múltiples enfoques de validación y tipos de claves, Aidbox le permite implementar prácticas de seguridad robustas que se alinean con su infraestructura de identidad existente y sus necesidades operativas. ¿Busca un servidor FHIR que funcione con su configuración de autenticación actual? Aidbox incluye introspección de tokens de serie. [Pruébelo hoy](https://www.health-samurai.io/fhir-server) y compruebe cómo puede integrarse en su sistema. Véase también: [RBAC con Keycloak y SMART on FHIR V2](/blog/implementing-role-based-access-control-for-fhir-resources-with-keycloak-and-smart-on-fhir-v2) y [Uso de API Gateway con FHIR](/blog/using-api-gateway-with-fhir-api).