🔥 Token Introspection en FHIR: Guía para la Validación Moderna

1. Autenticación, Autorización y Token Introspection

En el mundo de la seguridad de 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 verificación de la identidad, que confirma que los usuarios son quienes dicen ser. Esto ocurre habitualmente en su Proveedor de Identidad (IdP) cuando los usuarios inician sesión con credenciales, datos biométricos u otros factores. El resultado es un token que representa la identidad autenticada.

La Autorización responde a «¿Qué puede hacer?». 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, es aquí donde entran en juego los recursos AccessPolicy.

Token Introspection es el puente crítico 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é Token Introspection?

Los ecosistemas digitales modernos, especialmente en el ámbito sanitario, son complejos. A menudo están formados por numerosas aplicaciones —desde portales para pacientes y HCE hasta aplicaciones móviles para profesionales clínicos—, cada una potencialmente conectada a diferentes sistemas de Gestión de Identidad y Acceso (IAM) o IdPs.

Cuando se introduce un servidor FHIR en esta arquitectura, no debería obligar a cambiar los flujos de autenticación 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 debe ser capaz de confiar en los tokens emitidos por estos sistemas de autenticación externos y validarlos.

Es aquí donde Token Introspection se vuelve 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. Token Introspection en Aidbox

Aidbox proporciona el recurso TokenIntrospector para validar tokens emitidos por un IdP externo. Puede gestionar dos tipos diferentes de tokens:

JWT (JSON Web Token): Un token autocontenido que lleva las afirmaciones del usuario y está firmado. TokenIntrospector verifica la firma de forma local y lee las afirmaciones —no es necesario ningún viaje de ida y vuelta al servidor de autenticación.
Token opaco. Una cadena de caracteres de aspecto aleatorio sin afirmaciones incrustadas. Para verificarlo, Aidbox llama al introspection_endpoint del emisor (según RFC 7662) y pregunta si el token está activo y a quién representa.

TokenIntrospector valida el token utilizando el método correcto para 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 Token Opaco

Técnicamente, el Endpoint de Introspección podría utilizarse para cualquier tipo de token, pero se usa más comúnmente para tokens opacos, ya que los tokens JWT son autocontenidos y disponen de diferentes opciones para ser validados localmente.

Aidbox implementa el estándar OAuth 2.0 Token Introspection (RFC 7662). Cuando llega un token opaco, el TokenIntrospector realiza una solicitud HTTP POST al introspection_endpoint configurado, enviando el token para su validación.

{
  "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 afirmaciones pertinentes:

{
  "active": true,
  "sub": "user123",
  "scope": "read write",
  "exp": 1684567890,
  "client_id": "my-client"
}

Aidbox recibe esta respuesta y pone las afirmaciones a disposición de los recursos AccessPolicy en 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 Formas de Validar un JWT

Para los tokens JWT, Aidbox ofrece tres métodos de validación, cada uno adecuado para diferentes 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.

{
  "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 despliegues sencillos. Sin embargo, requiere que el mismo secreto se almacene 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.

{
  "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 es compatible con los proveedores estándar OAuth 2.0/OIDC y admite 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 permite especificar múltiples claves criptográficas directamente en la configuración de TokenIntrospector. Permite gestionar las claves de forma explícita dentro de Aidbox, con soporte simultáneo de múltiples algoritmos y tipos de claves.

{
  "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 es 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 diferentes aplicaciones de su ecosistema pueden utilizar distintos algoritmos criptográficos. Las aplicaciones móviles pueden preferir ES256 por rendimiento, mientras que las aplicaciones web usan RS256 por compatibilidad.
IdP en Paralelo: Las grandes organizaciones suelen tener múltiples IdPs o entornos. Un único TokenIntrospector puede validar tokens de diferentes 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 Admitidos

Aidbox admite las siguientes claves criptográficas y algoritmos:

Tipo de Clave (kty)	Algoritmos (alg)	Formato	Campo de Clave	Caso de Uso
RSA	RS256, RS384	PEM	pub	Amplia compatibilidad, estándar consolidado
EC	ES256	PEM	pub	Claves más pequeñas, mejor rendimiento
OCT	HS256	plain	k	Secretos compartidos, firma simétrica

Reglas de Configuración de Claves:

Claves asimétricas (RSA, EC): Use el campo pub con formato PEM
Claves simétricas (OCT): Use el campo k con formato plain
Requisitos de formato: PEM es obligatorio para los algoritmos asimétricos, plain para los algoritmos simétricos

4.3 Ejemplo JSON Completo

A continuación se muestra un ejemplo completo con cuatro claves diferentes en un único TokenIntrospector:

{
  "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 Selecciona Aidbox la Clave Correcta

Al validar un JWT, Aidbox sigue un algoritmo específico para seleccionar la clave apropiada:

Coincidencia de Algoritmo: Aidbox extrae la afirmación alg de la cabecera del JWT y busca claves con algoritmos coincidentes.
Prueba Secuencial: Aidbox prueba cada clave con el algoritmo coincidente, comprobando también el formato de la clave y el kty (tipo de clave), hasta que una de ellas 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 Debe Evitar

Formato Incorrecto: El error más común es la discordancia entre el campo de formato 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 significa que los tokens no coincidirán con este TokenIntrospector, lo que provocará fallos de validación.

Discordancia 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 en Base64 son habituales 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. Es ahí donde entran en juego los recursos AccessPolicy.

Tras la validación exitosa del token, Aidbox extrae las afirmaciones del JWT y las pone a disposición para las decisiones de autorización. Una AccessPolicy sencilla podría tener el siguiente aspecto:

{
  "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, ámbitos u otras afirmaciones del JWT.

Recuerde: validación ≠ autorización. Un token válido no concede acceso automáticamente; sus AccessPolicies determinan qué puede hacer cada usuario.

6. Mejores Prácticas y Consejos para Token Introspection

Rote las Claves con Regularidad: Implemente un calendario de rotación de claves, especialmente para los entornos de producción. Utilice la función de múltiples claves para permitir una rotación sin interrupciones.

Prefiera los 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 Afirmaciones de Emisor Coherentes: Asegúrese de que su IdP siempre utilice el mismo valor iss en todos los tokens. Cambiar los emisores requiere actualizar las configuraciones de TokenIntrospector.

Use Introspectores Específicos por Entorno: Cree recursos TokenIntrospector separados para los entornos de desarrollo, preproducción y producción. Esto evita la aceptación de tokens entre entornos.

Supervise la Caducidad de las Claves: Realice un seguimiento de cuándo caducan 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

Aidbox TokenIntrospector proporciona opciones completas de validación de tokens para su infraestructura FHIR. Tanto si elige la introspección de token opaco, la validación basada en secreto, 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 sólidas 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 tiene Token Introspection integrado. Pruébelo hoy y compruebe cómo puede integrarse en su sistema.

Véase también: RBAC con Keycloak y SMART on FHIR V2 y Uso de API Gateway con FHIR.