# Health Information Exchange Version 0.1.0 (draft) - https://hix.meddyg.com/fhir/hix # Descripción general HIX define una arquitectura de referencia para comunidades que comparten documentos clínicos. No propone un estándar nuevo. Articula los perfiles de IHE, los estándares y las especificaciones necesarios para operar una comunidad así sobre FHIR, y sigue el modelo de comunidad de **[Mobile Health Document Sharing (MHDS)](https://profiles.ihe.net/ITI/MHDS/volume-1.html)**, que toma como referencia sin declarar conformidad con él. Sin una comunidad, cada organización tiene que integrarse con cada una de las demás, y la política de acceso se aplica en tantos lugares como organizaciones haya, con la calidad que cada una pueda pagar. HIX concentra esa integración y esa política en una infraestructura central, con la que cada organización se integra una sola vez, como explica la [sección 2.1](volume-1-concepts.html#limite-de-confianza). ## Propósito y alcance Esta guía describe los roles de la comunidad, sus límites de confianza y la relación entre sus componentes. Explica, entre otras decisiones, por qué la localización y la recuperación se median de forma centralizada, por qué la custodia documental se mantiene distribuida por defecto y cómo **[IUA](https://profiles.ihe.net/ITI/IUA/index.html)** y **[OAuth 2.0](https://www.rfc-editor.org/info/rfc6749/)** establecen la base de autorización y delegación entre los participantes. Cuando la autorización requiere la participación de una persona, incorpora **[SMART App Launch](https://hl7.org/fhir/smart-app-launch/)** en el flujo interactivo que esa persona completa desde su navegador. Esta arquitectura abarca las siguientes capacidades dentro de la comunidad: - Publicación, indexación, localización y recuperación de documentos clínicos. - Custodia distribuida de documentos y almacenamiento central cuando corresponda. - Transporte seguro hacia los custodios, HTTPS directo o **[X-Road](https://x-road.global/)** según declare el directorio, sin alterar la topología de la comunidad. - Identidad maestra de pacientes y vinculación con las identidades locales. - Directorio de organizaciones participantes, servicios y endpoints. - Autorización y divulgación controlada de documentos. ### Capacidades en desarrollo Las siguientes capacidades forman parte de la arquitectura HIX, pero su especificación detallada se definirá en una versión posterior de esta guía. La arquitectura ya establece los límites, los puntos de integración y los flujos que permiten incorporarlas sin alterar la topología mediada de la comunidad. - **Consentimiento anticipado del paciente.** HIX define dónde se aplica la decisión de divulgación y qué información necesita. El modelo de consentimiento, su ciclo de vida y sus políticas se especificarán a partir de los perfiles IHE aplicables. - **Auditoría de operaciones y divulgaciones.** HIX define la necesidad de registrar las operaciones en ambos extremos de la interacción. El modelo de consulta y el comportamiento ante fallos se especificarán posteriormente. Los casos previstos para versiones posteriores se listan en la [sección 2.5](volume-1-usecases.html#casos-previstos) del Volumen 1. ## Convenciones de la especificación Las palabras clave **MUST**, **MUST NOT**, **REQUIRED**, **SHALL**, **SHALL NOT**, **SHOULD**, **SHOULD NOT**, **RECOMMENDED**, **NOT RECOMMENDED**, **MAY** y **OPTIONAL**, cuando aparecen íntegramente en mayúsculas, se interpretan conforme a [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119) y [RFC 8174](https://www.rfc-editor.org/rfc/rfc8174). Estas palabras expresan requisitos normativos de **HIX**. El resto del lenguaje utilizado en esta guía es descriptivo, salvo que se indique explícitamente lo contrario. Cuando HIX incorpora o referencia requisitos definidos por un perfil IHE, una especificación HL7 FHIR o un RFC, dichos requisitos conservan la fuerza normativa establecida por su especificación de origen. Un requisito que empieza con la etiqueta **Experimental.** es una propuesta de esta versión para un punto en el que los estándares no dan una respuesta única. Es normativo como cualquier otro, pero puede cambiar con la experiencia de implementación. ### Terminología y abreviaturas HIX utiliza terminología definida por IHE, HL7 FHIR y OAuth 2.0. Salvo que se indique lo contrario, los nombres de perfiles y actores conservan el significado establecido por su especificación de origen. En esta guía, un **perfil IHE** define un conjunto de capacidades y transacciones, mientras que un **actor IHE** representa el rol que un sistema desempeña dentro de dicho perfil. | Término | Significado | | --- | --- | | **[MHDS](https://profiles.ihe.net/ITI/MHDS/volume-1.html)** — *Mobile Health Document Sharing* | Perfil IHE que define una comunidad de intercambio de documentos clínicos basada en FHIR y la composición de perfiles necesaria para operarla. HIX lo toma como arquitectura de referencia. | | **[MHD](https://profiles.ihe.net/ITI/MHD/5.0.0/index.html)** — *Mobile access to Health Documents* | Perfil IHE para publicar, localizar y recuperar documentos clínicos mediante FHIR. HIX usa sus actores **Document Source**, **Document Consumer**, **Document Recipient** y **Document Responder**. | | **[PMIR](https://profiles.ihe.net/ITI/PMIR/index.html)** — *Patient Master Identity Registry* | Perfil IHE para gestionar y sincronizar identidades maestras de pacientes. | | **[PIXm](https://profiles.ihe.net/ITI/PIXm/index.html)** — *Patient Identifier Cross-referencing for mobile* | Perfil IHE con el que cada miembro declara sus identidades locales de paciente y resuelve un identificador a la identidad maestra. | | **[PDQm](https://profiles.ihe.net/ITI/PDQm/index.html)** — *Patient Demographics Query for Mobile* | Perfil IHE para localizar a un paciente por sus datos demográficos cuando no se dispone de un identificador conocido por la comunidad. | | **[mCSD](https://profiles.ihe.net/ITI/mCSD/index.html)** — *Mobile Care Services Discovery* | Perfil IHE utilizado para consultar organizaciones participantes, servicios y endpoints. En HIX, el endpoint de cada custodio declara además el canal de transporte por el que se lo alcanza. | | **[ATNA](https://profiles.ihe.net/ITI/TF/Volume1/ch-9.html)** — *Audit Trail and Node Authentication* | Perfil IHE que aporta la autenticación de nodos, la confidencialidad en tránsito y el registro de eventos de auditoría. | | **[CT](https://profiles.ihe.net/ITI/TF/Volume1/ch-7.html)** — *Consistent Time* | Perfil IHE que mantiene sincronizados los relojes de todos los sistemas de la comunidad, para que los eventos de auditoría y la vigencia de los tokens signifiquen lo mismo en cada extremo. | | **[BALP](https://profiles.ihe.net/ITI/BALP/index.html)** — *Basic Audit Log Patterns* | Perfil IHE de contenido que define patrones reutilizables de `AuditEvent`. De ellos derivan la mayoría de los eventos de auditoría que cada perfil especifica para sus transacciones. | | **[IUA](https://profiles.ihe.net/ITI/IUA/index.html)** — *Internet User Authorization* | Perfil IHE utilizado por HIX como base de autorización para las interacciones protegidas entre sus participantes. [HIX-1](volume-2-hix-1.html) se apoya además en [RFC 8693](https://www.rfc-editor.org/rfc/rfc8693) y [RFC 8707](https://www.rfc-editor.org/rfc/rfc8707). | | **[SMART App Launch](https://hl7.org/fhir/smart-app-launch/app-launch.html)** | Especificación de HL7 que HIX usa en los flujos interactivos en los que la autorización requiere la participación de una persona desde su navegador. | | **[X-Road](https://x-road.global/)** | Capa de intercambio de datos entre organizaciones sobre transporte mTLS entre servidores de seguridad. HIX la admite como canal entre los participantes, declarado en el directorio. No aporta semántica documental. | | **Record Locator Service** | Actor propio de HIX, no de IHE, responsable de localizar los documentos clínicos disponibles para un paciente y mediar su recuperación desde los custodios correspondientes. En términos IHE agrupa un Document Responder y un Document Consumer de MHD. | Los demás términos, como los de OAuth 2.0 y los propios de HIX, se definen en el [glosario](appendix-glossary.html). ## Cómo leer esta guía HIX organiza sus requisitos en diferentes niveles de abstracción. Los volúmenes de esta guía deben leerse de forma complementaria y no como especificaciones independientes. - El **[Volumen 1](volume-1.html)** describe la arquitectura, es decir, qué hace cada actor y por qué. Sus secciones se numeran 2.x. - El **[Volumen 2](volume-2.html)** detalla las transacciones. Especifica completas las propias de HIX y, de las demás, dice con qué restricciones las usa. Sus secciones se numeran 3.x. - Los **apéndices** reúnen el material de apoyo, por ahora el [glosario](appendix-glossary.html). Quien quiere entender la arquitectura puede leer la [sección 2](volume-1.html), la [2.1](volume-1-concepts.html) y la [2.6](volume-1-security.html), y después la [sección 3](volume-2.html), la [3.2](volume-2-hix-1.html) y la [3.3](volume-2-hix-2.html). Quien implementa un miembro puede empezar por la [sección 2.2](volume-1-actors.html) y la [2.4](volume-1-groupings.html), y seguir con la página del Volumen 2 de cada transacción que implementa. ## Otros formatos La guía se publica también en formatos pensados para leerla fuera del sitio. - **Para asistentes de IA.** [llms.txt](https://hix.meddyg.com/fhir/hix/llms.txt) es un índice en texto plano con una línea por página, que dice de qué trata cada una y enlaza a su versión en Markdown. Un implementador puede dárselo a su agente para que lea solo las páginas que necesita. [llms-full.txt](https://hix.meddyg.com/fhir/hix/llms-full.txt) reúne la guía completa en un solo archivo. Los dos se generan de forma automática en cada publicación, a partir de las mismas páginas que forman este sitio. No hay una segunda redacción, así que su contenido no puede apartarse del de la guía. - **Para leer sin conexión.** El PDF y el documento de Word de cada versión se adjuntan a su publicación en [GitHub](https://github.com/meddyg/Health-Information-Exchange/releases). > **Nota.** Estos archivos sirven para asistir al implementador, no para sustituirlo. Un asistente de IA puede equivocarse al leer o al resumir. El criterio técnico y la responsabilidad sobre lo que se implementa recaen siempre en quien implementa, y el texto que obliga es el de esta guía. ## Dependencias HIX es una guía sobre FHIR R5 que se basa en perfiles IHE publicados sobre R4. De los que compone, solo MHD tiene una edición sobre R5, la [5.0.0](https://profiles.ihe.net/ITI/MHD/history.html), una Trial Implementation que IHE mantiene en paralelo a la línea 4.2.x sobre R4 y que HIX fija. Los demás están solo sobre R4. HIX sigue sus modelos, transacciones y vocabulario sobre R5 sin declarar conformidad con sus artefactos R4, como explica la [sección 2.1](volume-1-concepts.html#relacion-con-mhds). IUA, ATNA y CT no se distribuyen como paquetes FHIR, y por eso no figuran aquí aunque HIX los use. MHDS tampoco figura, porque HIX lo toma como referencia y no depende de su paquete. | Paquete | Versión | Aporta | | --- | --- | --- | | ihe.iti.mhd | 5.0.0 | Publicación, localización y recuperación de documentos (FHIR R5) | | ihe.iti.pmir | 1.6.0 | Identidad maestra del paciente (FHIR R4) | | ihe.iti.pixm | 3.1.0 | Declaración de identidades locales y resolución a la identidad maestra (FHIR R4) | | ihe.iti.pdqm | 3.2.0 | Búsqueda de pacientes por datos demográficos (FHIR R4) | | ihe.iti.mcsd | 4.0.0 | Directorio de organizaciones, servicios y endpoints (FHIR R4) | | ihe.iti.balp | 1.1.4 | Patrones de los eventos de auditoría (FHIR R4) | # Volumen 1. Arquitectura HIX es una comunidad de intercambio de documentos clínicos sobre FHIR. Sigue el modelo que IHE llama **Centralized Discovery and Retrieve**, en el que un localizador central permite descubrir dónde están los documentos y recuperarlos del custodio que registró su existencia ([IHE HIE Whitepaper, §2.8](https://profiles.ihe.net/ITI/HIE-Whitepaper/index.html#28-document-sharing-models))[^hie-cdr]. HIX lo aplica con una variante deliberada, que registra la [Tabla 2.1-3](volume-1-concepts.html#tabla-2-1-3). También la recuperación pasa por ese localizador, de modo que **la localización y la recuperación se median de forma centralizada, mientras la custodia de los documentos permanece distribuida** entre los miembros que los producen. IHE realiza ese modelo sobre FHIR con **[MHDS](https://profiles.ihe.net/ITI/MHDS/volume-1.html)**. HIX lo toma como arquitectura de referencia, sin declarar conformidad con él, y compone directamente los perfiles que resuelven cada pieza, por las razones que da la [sección 2.1](volume-1-concepts.html#relacion-con-mhds). Cada perfil que HIX compone aporta una pieza de esa arquitectura. - **[MHD](https://profiles.ihe.net/ITI/MHD/5.0.0/index.html)** pone las transacciones con las que se publica, localiza y recupera un documento. - **[PMIR](https://profiles.ihe.net/ITI/PMIR/index.html)**, **[PIXm](https://profiles.ihe.net/ITI/PIXm/index.html)** y **[PDQm](https://profiles.ihe.net/ITI/PDQm/index.html)** ponen la identidad maestra del paciente y su vínculo con las identidades locales. - **[mCSD](https://profiles.ihe.net/ITI/mCSD/index.html)** pone el directorio del que la infraestructura central aprende dónde responde cada custodio. - **[IUA](https://profiles.ihe.net/ITI/IUA/index.html)** y OAuth 2.0 ponen los tokens que cruzan cada límite de confianza, con **[SMART App Launch](https://hl7.org/fhir/smart-app-launch/)** cuando quien autoriza es una persona. - **[ATNA](https://profiles.ihe.net/ITI/TF/Volume1/ch-9.html)** con **[BALP](https://profiles.ihe.net/ITI/BALP/index.html)** pone el registro que hace reconstruible cada divulgación. Lo que ningún perfil cubre, como el intercambio de tokens con el que el mediador alcanza a un custodio, y según el despliegue a otros Resource Servers centrales, o el lanzamiento de la aplicación del paciente, HIX lo especifica como transacción propia, identificada como `HIX-n`, en el Volumen 2. ## Infraestructura central ![Infraestructura central de HIX](central-architecture-diagram.svg) **Figura 2-1:** Infraestructura central de HIX La [Figura 2-1](volume-1.html#figura-2-1) muestra la infraestructura central de la comunidad, es decir, los servicios que HIX opera y las transacciones que los conectan. Es una vista de arquitectura, no de despliegue. Omite las agrupaciones transversales que casi todo actor lleva, como el Time Client de CT, y no dibuja los sistemas de los miembros, que solo tratan con la infraestructura central y nunca entre sí. - El **Record Locator Service** es el mediador de la comunidad. Localiza y recupera documentos en nombre de los miembros y aplica la decisión de divulgación. - El **Authorization Server** es el único emisor de tokens de la comunidad. Emite el token con el que un miembro llega al mediador y lo intercambia por otro, acotado al destino que nombra su `resource`, cada vez que el mediador tiene que alcanzar a un custodio y, según el despliegue, a otro Resource Server central. - El **Document Registry** conserva los punteros a los documentos publicados, cada uno con la identidad maestra del paciente como sujeto. - Los **Shared HIE Services** de la figura completan la infraestructura. El directorio de la comunidad describe a los miembros y sus endpoints, el Master Patient Index mantiene una identidad por persona y el Audit Record Repository concentra los eventos de los componentes centrales. - La **fuente autoritativa de identidad** es externa a la comunidad y la única que puede crear identidades maestras. HIX no la designa. La propuesta para Costa Rica es que sea el EDUS, el expediente digital único de la CCSS, que ya tiene resuelta la identificación de las personas. Dicho en seis afirmaciones. 1. La comunidad es **la única contraparte** de sus miembros. **Ningún miembro interactúa con otro.** 2. El **índice es central y el contenido es del custodio**. Un documento se queda donde se produjo, y la comunidad sabe que existe, de quién es y quién lo conserva. 3. La **divulgación se decide una vez por cada consulta**, en la infraestructura central, sobre los metadatos del índice y antes de mover contenido alguno. Localizar y recuperar son dos consultas. 4. Cada recuperación alcanza al custodio con una **credencial derivada de la petición viva del solicitante**, el [token mediado](appendix-glossary.html#token-mediado), que vale para ese único custodio, dura dos minutos como máximo y el custodio verifica por sí mismo. Ningún participante tiene una credencial que valga ante un custodio, ni siquiera el mediador. 5. La **identidad maestra del paciente está anclada en la identidad que verifica la fuente autoritativa**. Los miembros declaran sus identidades locales, la comunidad las vincula y ningún miembro crea una persona. 6. El **transporte hacia cada custodio se declara en el directorio**, no en los punteros ni en la API. Una red de intercambio como [X-Road](https://x-road.global/) puede llevar ese tramo sin que cambie un puntero, un token ni una transacción. ## Cómo leer este volumen - **[2.1 Conceptos y decisiones de arquitectura](volume-1-concepts.html)** explica el porqué de cada decisión y lo que cuesta. - **[2.2 Actores y transacciones](volume-1-actors.html)** define los actores de HIX, las transacciones que los vinculan y los requisitos normativos de cada uno. - **[2.3 Capacidades opcionales de los actores](volume-1-options.html)** describe lo que un actor puede añadir a lo que se le exige. - **[2.4 Agrupaciones de actores requeridas](volume-1-groupings.html)** enumera los actores de otros perfiles que cada actor de HIX agrupa. - **[2.5 Casos de uso y flujos](volume-1-usecases.html)** recorre los escenarios que la arquitectura soporta, con el flujo de cada uno. - **[2.6 Consideraciones de seguridad](volume-1-security.html)** especifica el modelo de confianza, los dos regímenes de token y los controles de seguridad y privacidad. El [Volumen 2](volume-2.html) detalla las transacciones. Este volumen describe qué hace cada actor y por qué, y el siguiente, cómo. ## Referencias [^hie-cdr]: [IHE HIE Whitepaper, §2.8 Document Sharing Models](https://profiles.ihe.net/ITI/HIE-Whitepaper/index.html#28-document-sharing-models): "**Centralized Discovery and Retrieve** – in this model, a centralized locator is used to discover the location of documents which enables a retrieval of the document from a custodian who has registered existence of the document with the centralized locator". [§3 Document Sharing Profiles](https://profiles.ihe.net/ITI/HIE-Whitepaper/index.html#3-document-sharing-profiles) asocia ese modelo a "Mobile access to Health Documents (MHD), Mobile Health Document Sharing (MHDS), and Cross-Enterprise Document Sharing (XDS)". ## Conceptos y decisiones de arquitectura Esta sección explica las decisiones que dan forma a esta comunidad. Cada una se presenta con lo que decide y por qué lo decide, y la [Tabla 2.1-2](volume-1-concepts.html#tabla-2-1-2) resume lo que cuestan. Son decisiones de arquitectura, no de implementación. Una comunidad puede desplegarlas de muchas maneras sin que cambie nada de lo que aquí se describe. La última subsección explica la relación de HIX con MHDS. ### Comunidad y límite de confianza Una comunidad HIX es un conjunto de organizaciones que acuerdan compartir documentos clínicos bajo una política común y a través de una infraestructura común. La pertenencia es explícita. Una organización es miembro cuando figura en el directorio de la comunidad y el Authorization Server reconoce a sus sistemas. **En una malla de pares, las garantías de la comunidad valen lo que valga su miembro más débil.** Ese es el argumento que decide la topología. Si cada miembro descubre y consulta a los demás, cada uno tiene que implementar el descubrimiento y mantener tantas relaciones de confianza como miembros haya. Cada uno tiene que poner además un punto de aplicación de política, el PEP, delante de sus propios datos, y auditar por su cuenta. La política de la comunidad se aplica entonces en tantos lugares como miembros, con la calidad que cada uno pueda pagar, y basta un miembro mal implementado para que la garantía deje de existir para todos. IHE describe tres modelos de intercambio en su whitepaper sobre intercambio de información de salud, entre ellos el centralizado y el federado ([HIE Whitepaper, §2.8](https://profiles.ihe.net/ITI/HIE-Whitepaper/index.html#28-document-sharing-models))[^hie-wp]. HIX elige la centralizada y absorbe esa complejidad una sola vez, en el centro, donde se puede operar, verificar y auditar. Por esta razón, la relación de confianza no se establece de forma directa entre los miembros, sino entre cada miembro y la infraestructura central. Un miembro no confía en los demás ni necesita conocerlos. Confía en que la comunidad autoriza, media y registra cada interacción. Integrarse a HIX es integrarse una sola vez, con la comunidad. No hay que integrarse con cada uno de los demás miembros, ni volver a hacerlo cuando entra uno nuevo. ### Mediación central de la localización y la recuperación Toda localización y toda recuperación pasan por el [Record Locator Service](appendix-glossary.html#record-locator-service), el mediador de la comunidad. Es el único actor que atiende a los miembros cuando localizan y recuperan, y el único que alcanza a un custodio. Un solicitante obtiene de él los punteros que la política le permite ver, y las URL de contenido que recibe apuntan al propio mediador, nunca al custodio. Al recuperar, el mediador alcanza al custodio en nombre del solicitante y le entrega el documento. Para el miembro, la comunidad es un único servidor FHIR, con independencia de cuántos custodios haya y de cómo se llegue a cada uno. MHDS admite que un consumidor alcance directamente al servicio que aloja un documento fuera del Document Registry ([MHDS Vol. 1, §1:50.1.1.2](https://profiles.ihe.net/ITI/MHDS/volume-1.html#150112-storage-of-binary))[^mhds-storage], y reconoce que en ese caso su opción de consentimiento **no protege el contenido** y que cada Document Source carga solo con la protección de sus documentos ([MHDS Vol. 1, §1:50.2.2](https://profiles.ihe.net/ITI/MHDS/volume-1.html#15022-consent-manager-option))[^mhds-consent]. Con custodia distribuida, eso obligaría a cada custodio a evaluar la política de la comunidad frente a cada consumidor. La mediación cierra ese hueco. La política se aplica en un solo lugar, con una única superficie auditable y un único contrato de integración. El precio es que la infraestructura central se vuelve indispensable para operar, y se dimensiona y protege como tal. Todo byte clínico atraviesa el mediador. La [sección 2.6](volume-1-security.html) especifica lo que eso exige. Mediar no es lo mismo que enrutar. El mediador es imprescindible donde hay que alcanzar a un custodio en nombre de un miembro, es decir, al recuperar, porque es quien obtiene el [token mediado](appendix-glossary.html#token-mediado) para ese custodio y recorre el canal que el directorio declara. La decisión de divulgación sobre los punteros es otra cosa. La toma la infraestructura central antes de mover contenido alguno, y la evalúa el mediador o un Document Registry que conozca la política de la comunidad, según dónde la sitúe cada comunidad, como fija la [sección 2.2](volume-1-actors.html#record-locator-service). Como las localizaciones y recuperaciones de los miembros las atiende siempre el mediador, dónde se evalúe es invisible para ellos, y en ningún caso el mediador entrega un puntero o un documento que la decisión niegue. En las transacciones entre un miembro y un solo componente central, como declarar una identidad o publicar un puntero, no hay nada que mediar. El componente que las recibe comprueba que la petición cumple las reglas de la comunidad para esa transacción, por ejemplo que el miembro solo escribe en su propio dominio de identificadores, y la registra en el repositorio de auditoría de la comunidad. Que el mediador actúe además como fachada de esos componentes y les reenvíe esas transacciones es una decisión de infraestructura, como el canal de transporte. No cambia qué actor las responde ni las reglas que aplica, como explica la [sección 2.4](volume-1-groupings.html#sobre-los-despliegues). > **Nota.** Por qué hay un mediador. El flujo de MHDS no lo necesita. Sin él, cada custodio tendría que aplicar la política de la comunidad por su cuenta frente a cada consumidor, con un PEP delante de sus documentos, y auditar por su cuenta, que es el reparto cuyos límites MHDS reconoce. La política se aplicaría en tantos lugares como custodios, con la calidad que cada uno pudiera pagar, y bastaría un custodio mal implementado para que la comunidad dejara de poder garantizar su política, como explica [la apertura de esta sección](volume-1-concepts.html#limite-de-confianza). Cada consumidor tendría que obtener un token para cada custodio y alcanzarlo directamente, y la pregunta de quién accedió a un expediente ya no se respondería desde un solo lugar. La comunidad resultante sería MHDS, no HIX. Dejarían de valer las [afirmaciones 1 y 4 del Volumen 1](volume-1.html#seis-afirmaciones), la comunidad como única contraparte de sus miembros y la credencial derivada de la petición viva del solicitante, y desaparecería [HIX-1](volume-2-hix-1.html), porque ya nadie actuaría en nombre de un solicitante. Por eso el mediador es un actor obligatorio de toda comunidad HIX. ### Custodia distribuida y almacenamiento central El documento permanece donde se produjo. El miembro que lo creó lo conserva, responde por su contenido y participa en cada recuperación que lo alcanza. La infraestructura central mantiene el índice, no una copia del expediente. MHDS admite dos ubicaciones válidas para el contenido, dentro del Document Registry o en cualquier otro lugar de la comunidad, incluido el sistema del propio Document Source ([MHDS Vol. 1, §1:50.1.1.2](https://profiles.ihe.net/ITI/MHDS/volume-1.html#150112-storage-of-binary))[^mhds-storage]. HIX adopta la segunda como **política por defecto** y ofrece la primera como opción. Un custodio que no puede alojar un endpoint ejerce la Opción de Almacenamiento Central y entrega el contenido a la infraestructura central sin dejar de figurar como custodio. Las dos ubicaciones tienen ejemplos nacionales. Estonia recupera cada documento del proveedor que lo produjo, como se ve en la sección de transporte. Suiza hace lo contrario. Cada comunidad de su expediente electrónico almacena los binarios en su propio Document Repository y las instituciones le entregan el documento al publicarlo ([eHealth Suisse, EPR architecture, §3.3.4](https://www.e-health-suisse.ch/payload/api/documents/file/EPD-Architektur_EN.pdf))[^ch-epr-arch]. Su acceso móvil se especifica sobre MHD en [CH EPR FHIR](https://fhir.ch/ig/ch-epr-fhir/index.html). Como la API que ve el solicitante es idéntica bajo ambas ubicaciones, un custodio puede pasar de una a otra sin que ningún miembro lo note. Por eso "el contenido nunca sale del custodio" es una política por defecto y no un principio absoluto. La arquitectura admite las dos y la comunidad decide por custodio. ### Identidad del paciente **Ningún miembro conoce ni usa los identificadores de paciente de los demás miembros**, ni necesita conocerlos. Para la comunidad, cada miembro es un **dominio de identificadores** distinto, y un mismo MRN solo tiene sentido dentro del dominio del miembro que lo asignó. La comunidad no reemplaza los MRN. Mantiene una **identidad maestra** por persona y enlaza con ella las identidades locales que los miembros declaran, de modo que cualquier MRN, de cualquier miembro, resuelve a la misma persona. La identidad maestra es un recurso `Patient` en un dominio reservado a la identidad verificada, en el que solo escribe la fuente autoritativa. Lleva un identificador de la persona que la fuente autoritativa reconoce, la cédula en el caso de la figura, que la ancla a alguien real, la demografía verificada que aporta la fuente autoritativa y los enlaces a sus identidades locales, uno por cada miembro que la haya declarado. Contra esa demografía buscan ITI-78 e ITI-119. No lleva demografía de los miembros. Los nombres y las fechas que cada miembro registra se quedan en él. ![Identidad maestra e identidades locales](hix-master-patient-index.svg) **Figura 2.1-1:** Identidad maestra e identidades locales La [Figura 2.1-1](volume-1-concepts.html#figura-2-1-1) muestra cómo se construye. - La **fuente autoritativa de identidad** es quien crea la identidad maestra. Lo hace con el feed **[PMIR](https://profiles.ihe.net/ITI/PMIR/index.html)** ([ITI-93](https://profiles.ihe.net/ITI/PMIR/ITI-93.html)), una vez que comprobó quién es la persona. Nadie más puede crear una identidad maestra. HIX no designa cuál es esa fuente. La propuesta para Costa Rica es que sea el EDUS, como indica la [introducción del volumen](volume-1.html). - Cada **miembro que publica** declara los pacientes de su dominio con el feed **[PIXm](https://profiles.ihe.net/ITI/PIXm/index.html)** ([ITI-104](https://profiles.ihe.net/ITI/PIXm/ITI-104.html)). Envía su MRN junto con un identificador de la persona que la fuente autoritativa reconoce, y el Master Patient Index enlaza ese MRN con la identidad maestra que ya existe para esa persona. Si la persona todavía no tiene identidad maestra, la declaración se rechaza por defecto, como explica la [sección 2.2](volume-1-actors.html#regla-de-identidad). Si la comunidad traduce identificadores, como describe el apartado sobre [el puntero](volume-1-concepts.html#el-puntero), el miembro no tiene que resolver la identidad maestra antes de publicar ni conservar nada de la respuesta. Nombra al paciente con el identificador que usó para declararlo o con su propio MRN. Si no, la obtiene con ITI-83 cuando la necesita. *Un miembro **vincula**, nunca crea.* Tres consultas responden quién es un paciente, y todas buscan solo entre identidades maestras. La [Tabla 2.1-1](volume-1-concepts.html#tabla-2-1-1) las compara. La tercera da a cada resultado un grado de coincidencia, como exige PDQm ([PDQm, §2:3.119.4.2.2.4](https://profiles.ihe.net/ITI/PDQm/ITI-119.html#231194224-quality-of-match)), y los ordena de más a menos probable, como describen los casos de ITI-119[^pdqm-match]. **Tabla 2.1-1:** Consultas de identidad | Consulta | Transacción | Qué recibe | Qué devuelve | Cuándo se usa | | --- | --- | --- | --- | --- | | Por identificador | [ITI-83](https://profiles.ihe.net/ITI/PIXm/ITI-83.html) de PIXm | Un MRN o un identificador que la fuente autoritativa reconoce | La identidad maestra enlazada a él | Es la vía normal. La usan también el Document Registry, al indexar y al resolver el identificador de una consulta, y el Authorization Server al fijar el contexto de paciente | | Por datos demográficos | [ITI-78](https://profiles.ihe.net/ITI/PDQm/ITI-78.html) de PDQm | Criterios como el nombre o la fecha de nacimiento | Las identidades maestras que coinciden con ellos | Cuando no hay un identificador fiable | | Por coincidencia probabilística | [ITI-119](https://profiles.ihe.net/ITI/PDQm/ITI-119.html) de PDQm | Los datos de un candidato | Las identidades maestras que más se le parecen, de más a menos probable | Cuando los datos están incompletos o pueden traer errores, como un apellido mal escrito | > **Nota.** Un miembro no puede crear una persona, fusionar dos personas ni escribir en el dominio de otro. Sobre las identidades locales de su propio dominio decide él. Y ninguna de las tres consultas prueba una identidad. Eso solo lo hace la fuente autoritativa. ### El puntero La unidad del índice es el puntero, un [`DocumentReference`](https://hl7.org/fhir/R5/documentreference.html) de FHIR R5 que describe un documento sin contenerlo. Toda decisión de la comunidad se toma sobre el puntero, antes de mover un byte del documento, así que lo que el puntero lleva es una decisión de arquitectura. Estos son sus elementos. - **`subject`** apunta a la identidad maestra del paciente en todo puntero que la comunidad registra, nunca a una identidad local. Cómo llega esa identidad al puntero es una decisión de despliegue. La comunidad puede exigir que el custodio publique ya con la identidad maestra, que obtiene con ITI-83, o puede traducir al indexar el identificador con el que el custodio nombra al paciente. Si traduce el identificador de la persona que la fuente autoritativa reconoce, usa la referencia lógica que MHD admite cuando existe un identificador común ([MHD, §2:3.65.4.1.2.2](https://profiles.ihe.net/ITI/MHD/5.0.0/ITI-65.html#23654122-patient-identity))[^mhd-patient]. Si traduce además el MRN del custodio, en su propio dominio, se aparta de MHD, que solo admite la referencia lógica por un identificador común, y la [Tabla 2.1-3](volume-1-concepts.html#tabla-2-1-3) lo declara. Con la traducción, ningún miembro tiene que resolver identidades antes de publicar. El Document Registry resuelve el `subject` con la consulta por identificador y escribe en él la identidad maestra al indexar, como muestra la [sección 3.5](volume-2-publication.html#iti-65). En cualquier caso, el puntero queda registrado con la identidad maestra. - **`sourcepatient`** es una extensión que nombra a la identidad local con una referencia lógica, es decir, con el identificador del paciente en el dominio del custodio y sin referencia a ningún recurso, porque ningún actor de la comunidad sirve las identidades locales. Es la extensión estándar [`documentreference-sourcepatient`](https://hl7.org/fhir/extensions/StructureDefinition-documentreference-sourcepatient.html), que en R5 reemplaza a `context.sourcePatientInfo`. Conserva la traza de qué miembro declaró a quién y permite volver a resolver `subject` si un enlace de identidad cambia. Todo puntero registrado lleva los dos, `sourcepatient` hacia la identidad local y `subject` hacia la identidad maestra. - **`custodian.identifier`** nombra a la organización responsable con el mismo identificador que lleva su token y que publica el directorio. Nunca es una referencia a un recurso. - **`content.attachment.url`** es una ruta relativa al endpoint del custodio cuando el contenido queda en él. Bajo la Opción de Almacenamiento Central apunta al contenido que conserva el Document Registry. Un puntero nunca contiene una dirección física ni nada que identifique un transporte. Cuando el contenido queda en el custodio, la dirección se resuelve en el directorio en cada recuperación. - **`securityLabel`** lleva la [etiqueta de confidencialidad](https://hl7.org/fhir/R5/security-labels.html) del documento, un código del sistema [v3-Confidentiality](https://terminology.hl7.org/CodeSystem-v3-Confidentiality.html) de HL7, como `N` para normal, `R` para restringido o `V` para muy restringido. Es obligatorio desde la primera publicación. Sin la etiqueta en el índice, decidir si un documento se puede divulgar exigiría leerlo primero, y añadirla después obligaría a releer todos los documentos en los custodios. - **`identifier`** es el identificador de negocio del documento. Identifica una versión concreta, de modo que publicar dos veces la misma versión no duplica el puntero. Una versión nueva no sobrescribe el puntero anterior. Se publica como un puntero nuevo que declara en `relatesTo` que reemplaza al anterior, y el anterior pasa a estado `superseded`, como fija MHD ([MHD, §2:3.65.4.1.2.3](https://profiles.ihe.net/ITI/MHD/5.0.0/ITI-65.html#23654123-replace-transform-signs-and-append-associations))[^mhd-replace]. Así el índice conserva la historia de cada documento. El resto de elementos, como `status`, `type` o `date`, son los metadatos habituales de MHD y se especificarán más adelante en esta guía. Un puntero nunca se publica suelto. Cada publicación es un ITI-65 con un SubmissionSet, un recurso `List` que agrupa los punteros publicados juntos y dice quién los publicó y cuándo, y puede llevar además carpetas, que también son recursos `List` ([MHD, §2:3.65.4.1.2](https://profiles.ihe.net/ITI/MHD/5.0.0/ITI-65.html#2365412-message-semantics))[^mhd-bundle]. El Document Registry conserva esas listas junto a los punteros, y son lo que devuelve ITI-66. Por eso la decisión de divulgación se aplica también a ellas, y las fusiones de identidad alcanzan a su `subject` igual que al de los punteros. ### Directorio de la comunidad El directorio describe las organizaciones participantes, su pertenencia a la comunidad y los endpoints en los que responden. Es la fuente de la que la infraestructura central aprende a quién dirigir una recuperación, por qué canal y qué opciones ejerce cada custodio. Los miembros no consultan el directorio, porque nunca se comunican entre sí. Lo consulta el mediador, en cada recuperación cuyo contenido queda en el custodio, para saber a qué custodio dirigirse y en qué endpoint, y el Document Registry, para comprobar que quien publica es un miembro activo. Por eso incorporar un miembro no exige reconfigurar nada. Basta con darlo de alta en el directorio para que el mediador pueda alcanzarlo. Un custodio puede tener más de un endpoint, porque mCSD lo admite ([mCSD, §1:46.8.2](https://profiles.ihe.net/ITI/mCSD/volume-1.html#14682-endpoint-content))[^mcsd-endpoints]. Con qué criterio elige el mediador entre ellos es política de la comunidad. Si el directorio no devuelve ninguno activo, el mediador trata al custodio como no disponible. El directorio fija dos valores que se usan tal cual en toda la comunidad. El **identificador de la organización** es el mismo que el Authorization Server incluye en los tokens del miembro para decir en nombre de qué organización actúa, y el mismo que sus punteros llevan en `custodian.identifier`. La **dirección del endpoint** es la URL a la que el mediador llama, la audiencia del token que obtiene para ese custodio y la base contra la que se resuelven las rutas relativas de sus punteros. Como token, puntero y directorio parten del mismo valor, no pueden desincronizarse. ### Autorización y delegación HIX usa OAuth 2.0 ([RFC 6749](https://www.rfc-editor.org/rfc/rfc6749)) según lo perfila [IUA](https://profiles.ihe.net/ITI/IUA/index.html). La idea de fondo es sencilla. Para hablar con la comunidad, un sistema necesita un token, y todos los tokens los emite un único Authorization Server. Un miembro obtiene un token para hablar con los actores centrales que atienden sus transacciones, y solo con ellos. Ese token no sirve ante ningún custodio, y el miembro nunca recibe uno que sirva. El mediador comprueba cada token que recibe preguntando al Authorization Server si sigue siendo válido. Esa consulta es la introspección de [RFC 7662](https://www.rfc-editor.org/rfc/rfc7662), que IUA recoge como la transacción Introspect Token ([ITI-102](https://profiles.ihe.net/ITI/IUA/index.html#3102-introspect-token-iti-102)). Cuando una operación exige llegar a un custodio, el mediador no reutiliza el [token del solicitante](appendix-glossary.html#token-del-solicitante). Lo **intercambia** por otro, siguiendo OAuth 2.0 Token Exchange ([RFC 8693](https://www.rfc-editor.org/rfc/rfc8693)) con un resource indicator ([RFC 8707](https://www.rfc-editor.org/rfc/rfc8707)). Presenta al Authorization Server el token del solicitante y pide a cambio uno nuevo, hecho a la medida de esa llamada. Vale para ese solo custodio y un solo tipo de transacción, dura como mucho dos minutos y dice dentro quién pidió y quién actúa en su nombre. La [Tabla 2.6-1](volume-1-security.html#tabla-2-6-1) detalla lo que lleva. El custodio valida ese token por su cuenta, con las claves públicas del Authorization Server, sin tener que preguntarle. Así sabe quién pregunta, en nombre de quién actúa la comunidad y para qué. Ante los actores centrales desplegados como sistemas distintos, el mediador actúa con tokens mediados, que es lo que esta guía recomienda, o con un token propio si la comunidad lo autoriza, como fija la [sección 2.2](volume-1-actors.html#record-locator-service). Solo ITI-90 escapa al scope del solicitante, y por eso HIX-1 lo admite por la delegación registrada. Cada llamada atiende una operación autorizada de un solicitante. Cuando los componentes forman un mismo sistema, la llamada es interna. El mediador es el primer punto de aplicación de la política de la comunidad, no un participante con autoridad propia. La [Figura 2.1-2](volume-1-concepts.html#figura-2-1-2) resume el recorrido de los tokens. Un solo token entra por la izquierda, el del miembro, y de él derivan los tokens mediados para alcanzar custodios y componentes centrales desplegados como sistemas distintos. Hacia los componentes centrales, la comunidad puede autorizar en su lugar un token propio del mediador. ![Delegación de tokens en HIX](hix-delegacion.svg) **Figura 2.1-2:** Delegación de tokens en HIX Tres reglas hacen que el mínimo privilegio sea estructural, en lugar de depender de la buena conducta de cada parte. - **Un token, el destino mínimo.** Cada token vale solo ante quien tiene que recibirlo. El mediado nunca vale ante dos custodios, porque entonces uno de ellos podría usarlo contra el otro. - **Solo el mediador puede intercambiar.** Ningún otro participante puede pedir un token a nombre de un tercero, y los custodios no aceptan tokens llegados por otro camino. - **La autoridad documental nunca crece.** Para localizar y recuperar documentos, el token mediado solo permite lo que el solicitante ya podía y lo que la comunidad delega al mediador ante el destino. Solo ITI-90, que ningún solicitante tiene en su scope, se autoriza por la delegación registrada. Poder localizar un documento nunca da poder para recuperarlo. Un token dice quién pide, qué puede pedir, ante quién y hasta cuándo. El token de un miembro **no nombra a ningún paciente**. Solo lo hace el de una persona que entra a su propio expediente con [SMART App Launch](https://hl7.org/fhir/smart-app-launch/scopes-and-launch-context.html), y ahí el contexto de paciente sirve para confinar el token a ese expediente. La cuenta con la que esa persona entra no es un identificador de paciente. El Authorization Server resuelve el contexto de paciente contra la identidad maestra con la consulta por identificador. En ambos casos, **tener un token da derecho a preguntar, no a ver**. Qué documentos se entregan lo decide la infraestructura central, puntero por puntero. Esa separación es la idea más importante de este volumen. ### Divulgación La decisión de divulgación se toma en la infraestructura central, **sobre los punteros y antes de recuperar contenido alguno**. La toma el mediador o, cuando la comunidad la sitúa allí, el Document Registry. Quien la toma combina dos fuentes. Del token toma lo que el Authorization Server avaló del solicitante, es decir, su organización, su propósito de uso y, cuando existe, el contexto de paciente. Del puntero toma el paciente, la etiqueta de confidencialidad, el tipo de documento y el custodio. Nada de lo que el solicitante afirme de sí mismo en la petición cuenta. Ese orden es lo que hace que centralizar valga su costo. Un puntero cuya divulgación se niega no genera ninguna recuperación, ninguna consulta al directorio y ningún token. La decisión se toma una vez por consulta, y un documento atraviesa dos, porque revelar que existe ya es una divulgación. Al localizar, se filtran los punteros de la respuesta. Al recuperar, el mediador vuelve a evaluar el puntero pedido antes de alcanzar al custodio. Un puntero negado no aparece en la respuesta ni se anuncia como negado. El punto de partida es un entorno de consentimiento implícito, con una política única para toda la comunidad. MHDS lo describe en su Consent Manager Option como el entorno en el que se permite divulgar mientras el paciente no haya registrado un consentimiento ([MHDS Vol. 1, §1:50.2.2](https://profiles.ihe.net/ITI/MHDS/volume-1.html#15022-consent-manager-option))[^mhds-implied]. El destino es [PCF](https://profiles.ihe.net/ITI/PCF/volume-1.html#1534-pcf-overview), donde las directivas de consentimiento de cada paciente se evalúan en cada petición ([PCF Vol. 1, §1:53.4](https://profiles.ihe.net/ITI/PCF/volume-1.html#1534-pcf-overview))[^pcf]. La Opción de Consentimiento declara dónde se aplica esa decisión y qué información necesita. **El modelo de consentimiento se especificará en una versión posterior de esta guía a partir de PCF.** ### Auditoría en ambos extremos Cada participante registra lo que hace. Es lo que [ATNA](https://profiles.ihe.net/ITI/TF/Volume1/ch-9.html) exige a todo sistema que se declara [Secure Node o Secure Application](appendix-glossary.html#secure-node) ([ITI TF-1, §9.1.1.1](https://profiles.ihe.net/ITI/TF/Volume1/ch-9.html#9.1.1.1) y [§9.1.1.2](https://profiles.ihe.net/ITI/TF/Volume1/ch-9.html#9.1.1.2))[^atna-node] y lo que MHDS exige a su Document Registry ([MHDS Vol. 1, §1:50.1.1.1](https://profiles.ihe.net/ITI/MHDS/volume-1.html#150111-document-registry))[^mhds-audit]. Los registros siguen los patrones de [BALP](https://profiles.ihe.net/ITI/BALP/index.html), que definen cómo se escribe un `AuditEvent` de FHIR para cada tipo de evento. La infraestructura central registra la solicitud que recibe del miembro y la recuperación que ella misma inicia hacia el custodio. El custodio registra la entrega. Los registros de una misma divulgación comparten un identificador de correlación. El mediador lo genera al recibir la solicitud y lo transmite al custodio en cada llamada. BALP prevé este uso y reserva un elemento del `AuditEvent` para guardar el identificador de la petición y correlacionar los registros de cliente y servidor ([BALP, §3:5.7.3.1](https://profiles.ihe.net/ITI/BALP/content.html#35731-x-request-id-header))[^balp-corr]. Así una divulgación se puede reconstruir completa desde sus dos lados. El token mediado nombra al solicitante original y al mediador como actor. Por eso el custodio registra quién pidió el documento y en nombre de quién actuó la comunidad, y no solo que lo pidió la comunidad. Ningún registro contiene un token completo ni contenido clínico. Basta un identificador del token, como su `jti`, para atar el evento a él. Todos los componentes centrales registran en el mismo [Audit Record Repository](appendix-glossary.html#audit-record-repository) de ATNA, el repositorio de auditoría de la comunidad. Como además toda divulgación pasa por el mediador, la pregunta "quién accedió al expediente de esta persona" se responde desde un solo lugar, ese repositorio. Cómo se consulta se especificará más adelante, como señala la [descripción general](index.html). Eso no exime a ningún custodio de registrar su lado. ### Transporte y redes de intercambio La dirección física de un custodio vive únicamente en el directorio. El puntero lleva una organización y una ruta relativa. Cuando el contenido queda en el custodio, el mediador resuelve la dirección en cada recuperación y llega al custodio por el canal que el directorio declara para él. Ese canal puede ser una conexión directa o una red de intercambio ya establecida, como [X-Road](https://x-road.global/). En ambos casos el puntero, la API que ven los miembros y el modelo de tokens son los mismos. Cambiar de canal es cambiar un dato del directorio. Una red de intercambio resuelve cómo se conectan las organizaciones y cómo se identifican entre sí. No dice nada de documentos, punteros ni consentimiento. Por eso HIX la usa solo entre cada miembro y la infraestructura central, nunca entre miembros. Si los miembros la usaran para hablar entre sí, volverían a la malla de pares que HIX descarta. Estonia sigue este mismo patrón. Su registro nacional de salud recupera los datos de cada proveedor cuando se necesitan y los presenta en un formato común ([e-Estonia](https://e-estonia.com/solutions/healthcare/e-health-records/))[^estonia], y los sistemas de información del país se conectan entre sí sobre X-Road ([e-Estonia](https://e-estonia.com/solutions/interoperability-services/x-road/))[^estonia-xroad]. El token mediado sigue viajando por ese canal y el custodio sigue validándolo. La identidad que la red asigna a cada organización no lo sustituye. ### Comunidades vecinas Una comunidad HIX puede conectarse con otras comunidades mediante [XCA](https://profiles.ihe.net/ITI/TF/Volume1/ch-18.html). La pasarela, con sus Initiating Gateway y Responding Gateway, se agrupa en la infraestructura central junto al Record Locator Service, que la consulta al localizar y al recuperar, así que la mediación se conserva y ningún miembro habla con la otra comunidad. Esta guía no la especifica. ### Compromisos asumidos IHE deja la gobernanza fuera de su alcance. Declara que no define políticas de privacidad ni de seguridad, y que el marco de políticas de una comunidad debe definirse antes de construirla ([MHDS Vol. 1, §1:50.5](https://profiles.ihe.net/ITI/MHDS/volume-1.html#1505-mhds-security-considerations) y [§1:50.5.1](https://profiles.ihe.net/ITI/MHDS/volume-1.html#15051-policies-and-risk-management))[^mhds-policy]. Por eso, de los compromisos de la tabla, el que más pesa es la apuesta por la operación del centro. **Tabla 2.1-2:** Compromisos de la arquitectura | Compromiso | Qué se acepta | Cómo se mitiga | | --- | --- | --- | | Acoplamiento de disponibilidad | Una recuperación mediada necesita al mediador, al Authorization Server y al custodio a la vez | La localización no depende de los custodios. Una recuperación ante un custodio caído falla sin confundirse con un documento inexistente. Cualquier custodio puede pasar a almacenamiento central sin que nadie lo note | | Contenido en tránsito por el centro | Todo byte clínico atraviesa el mediador, que lo ve en claro | El mediador no guarda ni registra contenido. El canal entre organizaciones va cifrado. El índice se gobierna como dato sensible | | Authorization Server en el camino crítico | Cada operación exige una introspección del token del solicitante y un intercambio por cada destino que el mediador alcanza | Se dimensiona con la misma disponibilidad que el mediador. Un token mediado vale solo ante el destino que nombra su `resource`, nunca ante dos custodios, y dura como mucho dos minutos, así que un token filtrado tiene una ventana de uso corta y conocida | | Apuesta por la operación del centro | La garantía de la comunidad vale lo que valga la operación de su infraestructura central. Un centro bien operado supera a una federación operada a medias, y un centro mal operado es peor que esa federación | Quién certifica miembros, quién responde al paciente y quién financia el centro se fija en la gobernanza de la comunidad, antes de construirla. Es su riesgo principal a largo plazo | ### Relación con MHDS HIX sigue la forma de comunidad que describe [MHDS](https://profiles.ihe.net/ITI/MHDS/volume-1.html), con una infraestructura central de servicios compartidos y miembros que publican y consumen a través de ella, y toma de él buena parte de su vocabulario. No declara conformidad con MHDS. Sigue los perfiles que MHDS compone, que son los que se mantienen, se prueban y se distribuyen como paquetes versionados. Como la mayoría solo se publica sobre FHIR R4, HIX sigue sus modelos, transacciones y vocabulario sobre FHIR R5 sin declarar conformidad con sus artefactos R4, mientras IHE no publique ediciones R5. Hay dos razones. La primera es que la última publicación de MHDS es de agosto de 2023 y está hecha sobre FHIR R4[^mhds-version], y los perfiles que compone siguieron cambiando después. [MHD se publicó sobre FHIR R5](https://profiles.ihe.net/ITI/MHD/5.0.0/index.html) y mCSD rehízo y renombró todos sus actores ([mCSD, Significant Changes](https://profiles.ihe.net/ITI/mCSD/issues.html#significant-changes))[^mcsd-rename], de modo que MHDS nombra hoy actores que mCSD ya no define. La segunda es que HIX no ejerce algunas de sus opciones. Bajo su Authorization Option, MHDS agrupa el Document Registry con el Authorization Server ([MHDS Vol. 1, §1:50.2.1](https://profiles.ihe.net/ITI/MHDS/volume-1.html#15021-authorization-option))[^mhds-as-grouping], y bajo su Consent Manager Option deja en este la gestión del consentimiento ([MHDS Vol. 1, §1:50.2.2](https://profiles.ihe.net/ITI/MHDS/volume-1.html#15022-consent-manager-option))[^mhds-consent-as]. HIX quiere un único emisor para varios Resource Servers, el despliegue que IUA prevé al no atar el Authorization Server a los Resource Servers ([IUA, Relation to SMART-on-FHIR](https://profiles.ihe.net/ITI/IUA/index.html#relation-to-smart-on-fhir))[^iua-loose]. De ahí salen dos reglas. Cuando MHDS y un perfil vigente dicen cosas distintas, prevalece el perfil vigente. Cuando MHDS y una decisión de HIX dicen cosas distintas, esta guía declara en qué se aparta y por qué. La [Tabla 2.1-3](volume-1-concepts.html#tabla-2-1-3) reúne lo que HIX toma de MHDS y lo que no. **Tabla 2.1-3:** Lo que HIX toma de MHDS y lo que no | Asunto | En MHDS | En HIX | | --- | --- | --- | | Forma de la comunidad | Infraestructura central de servicios compartidos, con miembros que publican y consumen | La misma | | Document Registry | Actor propio de MHDS, con sus opciones | Actor de HIX con el mismo nombre y la misma función, definido por los actores que agrupa en la [sección 2.4](volume-1-groupings.html) | | Acceso de quien consulta | Directo al Document Registry y, si el contenido está fuera de él, al servicio que lo aloja | Siempre a través del Record Locator Service | | URL del contenido fuera del Document Registry | Una URL persistente al `Binary` | Una ruta relativa al endpoint del custodio, que se resuelve en el directorio en cada recuperación | | Identidad que aporta un miembro | El miembro crea y actualiza identidades en el registro de la comunidad, como Patient Identity Source de PMIR | El miembro declara sus identidades locales con ITI-104 de PIXm y nunca crea una persona | | Identificador con el que un miembro nombra al paciente | Una referencia al Patient de la comunidad o una referencia lógica por un identificador común, como el nacional, que es lo que MHD admite | Además, si la comunidad lo autoriza, una referencia lógica por el identificador del propio dominio del miembro, que el Document Registry traduce con ITI-83 al publicar, al localizar o en ambos casos | | Authorization Server | Agrupado con el Document Registry bajo la Authorization Option | Servicio central independiente y único emisor de la comunidad | | Consentimiento | Lo gestiona y decide el Authorization Server agrupado | La decisión de divulgación se toma sobre los punteros en la infraestructura central, no en el Authorization Server. Eso no impide adoptar PCF más adelante, con los actores que defina | | Versiones | FHIR R4 y las versiones de los perfiles vigentes en 2023 | FHIR R5 y la versión vigente de cada perfil | | Conformidad | Declarada con los perfiles sobre FHIR R4 | Sigue sus modelos, transacciones y vocabulario sobre FHIR R5, sin declarar conformidad con sus artefactos R4 | El apartamiento de más peso es el de la identidad. MHDS deja que los participantes creen y actualicen identidades en el registro de la comunidad ([MHDS Vol. 1, §1:50.1](https://profiles.ihe.net/ITI/MHDS/volume-1.html#1501-mhds-actors-transactions-and-content-modules))[^mhds-identity]. HIX reserva esa facultad a la fuente autoritativa, como explica el apartado sobre la [identidad del paciente](volume-1-concepts.html#identidad-del-paciente), para que ningún miembro pueda crear una persona. ### Referencias Las citas reproducen el texto publicado por su fuente. Los recortes se marcan con "[...]" y la negrita es de esta guía. [^mhds-consent]: [MHDS Vol. 1, §1:50.2.2 Consent Manager Option](https://profiles.ihe.net/ITI/MHDS/volume-1.html#15022-consent-manager-option): "Note that this option **does not protect Binary content stored outside of the Document Registry** [...]. When documents are stored outside of the Document Registry, **the Document Source system takes on the burden of protecting the document**." [^mhds-storage]: [MHDS Vol. 1, §1:50.1.1.2 Storage of Binary](https://profiles.ihe.net/ITI/MHDS/volume-1.html#150112-storage-of-binary): "(1) The Document Source includes the Binary Resource in the [ITI-65] transaction, and the Document Registry is required to store it. (2) **The Community allows the Binary to be stored elsewhere in the Community.** [...] This might be other centralized infrastructure, distributed infrastructure, or **within the system implementing the Document Source**. [...] the service hosting the Binary shall: [...] **provide access to the community members**". [^hie-wp]: [IHE HIE Whitepaper, §2.8 Document Sharing Models](https://profiles.ihe.net/ITI/HIE-Whitepaper/index.html#28-document-sharing-models): "IHE has enabled **three distinct Document Sharing Models** [...] Centralized Discovery and Retrieve – in this model, a centralized locator is used to discover the location of documents which enables **a retrieval of the document from a custodian** who has registered existence of the document with the centralized locator" y "Federated Discovery and Retrieve – in this model, **a collection of peer entities are enabled to query each other** to locate documents of interest [...] the centralized model **requires knowledge only of the centralized locator** [...]" [^mhds-implied]: [MHDS Vol. 1, §1:50.2.2 Consent Manager Option](https://profiles.ihe.net/ITI/MHDS/volume-1.html#15022-consent-manager-option): "The grouped IUA Authorization Server SHALL support consent configuration to enable Implied Consent and Explicit Consent environments. **Implied Consent environments allow disclosure when no Consent has been recorded for that patient**, Explicit Consent environments Deny disclosure when no Consent has been recorded for that patient." [^pcf]: [PCF Vol. 1, §1:53.4 PCF Overview](https://profiles.ihe.net/ITI/PCF/volume-1.html#1534-pcf-overview): "The PCF Profile enables authorized access to data according to terms agreed by the Patient and the Organization protecting the data." [§1:53.1.1.3 Consent Authorization Server](https://profiles.ihe.net/ITI/PCF/volume-1.html#153113-consent-authorization-server): "The Consent Authorization Server **makes authorization decisions based on a given access requested context** (e.g., oAuth, query/operation parameters), organizational policies, and **current active Consent resources**." [^atna-node]: [ITI TF-1, §9.1.1.1 Secure Node](https://profiles.ihe.net/ITI/TF/Volume1/ch-9.html#9.1.1.1): "Detect and report a Record Audit Event as specified in ITI TF-2: 3.20 for: **all of the activity-related events for the Secure Node** [...] **all transaction-related events for the Secure Node**". La Secure Application tiene el mismo requisito en [§9.1.1.2](https://profiles.ihe.net/ITI/TF/Volume1/ch-9.html#9.1.1.2). [^mhds-audit]: [MHDS Vol. 1, §1:50.1.1.1 Document Registry](https://profiles.ihe.net/ITI/MHDS/volume-1.html#150111-document-registry): "The Document Registry **SHALL record all security relevant events** to ATNA Audit Record Repository with the “ATX: FHIR Feed” Option." [^mhds-policy]: [MHDS Vol. 1, §1:50.5 MHDS Security Considerations](https://profiles.ihe.net/ITI/MHDS/volume-1.html#1505-mhds-security-considerations): "**The policy landscape that the community is built on needs to be defined well before the community is built.**" [§1:50.5.1 Policies and Risk Management](https://profiles.ihe.net/ITI/MHDS/volume-1.html#15051-policies-and-risk-management): "IHE solves interoperability problems via the implementation of technology standards. **It does not define Privacy or Security Policies**, Risk Management, Healthcare Application Functionality, Operating System Functionality, Physical Controls, or even general Network Controls." [^balp-corr]: [BALP, §3:5.7.3.1 X-Request-Id header](https://profiles.ihe.net/ITI/BALP/content.html#35731-x-request-id-header): "Where it is known that an http RESTful transaction included an X-Request-Id, that value should be recorded in an .entity dedicated to X-Request-Id. **This ID can be used to correlated AuditEvents from client and server**, and may aid with correlation on further activities recorded caused by the transaction." [^ch-epr-arch]: [eHealth Suisse, EPR architecture. A detailed description, §3.3.4 XDS Document Repositories](https://www.e-health-suisse.ch/payload/api/documents/file/EPD-Architektur_EN.pdf): "The Document Repository Service implements interfaces to **store and query the binary objects** of the XDS documents. **The data are captured by the connected systems of the (core) communities when documents are saved** and are registered via interfaces." [^estonia]: [e-Estonia, e-Health Record](https://e-estonia.com/solutions/healthcare/e-health-records/): "the e-Health Record actually **retrieves data as necessary from various providers**, who may be using different systems" and "presents it in a standard format". [^estonia-xroad]: [e-Estonia, X-Road](https://e-estonia.com/solutions/interoperability-services/x-road/): "X-Road®, an open-source software and ecosystem solution that provides unified and secure data exchange between private and public sector organisations, **is the backbone of e-Estonia**. Invisible yet crucial, it allows the nation’s various public and private sector e-service information systems to link up and function in harmony." [^mhds-version]: [MHDS, pie de la publicación vigente](https://profiles.ihe.net/ITI/MHDS/index.html): "Package ihe.iti.mhds#2.3.1 based on FHIR 4.0.1. Generated 2023-08-04" [^mcsd-rename]: [mCSD, Significant Changes](https://profiles.ihe.net/ITI/mCSD/issues.html#significant-changes): "**Reworked all Actors to improve clarity**", con la tabla de equivalencias "New Actor (with Option) | Old Actor", que incluye "Directory | Care Services Selective Supplier" y "Query Client | Care Services Selective Consumer". [^mhds-as-grouping]: [MHDS Vol. 1, §1:50.2.1 Authorization Option](https://profiles.ihe.net/ITI/MHDS/volume-1.html#15021-authorization-option): "**The Document Registry SHALL be grouped with an IUA Resource Server and the IUA Authorization Server Actors.** The IUA Authorization Server Metadata Option shall be supported." [^mhds-consent-as]: [MHDS Vol. 1, §1:50.2.2 Consent Manager Option](https://profiles.ihe.net/ITI/MHDS/volume-1.html#15022-consent-manager-option): "**The grouped IUA Authorization Server would be used to manage the consent status and make authorization decisions based on the consent status.** [...] The IUA Resource Server that is grouped with the MHDS Document Registry would enforce these decisions." [^iua-loose]: [IUA, Relation to SMART-on-FHIR](https://profiles.ihe.net/ITI/IUA/index.html#relation-to-smart-on-fhir): "**IUA promotes a loose coupling of Resource Server and Authorization Servers.** This allows for deployments with multiple Resource Servers per Authorization Server as well as deployments with several or even no Authorization Servers." [^mhds-identity]: [MHDS Vol. 1, §1:50.1 MHDS Actors, Transactions, and Content Modules](https://profiles.ihe.net/ITI/MHDS/volume-1.html#1501-mhds-actors-transactions-and-content-modules): "PMIR – Patient Identity Source and Patient Identity Registry – to provide patient identity lookup by demographics or identity, and **to receive create and update of patient identity from participants**" [^mhd-patient]: [MHD, §2:3.65.4.1.2.2 Patient Identity](https://profiles.ihe.net/ITI/MHD/5.0.0/ITI-65.html#23654122-patient-identity): "**A commonly accessible logical reference using Patient Identifier, instead of a literal reference, may be acceptable where there is a common Identifier, such as a national individual identifier.**" [^mhd-replace]: [MHD, §2:3.65.4.1.2.3 Replace, Transform, Signs, and Append Associations](https://profiles.ihe.net/ITI/MHD/5.0.0/ITI-65.html#23654123-replace-transform-signs-and-append-associations): "The relatesTo.target element in the provided DocumentReference points at the pre-existing DocumentReference that is being replaced, transformed, signed, or appended. [...] **If a DocumentReference is being replaced, that DocumentReference needs to have the status element updated to superseded within the transaction bundle** with the UpdateDocumentsRef slice". [^mcsd-endpoints]: [mCSD, §1:46.8.2 Endpoint Content](https://profiles.ihe.net/ITI/mCSD/volume-1.html#14682-endpoint-content): "The Endpoint.connectionType and specificType extension indicate the type of connectivity enabled by the Endpoint. As such, **Organization and OrganizationAffiliation Resources MAY have many Endpoints** for the various types of connectivity they support." [^pdqm-match]: [PDQm, §2:3.119.4.1.3 Expected Actions](https://profiles.ihe.net/ITI/PDQm/ITI-119.html#23119413-expected-actions): "The results are ordered from most likely to least likely." [§2:3.119.4.2.2.4 Quality of Match](https://profiles.ihe.net/ITI/PDQm/ITI-119.html#231194224-quality-of-match): "**The Patient Demographics Supplier SHALL convey the quality of each match** based on strength of the particular result to the supplied Patient Resource. [...] it SHALL represent the confidence of a particular match within the bundle as a score attribute." [^mhd-bundle]: [MHD, §2:3.65.4.1.2 Message Semantics](https://profiles.ihe.net/ITI/MHD/5.0.0/ITI-65.html#2365412-message-semantics): "The Document Source shall initiate a FHIR “transaction” using a “create” action by sending an HTTP POST request method composed of a FHIR Bundle Resource containing: **one SubmissionSet type List Resource; one or more DocumentReference Resources; zero or more Folder type List Resources; and zero or more Binary Resources** to the Document Recipient." ## Actores y transacciones Esta sección define los actores de HIX y las transacciones que los vinculan. Los actores y transacciones tomados de un perfil IHE conservan el significado que les da su especificación de origen. Las transacciones identificadas como `HIX-n` son propias de esta guía y se especifican en el Volumen 2. HIX distingue tres clases de actor. Los **actores centrales** los opera la comunidad. Los **actores de miembro** los opera cada organización participante. La **fuente autoritativa de identidad** es externa a la comunidad. Un miembro solo trata con la infraestructura central, nunca con otro miembro. Obtiene sus tokens del Authorization Server, localiza y recupera a través del Record Locator Service, publica ante el Document Registry y declara identidades ante el Master Patient Index, que validan esas transacciones como describe la [sección 2.1](volume-1-concepts.html). Las tres pestañas siguientes muestran a los actores de miembro en su escenario típico. La aplicación del paciente es la de una persona que entra a su propio expediente. El hospital es un sistema que consume documentos, en atención normal y en una emergencia, donde por ejemplo busca al paciente por sus datos demográficos con PDQm. El laboratorio es un sistema que publica y custodia documentos. ![Aplicación del paciente ante la comunidad](hix-actores-paciente.svg) **Figura 2.2-1:** Aplicación del paciente ante la comunidad ![Hospital que consulta, en atención normal y en emergencia](hix-actores-hospital.svg) **Figura 2.2-2:** Hospital que consulta, en atención normal y en emergencia (ETREAT con PDQm) ![Laboratorio que publica documentos](hix-actores-laboratorio.svg) **Figura 2.2-3:** Laboratorio que publica documentos Las dos tablas siguientes listan las transacciones que definen a cada actor. R significa que la transacción es requerida para declararse conforme con el actor, y O que es opcional. La columna Referencia indica el perfil IHE que define la transacción, o el Volumen 2 de esta guía para las propias de HIX. Los miembros, y los actores centrales ante los que presentan tokens, se agrupan además con IUA, y todos los actores salvo la aplicación del paciente con ATNA y CT. Esas agrupaciones, y las transacciones que traen consigo, se describen en la [sección 2.4](volume-1-groupings.html). Por eso las tablas listan las transacciones de IUA y ATNA solo para el actor que las responde, el Authorization Server y el Audit Record Repository. Quién inicia y quién responde cada transacción lo dice la [Tabla 3-1](volume-2.html#tabla-3-1). **Tabla 2.2-1:** Actores de miembro | Actor | Transacción | Opcionalidad | Referencia | | --- | --- | --- | --- | | Sistema que publica y custodia documentos | Patient Identity Feed FHIR [ITI-104] | R | PIXm | | | Provide Document Bundle [ITI-65] | R | MHD | | | Retrieve Document [ITI-68] | R (nota 1) | MHD | | | Mobile Patient Identifier Cross-reference Query [ITI-83] | O | PIXm | | Sistema que consume documentos | Find Document Lists [ITI-66] | R | MHD | | | Find Document References [ITI-67] | R | MHD | | | Retrieve Document [ITI-68] | R | MHD | | | Mobile Patient Identifier Cross-reference Query [ITI-83] | O | PIXm | | | Mobile Patient Demographics Query [ITI-78] | O (nota 2) | PDQm | | | Patient Demographics Match [ITI-119] | O (nota 3) | PDQm | | Aplicación del paciente | Patient Application Launch \[[HIX-2](volume-2-hix-2.html)\] | R | Vol. 2 | | | Find Document Lists [ITI-66] | R | MHD | | | Find Document References [ITI-67] | R | MHD | | | Retrieve Document [ITI-68] | R | MHD | **Tabla 2.2-2:** Actores centrales y fuente de identidad | Actor | Transacción | Opcionalidad | Referencia | | --- | --- | --- | --- | | Record Locator Service | Find Document Lists [ITI-66] | R | MHD | | | Find Document References [ITI-67] | R | MHD | | | Retrieve Document [ITI-68] | R | MHD | | | Find Matching Care Services [ITI-90] | R | mCSD | | | Mediated Token Exchange \[[HIX-1](volume-2-hix-1.html)\] | R | Vol. 2 | | Document Registry | Provide Document Bundle [ITI-65] | R | MHD | | | Find Document Lists [ITI-66] | R | MHD | | | Find Document References [ITI-67] | R | MHD | | | Retrieve Document [ITI-68] | O (nota 4) | MHD | | | Mobile Patient Identifier Cross-reference Query [ITI-83] | R | PIXm | | | Find Matching Care Services [ITI-90] | R | mCSD | | | Mobile Patient Identity Feed [ITI-93] | R | PMIR | | Authorization Server | Get Access Token [ITI-71] | R | IUA | | | Introspect Token [ITI-102] | R | IUA | | | Get Authorization Server Metadata [ITI-103] | R | IUA | | | Mediated Token Exchange \[[HIX-1](volume-2-hix-1.html)\] | R | Vol. 2 | | | Patient Application Launch \[[HIX-2](volume-2-hix-2.html)\] | R | Vol. 2 | | | Mobile Patient Identifier Cross-reference Query [ITI-83] | R | PIXm | | Directorio de la comunidad | Find Matching Care Services [ITI-90] | R | mCSD | | Master Patient Index | Mobile Patient Identity Feed [ITI-93] | R | PMIR | | | Subscribe to Patient Updates [ITI-94] | R | PMIR | | | Patient Identity Feed FHIR [ITI-104] | R | PIXm | | | Mobile Patient Identifier Cross-reference Query [ITI-83] | R | PIXm | | | Mobile Patient Demographics Query [ITI-78] | R | PDQm | | | Patient Demographics Match [ITI-119] | R | PDQm | | Audit Record Repository | Record Audit Event [ITI-20] | R | ATNA | | Fuente autoritativa de identidad (externa) | Mobile Patient Identity Feed [ITI-93] | R | PMIR | Notas: 1. No requerido si el custodio declara la Opción de Almacenamiento Central. 2. Requerido si el actor declara la Opción de Demografía. 3. Requerido si el actor declara la Opción de Coincidencia Demográfica. 4. Requerido si el actor declara la Opción de Almacenamiento Central. El propósito de uso no depende del actor sino del caso de uso. Es un código del conjunto [PurposeOfUse](https://terminology.hl7.org/ValueSet-v3-PurposeOfUse.html) de HL7, tomado del sistema [v3-ActReason](https://terminology.hl7.org/CodeSystem-v3-ActReason.html), que el Authorization Server incluye en el token de cada solicitante y que la decisión de divulgación evalúa. No decide qué transacciones puede pedir un solicitante. Eso lo fija el scope de su token. Un mismo hospital consulta con `TREAT` en la atención habitual y con `ETREAT` en una urgencia. HIX usa el conjunto completo de HL7 y no lo restringe. Qué propósitos acepta una comunidad, y con qué condiciones, es política de implementación. La [Tabla 2.2-3](volume-1-actors.html#tabla-2-2-3) solo orienta al lector con los más frecuentes y el caso en el que aparece cada uno[^pou]. **Tabla 2.2-3:** Propósitos de uso más frecuentes en HIX | Código | Nombre en HL7 | Caso en el que aparece | | --- | --- | --- | | [`TREAT`](https://terminology.hl7.org/CodeSystem-v3-ActReason.html#v3-ActReason-TREAT) | treatment | Atención habitual de un paciente. Con él consulta un hospital y publica un laboratorio | | [`ETREAT`](https://terminology.hl7.org/CodeSystem-v3-ActReason.html#v3-ActReason-ETREAT) | Emergency Treatment | Atención inmediata de una urgencia. Qué permite frente a `TREAT` lo fija la política de la comunidad. Por ejemplo, divulgar documentos que en atención habitual exigirían un consentimiento, aunque el paciente esté plenamente identificado | | [`BTG`](https://terminology.hl7.org/CodeSystem-v3-ActReason.html#v3-ActReason-BTG) | break the glass | Urgencia atendida por quien no está autorizado para ese acceso, con anulación de la política. Cómo se admite y se audita lo fija cada comunidad | | [`COC`](https://terminology.hl7.org/CodeSystem-v3-ActReason.html#v3-ActReason-COC) | coordination of care | Coordinación de la atención de una persona entre varias organizaciones | | [`PATRQT`](https://terminology.hl7.org/CodeSystem-v3-ActReason.html#v3-ActReason-PATRQT) | patient requested | Acceso de una persona a su propio expediente | | [`FAMRQT`](https://terminology.hl7.org/CodeSystem-v3-ActReason.html#v3-ActReason-FAMRQT) | family requested | Acceso de un familiar autorizado por el paciente, si la comunidad admite la representación | | [`PWATRNY`](https://terminology.hl7.org/CodeSystem-v3-ActReason.html#v3-ActReason-PWATRNY) | power of attorney | Acceso del representante legal del paciente, como el padre o la madre de un menor, si la comunidad admite la representación | | [`HOPERAT`](https://terminology.hl7.org/CodeSystem-v3-ActReason.html#v3-ActReason-HOPERAT) | healthcare operations | Actividades administrativas y contractuales de la organización | | [`HPAYMT`](https://terminology.hl7.org/CodeSystem-v3-ActReason.html#v3-ActReason-HPAYMT) | healthcare payment | Actividades financieras relacionadas con el pago de la atención | | [`HRESCH`](https://terminology.hl7.org/CodeSystem-v3-ActReason.html#v3-ActReason-HRESCH) | healthcare research | Investigación en salud | | [`PUBHLTH`](https://terminology.hl7.org/CodeSystem-v3-ActReason.html#v3-ActReason-PUBHLTH) | public health | Actividades de salud pública, como la notificación de enfermedades de declaración obligatoria | ### Descripción de actores y requisitos Las descripciones siguen el orden de las tablas. Las reglas de estos dos párrafos valen para todos los actores y no se repiten en cada uno. Todo actor que recibe un token **SHALL** comprobar que está destinado a él y **SHALL** rechazar la solicitud si no lo está, como recomienda RFC 9700 para todo [Resource Server](appendix-glossary.html#resource-server) ([RFC 9700, §4.10.2](https://www.rfc-editor.org/rfc/rfc9700.html#section-4.10.2))[^rfc9700-aud]. Que el Authorization Server de la comunidad haya emitido un token no lo hace válido ante cualquier actor. Cada token nombra en su audiencia, el claim `aud`, a los actores ante los que vale, y ante cualquier otro no sirve, aunque lo haya emitido el mismo Authorization Server. Y todo sistema de un miembro y todo actor central registra sus propios eventos de auditoría, como exige la agrupación con ATNA de la [sección 2.4](volume-1-groupings.html). Todo actor central que recibe directamente el token de un solicitante **SHOULD** comprobarlo mediante [ITI-102](https://profiles.ihe.net/ITI/IUA/index.html#3102-introspect-token-iti-102) en cada operación, y **MAY** validarlo por sí mismo con las claves del Authorization Server si el token es un JWT. Quien lo valida así no ve una revocación hasta que el token expira. El Record Locator Service no tiene esa opción, porque [su apartado](volume-1-actors.html#record-locator-service) le exige la introspección. Quien introspecciona **SHOULD NOT** reutilizar el resultado en operaciones posteriores, porque un resultado cacheado sigue aceptando un token ya revocado. Quien introspecciona y no obtiene respuesta del Authorization Server **SHALL** rechazar la solicitud con el status code 503, porque no tiene cómo comprobar el token. #### Sistema que publica y custodia documentos El custodio es el miembro que produce documentos. Los conserva, declara las identidades locales de sus pacientes y publica los punteros a sus documentos con el propósito de uso del caso, normalmente `TREAT`. Agrupa a un [Document Source](appendix-glossary.html#document-source) de MHD y a un [Patient Identity Source](appendix-glossary.html#patient-identity-source) de PIXm, y es el servicio que aloja el contenido de sus documentos, como explica la [sección 2.4](volume-1-groupings.html#miembros). Responde las recuperaciones que le llegan desde la infraestructura central, y solo desde ella. El custodio **SHALL** declarar mediante [ITI-104](https://profiles.ihe.net/ITI/PIXm/ITI-104.html) la identidad local de todo paciente sobre el que publique, en su propio dominio de identificadores y con un identificador de la persona que la fuente autoritativa reconoce, como la cédula. **SHALL** publicar mediante [ITI-65](https://profiles.ihe.net/ITI/MHD/5.0.0/ITI-65.html) punteros que lo nombren a él como custodio y lleven etiqueta de confidencialidad, con URL de contenido relativa cuando el contenido queda en él. El custodio **SHALL** conservar el contenido y responder [ITI-68](https://profiles.ihe.net/ITI/MHD/5.0.0/ITI-68.html), salvo que declare la Opción de Almacenamiento Central. **SHALL** validar localmente el token de cada solicitud con las claves que publica el Authorization Server, conforme a la [sección 2.6](volume-1-security.html). **SHALL** rechazar toda solicitud que no llegue con un token mediado obtenido por el Record Locator Service y **SHALL NOT** atender recuperaciones originadas directamente en otro miembro. #### Sistema que consume documentos El consumidor es el miembro que consulta el expediente de un paciente. Localiza y recupera documentos a través del Record Locator Service y agrupa a un [Document Consumer](appendix-glossary.html#document-consumer) de MHD. Desde su punto de vista la comunidad es un único servidor FHIR. Actúa con el propósito de uso `TREAT` en la atención habitual y con `ETREAT` cuando atiende una urgencia. El consumidor **SHALL** obtener un token del Authorization Server cuya audiencia incluya al Record Locator Service y **SHALL** presentarlo en toda solicitud. **SHALL** recuperar los documentos únicamente a través de las URL que el Record Locator Service le entrega. Puede resolver la identidad de un paciente con [ITI-83](https://profiles.ihe.net/ITI/PIXm/ITI-83.html) y, si declara la Opción de Demografía, buscarlo por sus datos demográficos con [ITI-78](https://profiles.ihe.net/ITI/PDQm/ITI-78.html). Si declara la Opción de Coincidencia Demográfica, puede pedir además con [ITI-119](https://profiles.ihe.net/ITI/PDQm/ITI-119.html) las identidades que más se parecen a unos datos incompletos. Ambas sirven, por ejemplo, en una urgencia en la que no tiene un identificador fiable, como en la [Figura 2.2-2](volume-1-actors.html#figuras-2-2). #### Aplicación del paciente La aplicación del paciente accede al expediente de la persona que la usa, con el contexto de paciente que el Authorization Server fija durante el lanzamiento y el propósito de uso que corresponde a quien actúa, según la [Tabla 2.2-3](volume-1-actors.html#tabla-2-2-3). Agrupa a un Document Consumer de MHD. A partir del lanzamiento, sus consultas y recuperaciones son las de cualquier otro consumidor, confinadas a ese único paciente. Este actor **SHALL** obtener su token mediante [HIX-2](volume-2-hix-2.html) y **SHALL NOT** solicitar ni asumir un contexto de paciente distinto del que el token declara. Su token solo autoriza ITI-66, ITI-67 e ITI-68, como fija HIX-2. #### Record Locator Service El Record Locator Service media la localización y recuperación de documentos en nombre de los miembros. Ante ellos es un Resource Server de IUA y un Document Responder de MHD. Ante el Document Registry y los custodios actúa como Document Consumer de MHD y, ante cada Resource Server al que llama, como Authorization Client de IUA. Es el único actor que atiende a los miembros al localizar y recuperar y el único que alcanza a un custodio. Responde de que ningún puntero ni documento llegue a un solicitante contra la decisión de divulgación, la evalúe él mismo o el Document Registry, según dónde la sitúe la comunidad. ##### Validación de la solicitud El Record Locator Service **SHALL** aceptar únicamente tokens emitidos por el Authorization Server de la comunidad. **SHALL** comprobarlos mediante [ITI-102](https://profiles.ihe.net/ITI/IUA/index.html#3102-introspect-token-iti-102) una vez por operación y **SHALL** tomar de esa respuesta, y no de la solicitud, la organización, el propósito de uso y el contexto de paciente del solicitante. ##### Decisión de divulgación El Record Locator Service **SHALL NOT** entregar a un solicitante ningún puntero, lista ni documento cuya divulgación la política no permita, y **SHALL** garantizar que la decisión se evalúe sobre los punteros antes de que se origine cualquier recuperación. Puede evaluarla él mismo o, cuando la comunidad la sitúa allí, dejar que la evalúe el Document Registry sobre las consultas que recibe de él. En ese caso **SHALL** alcanzar al Document Registry con el token mediado de [HIX-1](volume-2-hix-1.html), porque es el que le lleva el sujeto, la organización, el propósito de uso y el contexto de paciente del solicitante. La omisión **SHALL NOT** ser distinguible, para el solicitante, de la ausencia del documento, y **SHALL** quedar registrada en la auditoría. La misma decisión **SHALL** aplicarse a las listas que se devuelven por [ITI-66](https://profiles.ihe.net/ITI/MHD/5.0.0/ITI-66.html), porque una lista revela qué documentos existen. Al atender un [ITI-68](https://profiles.ihe.net/ITI/MHD/5.0.0/ITI-68.html), el Record Locator Service **SHALL** someter de nuevo el puntero pedido a la decisión de divulgación antes de alcanzar al custodio, releyéndolo en el Document Registry cuando la evaluación está allí. Un puntero cuya divulgación se niega **SHALL NOT** originar consulta al directorio, intercambio de token ni llamada al custodio. ##### Recuperación mediada El Record Locator Service **SHALL** entregar a los solicitantes URL de contenido que apunten a sí mismo. **SHALL** resolver el endpoint del custodio en el directorio de la comunidad en cada recuperación, salvo bajo la [Opción de Almacenamiento Central](volume-1-options.html#opcion-de-almacenamiento-central), y **SHALL NOT** revelar ese endpoint al solicitante. El Record Locator Service **SHALL** obtener mediante [HIX-1](volume-2-hix-1.html) un token mediado para cada custodio al que llama en nombre de un solicitante. Hacia cada actor central que la comunidad despliegue como un sistema distinto **SHOULD** obtenerlo también, salvo que la comunidad autorice un token propio conforme al apartado siguiente. **SHALL** pedir en cada intercambio únicamente el scope de la transacción que va a realizar y **SHALL NOT** reenviar a ninguno el token del solicitante. Cuando el Record Locator Service y un actor central forman un mismo sistema, como admite MHDS para toda la infraestructura central ([MHDS Vol. 1, §1:50.6.2.4](https://profiles.ihe.net/ITI/MHDS/volume-1.html#150624-central-infrastructure-as-a-single-system))[^mhds-single], la llamada entre ellos es interna y no requiere intercambio. El Record Locator Service **SHALL NOT** conservar copias de los documentos que transitan por él ni registrar su contenido. No tiene acceso propio a ningún custodio ni al contenido, no llama al Master Patient Index, y hacia los demás actores centrales solo tiene el acceso que fija el [apartado de llamadas a los actores centrales](volume-1-actors.html#record-locator-service). Cuando el custodio no responde, **SHALL** indicar que el custodio no está disponible, de forma que esa recuperación no se confunda con un documento inexistente. ##### Llamadas a los actores centrales Toda llamada del Record Locator Service a un actor central desplegado como un sistema distinto lleva un token que **SHALL** emitir el Authorization Server de la comunidad, **SHALL** estar destinado a ese actor y **SHALL** limitarse a las transacciones que la comunidad autoriza ante él. Esta guía recomienda el token mediado de [HIX-1](volume-2-hix-1.html), porque no deja al mediador ninguna credencial que valga sin una petición viva y lleva al destino el sujeto original. La comunidad **MAY** autorizar en su lugar un token propio, que el Record Locator Service obtiene con [ITI-71](volume-2-authorization.html#iti-71) y el grant Client Credentials y reutiliza mientras esté vigente, y que el Authorization Server **SHALL** limitar al destino y a las transacciones autorizadas. Ese token **SHALL NOT** incluir ITI-68, porque el contenido solo se alcanza con un token mediado, también cuando lo conserva el Document Registry bajo la [Opción de Almacenamiento Central](volume-1-options.html#opcion-de-almacenamiento-central). Tampoco sirve para ITI-66 ni ITI-67 cuando la comunidad sitúa la evaluación de la decisión de divulgación en el Document Registry, porque esa evaluación necesita el contexto del solicitante que solo lleva el token mediado. ITI-90 es la única transacción que el solicitante no puede tener en su scope, porque los miembros no consultan el directorio. Cuando el Record Locator Service la pide con HIX-1, el Authorization Server **SHALL** comprobar que la delegación registrada la permite ante el directorio, sin exigir que el scope del token del solicitante la contenga. En todos los casos, el Record Locator Service **SHALL** llamar a un actor central únicamente para atender una operación autorizada de un solicitante y **SHALL** registrar cada llamada bajo el identificador de correlación de esa operación. La comunidad puede adoptar otra forma de obtener el token si cumple las condiciones anteriores. La [sección 2.6.5](volume-1-security.html#riesgos-residuales) compara las dos formas descritas. > **Nota.** *Record Locator Service* es el nombre que esta guía da al actor. No es vocabulario IHE. Corresponde al localizador central del modelo Centralized Discovery and Retrieve de IHE, el que permite descubrir dónde están los documentos y recuperarlos del custodio que registró su existencia ([IHE HIE Whitepaper, §2.8](https://profiles.ihe.net/ITI/HIE-Whitepaper/index.html#28-document-sharing-models))[^hie-cdr]. En HIX media además la recuperación, y se implementa agrupando un Document Consumer y un Document Responder de MHD. #### Document Registry El [Document Registry](appendix-glossary.html#document-registry) es el registro de documentos de la comunidad. Toma su nombre y su función del Document Registry de MHDS, pero es un actor de HIX, definido por los actores que agrupa en la [sección 2.4](volume-1-groupings.html). Conserva los punteros a los documentos publicados y, bajo la Opción de Almacenamiento Central, el contenido que los custodios le entregan. El Document Registry **SHALL** conservar en el `subject` de los punteros, los SubmissionSet y las carpetas la identidad maestra del paciente. La comunidad **MAY** autorizar que traduzca a esa identidad, mediante ITI-83, el identificador de la persona que la fuente autoritativa reconoce o un identificador del propio dominio del miembro, al publicar, al localizar o en ambos casos. Las dos decisiones son independientes y permiten a los miembros usar, en las operaciones que la comunidad habilite, los identificadores que ya conocen sin consultar antes la identidad maestra. ##### Publicación y validación El Document Registry **SHALL** registrar cada puntero a nombre de la organización que declara el token y **SHALL** rechazar la publicación cuyo custodio no coincida con ella. **SHALL** validar mediante [ITI-90](https://profiles.ihe.net/ITI/mCSD/ITI-90.html) que esa organización es un miembro activo de la comunidad. Esa consulta, y las que hace con ITI-83, las autentica con un token propio que obtiene con [ITI-71](volume-2-authorization.html#iti-71) y el grant Client Credentials, con el destino como `resource` y solo esa transacción como scope. El Document Registry **SHALL** validar mediante [ITI-83](https://profiles.ihe.net/ITI/PIXm/ITI-83.html) el `subject` de cada puntero, del SubmissionSet y de cada carpeta, y **SHALL** rechazar la publicación si alguno no corresponde a una identidad maestra activa o si no corresponden todos a la misma persona[^pixm-deprecated][^mhds-subject]. Si la comunidad autoriza la traducción al publicar, **MAY** aceptar en `subject` una referencia lógica por el identificador que la fuente autoritativa reconoce, como admite MHD[^mhd-patient], o por un identificador del propio dominio del custodio, que es el apartamiento de MHD que declara la [Tabla 2.1-3](volume-1-concepts.html#tabla-2-1-3). Cuando la acepta, **SHALL** resolverla con ITI-83 y escribir la identidad maestra al indexar, y **SHALL** rechazar un `subject` con un identificador de cualquier otro dominio. Si no ofrece esa traducción, el custodio debe enviar la identidad maestra. Cada puntero **SHALL** llevar en `sourcepatient` una referencia lógica a la identidad local que el custodio declaró con ITI-104, con el identificador en el dominio del custodio y sin referencia a un recurso. Si el custodio nombró al paciente en `subject` por ese identificador y no envió `sourcepatient`, el Document Registry **SHALL** copiarlo allí antes de escribir la identidad maestra. **SHALL** rechazar la publicación si falta `sourcepatient` y el `subject` no lo aporta, si la organización que publica no declaró esa identidad local o si esta no resuelve a la misma identidad maestra que el `subject` del puntero. El Document Registry **SHALL** rechazar la publicación que carezca de etiqueta de confidencialidad y, cuando el contenido queda en el custodio, aquella cuya URL de contenido no sea relativa. La [sección 3.5](volume-2-publication.html#iti-65) describe la publicación y reúne en una tabla los rechazos que HIX añade. ##### Localización El Document Registry **MAY**, si la comunidad autoriza la traducción al localizar, resolver mediante ITI-83 el identificador de paciente recibido en [ITI-66](https://profiles.ihe.net/ITI/MHD/5.0.0/ITI-66.html) o [ITI-67](https://profiles.ihe.net/ITI/MHD/5.0.0/ITI-67.html) y buscar por la identidad maestra resultante. Si no ofrece esa traducción, el solicitante debe nombrar al paciente por su identidad maestra. El Record Locator Service transmite el identificador recibido y no lo resuelve. Cuando la comunidad sitúa en él la decisión de divulgación, **SHALL** evaluarla sobre cada consulta que recibe del Record Locator Service con el contexto del solicitante que lleva el token mediado, conforme al [apartado de decisión de divulgación](volume-1-actors.html#record-locator-service) del Record Locator Service. ##### Actualizaciones de identidad El Document Registry recibe por [ITI-93](https://profiles.ihe.net/ITI/PMIR/ITI-93.html) los cambios de las identidades maestras. **SHALL** aplicar a los punteros y a las listas que conserva las fusiones recibidas, de modo que ninguno quede asociado a una identidad que dejó de existir. #### Authorization Server El Authorization Server emite, comprueba e intercambia los tokens que circulan por la comunidad. Es el Authorization Server de IUA. Es el único actor que emite tokens y el único que conoce a la vez al solicitante, su organización y el scope que se le concede. No decide sobre consentimiento, relación terapéutica ni identidad de paciente. El Authorization Server **SHALL** restringir la audiencia de todo token que emite a destinatarios identificados explícitamente, como recomienda RFC 9700 ([RFC 9700, §2.3](https://www.rfc-editor.org/rfc/rfc9700.html#section-2.3))[^rfc9700-aud]. El token de un miembro nombra a los Resource Servers centrales que define la comunidad, y el token mediado a los destinos que el Authorization Server asocia a su `resource`, como fija la [sección 2.6](volume-1-security.html#modelo-de-confianza). El Authorization Server **SHALL** atender [HIX-1](volume-2-hix-1.html) únicamente para el Record Locator Service. El token mediado **SHALL** llevar como audiencia los Resource Servers que el Authorization Server asocia al `resource` de la petición de intercambio, que son solo el custodio cuando el `resource` nombra a uno, y **SHALL** llevar el mismo sujeto, las mismas extensiones de IUA y, si lo hay, el mismo contexto de paciente que el token presentado, y como actor al Record Locator Service, en el claim `act` con el que OAuth 2.0 Token Exchange expresa la delegación ([RFC 8693, §4.1](https://www.rfc-editor.org/rfc/rfc8693.html#section-4.1))[^rfc8693-act]. El scope del token mediado **SHALL** ser el pedido en el intercambio y **SHALL** estar contenido en la delegación registrada para el Record Locator Service ante el destino, es decir, las transacciones que la comunidad registra en el Authorization Server para ese destino. También **SHALL** estar contenido en el scope del token del solicitante, salvo para ITI-90, como fija el apartado de llamadas a los actores centrales de la [sección 2.2](volume-1-actors.html#record-locator-service). La vida del token mediado **SHALL NOT** superar los dos minutos ni la vida restante del token del solicitante. El Authorization Server **SHALL NOT** emitir por ningún otro camino un token cuya audiencia sea un custodio, ni un token propio del Record Locator Service cuyo scope incluya ITI-68. El Authorization Server **SHALL** fijar la organización del solicitante desde su propio registro, sin aceptarla de la solicitud, y **SHALL** emitir como propósito de uso solo uno que su registro admita para ese cliente. Cómo indica el solicitante que necesita un propósito de emergencia lo decide la comunidad, porque IUA no define ningún mecanismo para ello, como explica la [sección 2.6](volume-1-security.html#acceso-de-emergencia). Cuando una persona se autentica, **SHALL** resolver su identidad verificada a la identidad maestra mediante [ITI-83](https://profiles.ihe.net/ITI/PIXm/ITI-83.html), con un token propio que obtiene con el grant Client Credentials, y **SHALL** fijar ese resultado como contexto de paciente del token, conforme a [HIX-2](volume-2-hix-2.html). **SHALL NOT** emitir un token con contexto de paciente cuando esa identidad no resuelva a una identidad maestra. #### Directorio de la comunidad El directorio publica las organizaciones participantes, su pertenencia a la comunidad y los endpoints en los que responden. Es el [Directory](appendix-glossary.html#directory) de mCSD de la comunidad y la única fuente de la que la infraestructura central aprende a quién dirigir una recuperación. El directorio **SHALL** responder [ITI-90](https://profiles.ihe.net/ITI/mCSD/ITI-90.html) y **SHALL** ser el único origen de los endpoints que usa la infraestructura central. **SHALL** identificar a cada organización con el mismo identificador que el Authorization Server incluye en sus tokens. Es Resource Server de IUA y **SHALL** comprobar el token de cada consulta del Record Locator Service y del Document Registry como fija la [Tabla 2.4-1](volume-1-groupings.html#tabla-2-4-1). Los miembros no consultan el directorio. Su contenido se mantiene administrativamente, al incorporar un miembro. #### Master Patient Index El Master Patient Index agrupa al [Patient Identity Registry](appendix-glossary.html#patient-identity-registry) de PMIR, al [Patient Identifier Cross-reference Manager](appendix-glossary.html#patient-identifier-cross-reference-manager) de PIXm y al [Patient Demographics Supplier](appendix-glossary.html#patient-demographics-supplier) de PDQm. Conserva una identidad maestra por persona, creada por la fuente autoritativa de identidad, y los enlaces con las identidades locales que los miembros declaran. El Master Patient Index **SHALL** crear identidades maestras únicamente a partir de [ITI-93](https://profiles.ihe.net/ITI/PMIR/ITI-93.html) recibido de la fuente autoritativa de identidad. **SHALL** aceptar [ITI-104](https://profiles.ihe.net/ITI/PIXm/ITI-104.html) únicamente en el dominio de identificadores del miembro que lo origina y **SHALL** rechazar la declaración que no pueda vincularse a una identidad maestra existente. Dentro de su propio dominio el miembro gestiona sus identidades locales con libertad, incluida la resolución de sus propios duplicados que define ITI-104. > **Nota.** Rechazar la declaración de una persona sin identidad maestra es la regla por defecto de esta versión y es una decisión abierta. Queda por definir cómo se declaran las personas que todavía no tienen un identificador que la fuente autoritativa reconozca, como un recién nacido, un paciente sin identificar en una urgencia o una persona extranjera. Una declaración de un miembro **SHALL NOT** crear, fusionar ni eliminar una identidad maestra. El Master Patient Index **SHALL NOT** modificar la demografía de la identidad maestra a partir de lo que un miembro declara. **SHALL** responder [ITI-83](https://profiles.ihe.net/ITI/PIXm/ITI-83.html) únicamente con la identidad maestra, nunca con las identidades locales que otros miembros declararon. PIXm admite esa restricción, porque deja que la respuesta sea un subconjunto determinado por política ([PIXm, §2:3.83.4.1.3](https://profiles.ihe.net/ITI/PIXm/ITI-83.html#2383413-expected-actions))[^pixm-subset]. El Master Patient Index **SHALL** responder [ITI-78](https://profiles.ihe.net/ITI/PDQm/ITI-78.html) e [ITI-119](https://profiles.ihe.net/ITI/PDQm/ITI-119.html) únicamente con identidades maestras, nunca con las identidades locales de los miembros, y **SHALL** limitar la respuesta a los pacientes que la política de la comunidad permita revelar por esa vía. **SHALL** rechazar una consulta ITI-78 que no lleve ningún criterio que nombre o describa a la persona. En ITI-119 **SHALL** indicar el grado de coincidencia de cada resultado, como exige PDQm ([PDQm, §2:3.119.4.2.2.4](https://profiles.ihe.net/ITI/PDQm/ITI-119.html#231194224-quality-of-match))[^pdqm-match]. Además, **SHALL** ordenarlos de más a menos probable, como describen los casos de ITI-119. #### Audit Record Repository El Audit Record Repository es el actor de ATNA que recibe mediante [ITI-20](https://profiles.ihe.net/ITI/TF/Volume2/ITI-20.html) los eventos que registran los actores centrales. Existe para que una divulgación pueda reconstruirse completa desde el lado de la comunidad, con la solicitud del miembro y la recuperación ante el custodio bajo un mismo identificador de correlación. Cada miembro detecta y registra los eventos de su propio lado, como ATNA exige a todo Secure Node o Secure Application ([ITI TF-1, §9.1.1.1](https://profiles.ihe.net/ITI/TF/Volume1/ch-9.html#9.1.1.1))[^atna-sn], con la agrupación que fija la [sección 2.4](volume-1-groupings.html#lo-que-casi-todos-agrupan). #### Fuente autoritativa de identidad La fuente autoritativa de identidad es el sistema, externo a la comunidad, contra el que se verifica la identidad de una persona y del que la comunidad obtiene sus identidades maestras. Es el Patient Identity Source de PMIR. HIX no designa cuál es. La propuesta para Costa Rica es que sea el EDUS, porque ya tiene resuelta la identificación de las personas. La fuente autoritativa **SHALL** alimentar el Master Patient Index mediante [ITI-93](https://profiles.ihe.net/ITI/PMIR/ITI-93.html), con un token emitido por el Authorization Server de la comunidad. Es la única que crea, actualiza, fusiona o desactiva identidades maestras. ### Transacciones propias de HIX **Mediated Token Exchange [HIX-1].** El Record Locator Service presenta al Authorization Server el token del solicitante y recibe a cambio un [token mediado](appendix-glossary.html#token-mediado) para el destino que nombra el `resource` y un solo tipo de transacción, como especifica la [sección 3.2](volume-2-hix-1.html). **Patient Application Launch [HIX-2].** Una aplicación elegida por una persona obtiene del Authorization Server un token destinado al Record Locator Service cuyo contexto de paciente es la identidad maestra de esa persona, como especifica la [sección 3.3](volume-2-hix-2.html). > **Nota.** La incorporación de un miembro, por la que una organización queda descrita en el directorio y reconocida por el Authorization Server, es un procedimiento administrativo y no una transacción. ### Referencias Las citas reproducen el texto publicado por su fuente. Los recortes se marcan con "[...]" y la negrita es de esta guía. [^rfc9700-aud]: [RFC 9700, §2.3 Access Token Privilege Restriction](https://www.rfc-editor.org/rfc/rfc9700.html#section-2.3): "In particular, **access tokens SHOULD be audience-restricted to a specific resource server** or, if that is not feasible, to a small set of resource servers." [§4.10.2 Audience-Restricted Access Tokens](https://www.rfc-editor.org/rfc/rfc9700.html#section-4.10.2): "The authorization server associates the access token with the particular resource server, and **the resource server is then supposed to verify the intended audience**. If the access token fails the intended audience validation, **the resource server refuses to serve the respective request**." [^pou]: [v3-ActReason, TREAT](https://terminology.hl7.org/CodeSystem-v3-ActReason.html#v3-ActReason-TREAT): "treatment. **To perform one or more operations on information for provision of health care.**" [ETREAT](https://terminology.hl7.org/CodeSystem-v3-ActReason.html#v3-ActReason-ETREAT): "Emergency Treatment. To perform one or more operations on information for provision of **immediately needed health care for an emergent condition**." [PATRQT](https://terminology.hl7.org/CodeSystem-v3-ActReason.html#v3-ActReason-PATRQT): "patient requested. To perform one or more operations on information **in response to a patient's request**." [FAMRQT](https://terminology.hl7.org/CodeSystem-v3-ActReason.html#v3-ActReason-FAMRQT): "family requested. To perform one or more operations on information in response to a request by **a family member authorized by the patient**." [PWATRNY](https://terminology.hl7.org/CodeSystem-v3-ActReason.html#v3-ActReason-PWATRNY): "power of attorney. To perform one or more operations on information in response to a request by **a person appointed as the patient's legal representative**." [^rfc8693-act]: [RFC 8693, §1.1 Delegation vs. Impersonation Semantics](https://www.rfc-editor.org/rfc/rfc8693.html#section-1.1): "With delegation semantics, principal A still has its own identity separate from B, and it is explicitly understood that while B may have delegated some of its rights to A, **any actions taken are being taken by A representing B**." [§2.1 Request](https://www.rfc-editor.org/rfc/rfc8693.html#section-2.1): "resource. OPTIONAL. **A URI that indicates the target service or resource where the client intends to use the requested security token.**" [§4.1 "act" (Actor) Claim](https://www.rfc-editor.org/rfc/rfc8693.html#section-4.1): "The act (actor) claim provides a means within a JWT to express that **delegation has occurred and identify the acting party to whom authority has been delegated**." [^mhds-subject]: [MHDS Vol. 1, §1:50.1.1.1.1 When the grouped MHD Document Recipient – is triggered](https://profiles.ihe.net/ITI/MHDS/volume-1.html#1501111-when-the-grouped-mhd-document-recipient--is-triggered): "The Document Registry SHALL validate that **the subject of the DocumentReference, and List Resources is the same Patient**, and that **Patient is a recognized and active Patient within the Community**. The Patient identity must be recognized and active by the PMIR Patient Identity Registry in the document sharing community. **This may be accomplished by a query of the PMIR Patient Identity Registry**, by way of a cached internal patient database, or other means." [^mhd-patient]: [MHD, §2:3.65.4.1.2.2 Patient Identity](https://profiles.ihe.net/ITI/MHD/5.0.0/ITI-65.html#23654122-patient-identity): "**A commonly accessible logical reference using Patient Identifier, instead of a literal reference, may be acceptable where there is a common Identifier, such as a national individual identifier.**" [^pixm-subset]: [PIXm, §2:3.83.4.1.3 Expected Actions](https://profiles.ihe.net/ITI/PIXm/ITI-83.html#2383413-expected-actions): "**The Patient Identifiers returned may be a subset based on policies that might restrict access to some Patient Identifiers.** For guidance on handling Access Denied, see ITI TF-2: Appendix Z.7." [^pdqm-match]: [PDQm, §2:3.119.4.2.2.4 Quality of Match](https://profiles.ihe.net/ITI/PDQm/ITI-119.html#231194224-quality-of-match): "**The Patient Demographics Supplier SHALL convey the quality of each match** based on strength of the particular result to the supplied Patient Resource. [...] it SHALL represent the confidence of a particular match within the bundle as a score attribute." Y en los casos de [§2:3.119.4.1.3 Expected Actions](https://profiles.ihe.net/ITI/PDQm/ITI-119.html#23119413-expected-actions): "**The results are ordered from most likely to least likely.**" [^pixm-deprecated]: [PIXm, §2:3.83.4.2.2.5 Post Merge/Delete](https://profiles.ihe.net/ITI/PIXm/ITI-83.html#23834225-post-mergedelete): "Based upon policy, **when the Patient is deprecated or deleted, the response message shall return: 200 OK, and return a Bundle with no patient resource, or 404 Not Found**" [^atna-sn]: [ITI TF-1, §9.1.1.1 Secure Node](https://profiles.ihe.net/ITI/TF/Volume1/ch-9.html#9.1.1.1): "The Secure Node shall: [...] **Detect and report a Record Audit Event** as specified in ITI TF-2: 3.20 for: **all of the activity-related events for the Secure Node**; all transaction-related events for the Secure Node.". La Secure Application tiene el mismo requisito en §9.1.1.2. [^mhds-single]: [MHDS Vol. 1, §1:50.6.2.4 Central Infrastructure as a single system](https://profiles.ihe.net/ITI/MHDS/volume-1.html#150624-central-infrastructure-as-a-single-system): "This is **a system that contains all of the Central Infrastructure** defined in MHDS as supporting services. These actors do not need to be combined into one system." [^hie-cdr]: [IHE HIE Whitepaper, §2.8 Document Sharing Models](https://profiles.ihe.net/ITI/HIE-Whitepaper/index.html#28-document-sharing-models): "**Centralized Discovery and Retrieve** – in this model, a centralized locator is used to discover the location of documents which enables a retrieval of the document from a custodian who has registered existence of the document with the centralized locator". ## Capacidades opcionales de los actores Las opciones definen capacidades que un actor puede añadir a las que se le exigen. La [Tabla 2.3-1](volume-1-options.html#tabla-2-3-1) lista las que cada actor puede declarar. Un actor que declara una opción **SHALL** cumplir todos sus requisitos. **Tabla 2.3-1:** Actores y opciones de HIX | Actor | Opción | | --- | --- | | Record Locator Service | Opción de Consentimiento | | | Opción de Canal de Interconexión | | Document Registry | Opción de Almacenamiento Central | | | Opción de Consentimiento | | | Opción de Canal de Interconexión | | Master Patient Index | Opción de Canal de Interconexión | | Authorization Server | Opción de Canal de Interconexión | | Sistema que publica y custodia documentos | Opción de Almacenamiento Central | | | Opción de Canal de Interconexión | | Sistema que consume documentos | Opción de Demografía | | | Opción de Coincidencia Demográfica | | | Opción de Canal de Interconexión | | Aplicación del paciente | Opción de Canal de Interconexión, solo con backend propio | ### Opción de Almacenamiento Central Un [custodio](appendix-glossary.html#custodio) que no puede conservar sus documentos delega el almacenamiento del contenido en la infraestructura central. El documento sigue siendo suyo. Figura como custodio en los metadatos y conserva la responsabilidad sobre su contenido, pero deja de participar en la recuperación. El custodio **SHALL** declarar esta opción solo si el Document Registry de la comunidad también la declara. El custodio que la declara **SHALL** enviar el contenido dentro del [ITI-65](https://profiles.ihe.net/ITI/MHD/5.0.0/ITI-65.html) en lugar de una referencia, y **SHOULD NOT** exponer un endpoint de recuperación, porque las recuperaciones ya no pasan por él. El Document Registry que declara esta opción **SHALL** conservar el contenido durante el ciclo de vida que la comunidad establezca y **SHALL** responder [ITI-68](https://profiles.ihe.net/ITI/MHD/5.0.0/ITI-68.html) con el contenido que conserva. El Record Locator Service atiende entonces la recuperación desde el Document Registry, como fija la [sección 2.2](volume-1-actors.html#record-locator-service). Esta opción corresponde a la primera de las dos ubicaciones del contenido que describe MHDS ([MHDS Vol. 1, §1:50.1.1.2](https://profiles.ihe.net/ITI/MHDS/volume-1.html#150112-storage-of-binary))[^mhds-storage]. Ambas coexisten en una misma comunidad, como explica la [sección 2.1](volume-1-concepts.html#custodia-distribuida-y-almacenamiento-central). El solicitante no distingue cuál se aplica a cada documento y no necesita hacerlo. Qué custodios pueden ejercerla, y quién lo decide, es política de la comunidad. ### Opción de Canal de Interconexión Las transacciones de la comunidad pueden recorrer un canal de interconexión distinto de HTTPS directo, cuando la comunidad opera sobre una red de intercambio ya establecida, como X-Road. Todo actor que la comunidad expone a otros participantes queda entonces bajo ese canal, sea un actor central o un custodio que responde recuperaciones, y lo mismo los miembros que llaman a esos actores. La excepción es la aplicación del paciente que es un cliente público, porque funciona en el navegador de la persona y solo puede usar HTTPS. Una aplicación con backend propio, que es un cliente confidencial, **MAY** declarar la opción para sus llamadas al Record Locator Service, aunque la autorización de [HIX-2](volume-2-hix-2.html) siga pasando por el navegador. El actor que declara esta opción **SHALL** atender y originar a través del canal las mismas transacciones, con el mismo contenido y los mismos requisitos de autorización. El directorio **SHALL** declarar, para el custodio que la declara, el endpoint que describe ese canal. El token sigue viajando en la solicitud y quien la recibe sigue validándolo. La identidad que el canal aporta **SHALL NOT** sustituir la validación del token. El canal no cambia nada de la arquitectura. Resuelve cómo se conectan, se identifican y cifran su tramo las organizaciones, y las transacciones, los punteros, los tokens, la decisión de divulgación y la auditoría siguen siendo los mismos, como explica la [sección 2.1](volume-1-concepts.html). La representación del canal en el directorio se especificará más adelante en esta guía. Una red como X-Road autentica y cifra el tramo entre los servidores de seguridad de las dos organizaciones ([X-Road, Arquitectura §3.3](https://docs.x-road.global/Architecture/arc-g_x-road_arhitecture.html#33-message-transport-protocol))[^xroad-transport]. El tramo entre el sistema del custodio y su propio servidor de seguridad queda dentro de su organización, y protegerlo es responsabilidad del custodio. Esta guía no lo especifica. ### Opción de Consentimiento Habilita la evaluación de una decisión de divulgación por paciente antes de responder una localización o una recuperación. La decisión base, con la política única de la comunidad, es un requisito de la [sección 2.2](volume-1-actors.html#record-locator-service). Esta opción la extiende al consentimiento de cada paciente. El actor que declara esta opción, sea el Record Locator Service o el Document Registry, **SHALL** consultar la decisión aplicable al paciente, al solicitante, a su organización, al propósito de uso que lleva su token y a la etiqueta de confidencialidad de cada puntero. **SHALL** omitir de la respuesta los documentos cuya divulgación no esté permitida, con las garantías que la [sección 2.2](volume-1-actors.html#record-locator-service) exige a toda omisión, es decir, que no se distinga de la ausencia del documento y que quede registrada en la auditoría. El modelo de consentimiento, su ciclo de vida, su representación y sus políticas se especificarán en una versión posterior de esta guía a partir de [PCF](https://profiles.ihe.net/ITI/PCF/index.html). Esta opción declara el punto en el que esa decisión se aplica y la información que necesita. Hasta entonces, la comunidad opera bajo la política de divulgación única que haya acordado, aplicada en el mismo punto. En qué punto se aplica, en el Record Locator Service o en el Document Registry, lo decide la comunidad, como explica la [sección 2.1](volume-1-concepts.html#divulgacion). MHDS resuelve este mismo problema de otro modo, con un Authorization Server agrupado con su Document Registry que gestiona el consentimiento. HIX no sigue ese camino, por las razones que da la [misma sección](volume-1-concepts.html#relacion-con-mhds). ### Opción de Demografía Permite a un [consumidor](appendix-glossary.html#consumidor) localizar a un paciente por sus datos demográficos cuando no dispone de un identificador conocido por la comunidad. Corresponde a la [Patient Search Option](https://profiles.ihe.net/ITI/PDQm/volume-1.html#13821-patient-search-option) de PDQm. El consumidor que declara esta opción **SHALL** presentar al menos un criterio que nombre o describa a la persona en cada consulta [ITI-78](https://profiles.ihe.net/ITI/PDQm/ITI-78.html). Qué parámetros cuentan como criterio lo fija la [sección 3.4](volume-2-identity.html#iti-78). Es una búsqueda determinista. Cada criterio filtra, y ningún resultado lleva grado de coincidencia. Las reglas que el Master Patient Index aplica a su respuesta, como devolver solo identidades maestras y limitarlas según la política de la comunidad, las fija la [sección 2.2](volume-1-actors.html#master-patient-index). ### Opción de Coincidencia Demográfica Permite a un [consumidor](appendix-glossary.html#consumidor) encontrar a un paciente a partir de datos demográficos incompletos o inexactos, con la coincidencia probabilística del Master Patient Index. Corresponde a la [Match Operation Option](https://profiles.ihe.net/ITI/PDQm/volume-1.html#13822-match-operation-option) de PDQm. El consumidor que declara esta opción **SHALL** presentar en cada [ITI-119](https://profiles.ihe.net/ITI/PDQm/ITI-119.html) los datos del paciente que busca. Un resultado de esta búsqueda es un candidato, no una identidad confirmada. Las reglas que el Master Patient Index aplica a su respuesta, como devolver solo identidades maestras e indicar el grado de coincidencia de cada una, las fija la [sección 2.2](volume-1-actors.html#master-patient-index). ### Referencias Las citas reproducen el texto publicado por su fuente. Los recortes se marcan con "[...]" y la negrita es de esta guía. [^mhds-storage]: [MHDS Vol. 1, §1:50.1.1.2 Storage of Binary](https://profiles.ihe.net/ITI/MHDS/volume-1.html#150112-storage-of-binary): "(1) The Document Source includes the Binary Resource in the [ITI-65] transaction, and the Document Registry is required to store it. (2) **The Community allows the Binary to be stored elsewhere in the Community.** [...] This might be other centralized infrastructure, distributed infrastructure, or **within the system implementing the Document Source**." [^xroad-transport]: [X-Road, Arquitectura §3.3 Message Transport Protocol](https://docs.x-road.global/Architecture/arc-g_x-road_arhitecture.html#33-message-transport-protocol): "The X-Road Message Transport Protocol is used by security server to exchange service requests and service responses. [...] The protocol is based on HTTPS and **uses mutual certificate-based TLS authentication**." ## Agrupaciones de actores requeridas Un actor de HIX no se implementa desde cero. Se implementa agrupando actores de los perfiles IHE que HIX compone, y cada uno de ellos trae consigo sus transacciones, sus opciones y sus requisitos. La [sección 2.2](volume-1-actors.html) dice qué transacciones ejecuta cada actor. Esta sección dice de qué está hecho, es decir, qué actores IHE agrupa y bajo qué opciones. Para quien implementa, es la lista de perfiles que debe leer y de agrupaciones que debe declarar al afirmar su conformidad. Para quien solo quiere entender la arquitectura, basta con la [sección 2.2](volume-1-actors.html) y esta queda como referencia. Cada actor de HIX **SHALL** implementar los actores agrupados que le asigna la [Tabla 2.4-2](volume-1-groupings.html#tabla-2-4-2). Las agrupaciones se describen primero en prosa, actor por actor, y la tabla las resume al final. ### Lo que casi todos agrupan Tres perfiles acompañan a casi todos los actores de HIX. Se describen aquí una sola vez y no se repiten en cada actor. **IUA pone el token en cada transacción.** Todo miembro es un [Authorization Client](appendix-glossary.html#authorization-client) de IUA. Obtiene el token del Authorization Server con [ITI-71](volume-2-authorization.html#iti-71) y el grant Client Credentials, salvo la aplicación del paciente, que lo obtiene con [HIX-2](volume-2-hix-2.html), y lo presenta en cada solicitud con [ITI-72](https://profiles.ihe.net/ITI/IUA/index.html#372-incorporate-access-token-iti-72). Todo actor ante el que un miembro presenta un token, directamente o a través del Record Locator Service, es un [Resource Server](appendix-glossary.html#resource-server) de IUA, que recibe el token con ITI-72 y lo comprueba. Ambos pueden descubrir los endpoints del Authorization Server mediante [ITI-103](https://profiles.ihe.net/ITI/IUA/index.html#3103-get-authorization-server-metadata-iti-103)[^iua-actors]. IUA exige a todo Resource Server declarar con qué opción comprueba el token ([IUA, Tabla 34.2-1](https://profiles.ihe.net/ITI/IUA/index.html#342-iua-actor-options))[^iua-options]. Cada actor declara al menos una de la [JWT Token Option](https://profiles.ihe.net/ITI/IUA/index.html#3422-jwt-token-option) o la [Token Introspection Option](https://profiles.ihe.net/ITI/IUA/index.html#3424-token-introspection-option), y puede declarar además la [Authorization Server Metadata Option](https://profiles.ihe.net/ITI/IUA/index.html#3421-authorization-server-metadata-option) para descubrir los endpoints del Authorization Server. La [Tabla 2.4-1](volume-1-groupings.html#tabla-2-4-1) dice cuáles declara cada actor de HIX. **Tabla 2.4-1:** Cómo comprueba el token cada actor | Actor | Opciones de IUA | Cómo comprueba el token | | --- | --- | --- | | Record Locator Service | Token Introspection | Pregunta al Authorization Server con [ITI-102](https://profiles.ihe.net/ITI/IUA/index.html#3102-introspect-token-iti-102) | | Master Patient Index | Token Introspection, JWT Token, Authorization Server Metadata | El token del miembro que le declara o consulta identidades, y el token propio del Document Registry o del Authorization Server, preferiblemente con ITI-102 | | Document Registry | Token Introspection, JWT Token, Authorization Server Metadata | El token del miembro que publica y el token propio del Record Locator Service, preferiblemente con ITI-102. El token mediado, por sí mismo | | Directorio de la comunidad | Token Introspection, JWT Token, Authorization Server Metadata | El token propio del Record Locator Service o del Document Registry, preferiblemente con ITI-102. El token mediado, por sí mismo | | Custodio | JWT Token, Authorization Server Metadata. Token Introspection, si la comunidad la admite | Por sí mismo, con las claves que el Authorization Server publica, como fija la [sección 2.6](volume-1-security.html#validacion-en-el-custodio) | | Authorization Server | JWT Token, Authorization Server Metadata, Token Introspection | Emite los tokens, publica sus endpoints y sus claves con ITI-103 y responde ITI-102 | Un mismo sistema puede ser las dos cosas. El Record Locator Service es Resource Server ante los miembros y Authorization Client ante los custodios y los actores centrales, y un custodio presenta tokens al publicar y los valida al servir documentos. Cómo se autentican entre sí los demás actores centrales queda a criterio de la implementación, porque pueden compartir un mismo sistema, como dice el apartado [sobre los despliegues](volume-1-groupings.html#sobre-los-despliegues). **ATNA protege el canal y deja rastro.** Todo sistema que participa en HIX, salvo la aplicación del paciente, es un [Secure Node o Secure Application](appendix-glossary.html#secure-node) de ATNA. Autentica al nodo con el que habla y cifra el canal con [ITI-19](https://profiles.ihe.net/ITI/TF/Volume2/ITI-19.html), bajo la opción [STX: TLS 1.2 Floor using BCP195](https://profiles.ihe.net/ITI/TF/Volume1/ch-9.html#9.2.6.4), y registra sus eventos de auditoría con [ITI-20](https://profiles.ihe.net/ITI/TF/Volume2/ITI-20.html), como recursos AuditEvent bajo la opción ATX: FHIR Feed[^atna-fhir-feed] y con el contenido que cada perfil define a partir de los patrones de BALP. Esa opción pide a quien registra al menos una de las dos interacciones de ITI-20, y al Audit Record Repository las dos. Quien escribe esos registros es, en términos de BALP, un Audit Creator, que BALP agrupa precisamente con ese Secure Node o Secure Application ([BALP, §1:52.1.1.1](https://profiles.ihe.net/ITI/BALP/volume-1.html#152111-audit-creator))[^balp-creator]. Los actores centrales envían sus eventos al Audit Record Repository de la comunidad. Cada miembro conserva los suyos en su propio registro de auditoría. **CT mantiene los relojes de acuerdo.** Todo sistema que participa en HIX, salvo la aplicación del paciente, es un [Time Client](appendix-glossary.html#time-client) de CT y sincroniza su reloj con [ITI-1](https://profiles.ihe.net/ITI/TF/Volume2/ITI-1.html) contra el Time Server que la comunidad designa, propio o una fuente de tiempo externa. Sin relojes de acuerdo, los eventos de una misma divulgación no podrían ordenarse entre sistemas y la vigencia de dos minutos del token mediado no significaría lo mismo en cada extremo. Esta guía deja por ahora a la aplicación del paciente fuera de ATNA y de CT. Su actividad queda registrada por los dos actores centrales ante los que actúa, el Authorization Server al lanzarse y el Record Locator Service en cada consulta. ### Miembros **Custodio.** Es un [Document Source](appendix-glossary.html#document-source) de MHD con la Comprehensive Metadata Option, porque el Document Registry exige metadatos completos al publicar, como hace el de MHDS[^mhds-source-comprehensive]. Declara también la [UnContained Reference Option](https://profiles.ihe.net/ITI/MHD/5.0.0/1332_actor_options.html#13323-uncontained-reference-option), porque el puntero no lleva copias contenidas. `subject` y `custodian` referencian lo que la comunidad conserva, y `sourcepatient`, que MHD deja opcional y sin forma fija bajo esa opción, es una referencia lógica por identificador[^mhd-uncontained]. No es un Document Responder de MHD, porque las localizaciones con ITI-66 e ITI-67 las responde el Document Registry, que guarda los punteros. Es el servicio que aloja el contenido fuera del Document Registry, como lo prevé MHDS ([MHDS Vol. 1, §1:50.1.1.2](https://profiles.ihe.net/ITI/MHDS/volume-1.html#150112-storage-of-binary))[^mhds-binary], y lo sirve con ITI-68 solo al Record Locator Service. Por eso es también un Resource Server de IUA, que valida localmente el token mediado. Es un [Patient Identity Source](appendix-glossary.html#patient-identity-source) de PIXm, que declara sus identidades locales con ITI-104. Y es un Authorization Client de IUA, que obtiene el token con el que publica y declara. Puede agrupar además un Patient Identifier Cross-reference Consumer de PIXm para comprobar por su cuenta el contexto de paciente, como admite la [sección 2.6](volume-1-security.html#lo-que-un-token-prueba-y-lo-que-no). Bajo la Opción de Almacenamiento Central deja de alojar el contenido y de ser Resource Server, porque entrega el contenido al publicar y ya no responde recuperaciones. **Consumidor.** Es un [Document Consumer](appendix-glossary.html#document-consumer) de MHD, que localiza con ITI-66 e ITI-67 y recupera con ITI-68 a través del Record Locator Service, y un Authorization Client de IUA. Puede agrupar además un [Patient Identifier Cross-reference Consumer](appendix-glossary.html#patient-identifier-cross-reference-consumer) de PIXm, para resolver con ITI-83 un identificador que ya conoce, y, bajo la Opción de Demografía, un [Patient Demographics Consumer](appendix-glossary.html#patient-demographics-consumer) de PDQm con la [Patient Search Option](https://profiles.ihe.net/ITI/PDQm/volume-1.html#13821-patient-search-option), para buscar con ITI-78 a un paciente del que solo conoce sus datos. Bajo la Opción de Coincidencia Demográfica ese mismo actor declara la [Match Operation Option](https://profiles.ihe.net/ITI/PDQm/volume-1.html#13822-match-operation-option), para buscarlo con ITI-119. No es Resource Server, porque no responde transacciones de nadie. **Aplicación del paciente.** Es un Document Consumer de MHD y un Authorization Client de IUA, y nada más. Obtiene su token con [HIX-2](volume-2-hix-2.html) y desde ahí localiza y recupera como cualquier consumidor, confinada al paciente que la usa. ### Actores centrales **Record Locator Service.** Hacia los miembros es un [Document Responder](appendix-glossary.html#document-responder) de MHD, que recibe sus localizaciones y recuperaciones, y un Resource Server de IUA con la Token Introspection Option, porque comprueba cada token con ITI-102. Hacia el Document Registry y los custodios es un [Document Consumer](appendix-glossary.html#document-consumer) de MHD, que ejecuta esas mismas transacciones a nombre del solicitante, y un Authorization Client de IUA, que obtiene el token mediado con [HIX-1](volume-2-hix-1.html) para cada custodio y, salvo que la comunidad autorice un token propio conforme a la [sección 2.2](volume-1-actors.html#record-locator-service), para cada actor central desplegado como un sistema distinto. Agrupa además un [Query Client](appendix-glossary.html#query-client) de mCSD, con el que obtiene el endpoint de cada custodio con ITI-90. **Document Registry.** HIX toma el nombre y la función de este actor del Document Registry de MHDS y adapta sus agrupaciones a la arquitectura de la comunidad[^mhds-groupings]. Agrupa los siguientes actores: - Un [Document Recipient](appendix-glossary.html#document-recipient) de MHD con la [Comprehensive Metadata Option](https://profiles.ihe.net/ITI/MHD/5.0.0/1332_actor_options.html#13321-comprehensive-metadata-option) y la [UnContained Reference Option](https://profiles.ihe.net/ITI/MHD/5.0.0/1332_actor_options.html#13323-uncontained-reference-option), que recibe las publicaciones sin exigir copias contenidas, de modo que `sourcepatient` nombra a la identidad local por su identificador en el dominio del custodio. Esta referencia conserva la identidad con la que la fuente conoce al paciente y no debe confundirse con `subject`, que HIX vincula con la identidad maestra (golden record) de la comunidad. - Un [Document Responder](appendix-glossary.html#document-responder) de MHD, que responde las localizaciones y, bajo la Opción de Almacenamiento Central, también las recuperaciones. - Un [Patient Identity Consumer](appendix-glossary.html#patient-identity-consumer) de PMIR, que recibe por ITI-93 las altas, los cambios y las fusiones de las identidades maestras. Aplica las fusiones a los punteros y a las listas que conserva, que es lo que MHDS pide a su Document Registry, y conserva las altas y los cambios solo para comprobar que un paciente es reconocido y está activo[^mhds-pic]. Las recibe porque está suscrito con [ITI-94](https://profiles.ihe.net/ITI/PMIR/ITI-94.html). Esa suscripción la crea un Patient Identity Subscriber de PMIR, que puede ser el propio Document Registry o la operación de la comunidad. - Un [Query Client](appendix-glossary.html#query-client) de mCSD (que MHDS todavía denomina Care Services Selective Consumer), con el que comprueba que quien publica es un miembro activo de la comunidad. - Un [Patient Identifier Cross-reference Consumer](appendix-glossary.html#patient-identifier-cross-reference-consumer) de PIXm, que HIX añade, con el que comprueba al indexar que la persona existe y está activa en la comunidad, la misma comprobación que MHDS pide a su Document Registry al validar una publicación[^mhds-subject], y con el que resuelve a la identidad maestra los identificadores con los que el custodio nombra al paciente en `subject` y en `sourcepatient`, y con los que una consulta ITI-66 o ITI-67 nombra al paciente. - Un Authorization Client de IUA, que obtiene con [ITI-71](volume-2-authorization.html#iti-71) y el grant Client Credentials el token con el que consulta el Master Patient Index y el directorio. - Un Resource Server de IUA, que comprueba cada token que recibe con las opciones de la [Tabla 2.4-1](volume-1-groupings.html#tabla-2-4-1). De las opciones que MHDS define para su Document Registry, HIX adopta las agrupaciones de la Authorization Option, salvo la del Authorization Server, y las de la UnContained References Option. El Authorization Server queda fuera de la agrupación porque la comunidad dispone de uno solo para todos sus Resource Servers, como explica la [sección 2.1](volume-1-concepts.html#autorizacion-y-delegacion). La decisión de divulgación la garantiza el Record Locator Service, y la evalúa él mismo o el Document Registry cuando la comunidad la sitúa allí, como fija la [sección 2.2](volume-1-actors.html#record-locator-service). > **Nota.** HIX todavía no define cómo manejar la SVCM Validation Option. Validar la terminología de los metadatos queda a criterio de cada implementación. **Authorization Server.** Es el [Authorization Server de IUA](https://profiles.ihe.net/ITI/IUA/index.html#34112-authorization-server), con las tres opciones de la [Tabla 2.4-1](volume-1-groupings.html#tabla-2-4-1). Es también un [OpenID Provider](appendix-glossary.html#openid-provider), es decir, un servidor de autorización que además autentica a la persona y acredita esa autenticación con un `id_token`[^oidc-op]. Lo es porque [HIX-2](volume-2-hix-2.html) se apoya en SMART App Launch, y SMART entrega ese `id_token` junto con el access token cuando la aplicación pide el scope `openid`[^smart-openid]. Y agrupa un [Patient Identifier Cross-reference Consumer](appendix-glossary.html#patient-identifier-cross-reference-consumer) de PIXm, con el que resuelve a la identidad maestra la identidad de la persona autenticada para fijar el contexto de paciente. **Directorio de la comunidad.** Es el [Directory](appendix-glossary.html#directory) de mCSD. Lo consultan el Record Locator Service, para dirigir cada recuperación cuando el contenido queda en el custodio, y el Document Registry, para validar a quien publica. Es Resource Server de IUA, porque el Record Locator Service le presenta un token en cada consulta, y agrupa además los comunes de [lo que casi todos agrupan](volume-1-groupings.html#lo-que-casi-todos-agrupan). **Master Patient Index.** Agrupa tres actores que trabajan sobre los mismos datos, y es Resource Server de IUA ante todos ellos. - El [Patient Identity Registry](appendix-glossary.html#patient-identity-registry) de PMIR, que recibe por ITI-93 las identidades maestras de la fuente autoritativa, responde las suscripciones de [ITI-94](https://profiles.ihe.net/ITI/PMIR/ITI-94.html) y envía por ITI-93 cada cambio a quien está suscrito, como el Document Registry. PMIR le exige además responder ITI-83 e ITI-78 con las reglas del Patient Identifier Cross-reference Manager y del Patient Demographics Supplier[^pmir-registry-queries]. - El [Patient Identifier Cross-reference Manager](appendix-glossary.html#patient-identifier-cross-reference-manager) de PIXm, que aporta ITI-104, con el que recibe las identidades locales que los miembros declaran y las enlaza con la identidad maestra. - El [Patient Demographics Supplier](appendix-glossary.html#patient-demographics-supplier) de PDQm con la [Match Operation Option](https://profiles.ihe.net/ITI/PDQm/volume-1.html#13822-match-operation-option), que aporta ITI-119, la búsqueda por coincidencia probabilística. **Audit Record Repository.** Es el [Audit Record Repository](https://profiles.ihe.net/ITI/TF/Volume1/ch-9.html) de ATNA con la opción ATX: FHIR Feed, que recibe por ITI-20 los eventos de los actores centrales como recursos AuditEvent. No agrupa más actores que los comunes de [lo que casi todos agrupan](volume-1-groupings.html#lo-que-casi-todos-agrupan). **Fuente autoritativa de identidad.** Es el [Patient Identity Source](appendix-glossary.html#patient-identity-source) de PMIR, que crea, actualiza, fusiona y desactiva las identidades maestras con ITI-93, y un Authorization Client de IUA, porque lo hace con un token que obtiene del Authorization Server de la comunidad con ITI-71 y el grant Client Credentials. Es externa a la comunidad, y HIX no le pide nada que PMIR, IUA, ATNA, BALP y CT no pidan a cualquier sistema que participa. ### Resumen La [Tabla 2.4-2](volume-1-groupings.html#tabla-2-4-2) reúne lo anterior en una sola vista. Las opciones van entre corchetes. ATNA Secure Node o Secure Application, BALP Audit Creator y CT Time Client acompañan a todos los actores salvo a la aplicación del paciente y no se repiten en cada fila. **Tabla 2.4-2:** Actores que agrupa cada actor de HIX | Actor de HIX | Actores agrupados | | --- | --- | | Custodio | MHD Document Source [Comprehensive Metadata, UnContained Reference], PIXm Patient Identity Source, IUA Authorization Client. Salvo bajo la Opción de Almacenamiento Central, también IUA Resource Server [JWT Token, Authorization Server Metadata, Token Introspection si la comunidad la admite] como servicio que aloja el contenido. Opcionalmente PIXm Patient Identifier Cross-reference Consumer, para comprobar por su cuenta el contexto de paciente | | Consumidor | MHD Document Consumer, IUA Authorization Client. Opcionalmente PIXm Patient Identifier Cross-reference Consumer y, bajo las opciones de Demografía y de Coincidencia Demográfica, PDQm Patient Demographics Consumer [Patient Search, Match Operation] | | Aplicación del paciente | MHD Document Consumer, IUA Authorization Client | | Record Locator Service | MHD Document Responder, MHD Document Consumer, mCSD Query Client, IUA Resource Server [Token Introspection], IUA Authorization Client | | Document Registry | MHD Document Recipient [Comprehensive Metadata, UnContained Reference], MHD Document Responder, PMIR Patient Identity Consumer, mCSD Query Client, PIXm Patient Identifier Cross-reference Consumer, IUA Resource Server [Token Introspection, JWT Token, Authorization Server Metadata], IUA Authorization Client | | Authorization Server | IUA Authorization Server [JWT Token, Authorization Server Metadata, Token Introspection], OpenID Provider de OpenID Connect, PIXm Patient Identifier Cross-reference Consumer, IUA Authorization Client | | Directorio de la comunidad | mCSD Directory e IUA Resource Server [Token Introspection, JWT Token, Authorization Server Metadata] | | Master Patient Index | PMIR Patient Identity Registry, PIXm Patient Identifier Cross-reference Manager, PDQm Patient Demographics Supplier [Match Operation], IUA Resource Server [Token Introspection, JWT Token, Authorization Server Metadata] | | Audit Record Repository | ATNA Audit Record Repository [ATX: FHIR Feed] | | Fuente autoritativa de identidad | PMIR Patient Identity Source, IUA Authorization Client | ### Sobre los despliegues Las agrupaciones anteriores describen funciones, no servidores. Una comunidad puede repartirlas entre varios sistemas o reunirlas en uno solo. Por ejemplo, el Document Registry, el Master Patient Index y el directorio pueden compartir un mismo servidor FHIR central. La distribución no cambia las responsabilidades. El Record Locator Service atiende siempre las localizaciones y recuperaciones de los miembros y garantiza que se aplique la decisión de divulgación. El Document Registry recibe las publicaciones y el Master Patient Index, las declaraciones y consultas de identidad. Cada actor comprueba el token del miembro y aplica las reglas de la comunidad para la transacción que recibe. La comunidad puede colocar una fachada común delante de estos servicios, incluido el propio Record Locator Service. Esa fachada cambia cómo se llega a ellos, pero cada actor conserva sus responsabilidades. Cuando el Record Locator Service y otro actor central forman un mismo sistema, sus llamadas son internas y no requieren intercambio de tokens mediante [HIX-1](volume-2-hix-1.html). Los requisitos de autorización de cada actor se detallan en la [sección 2.2](volume-1-actors.html#descripcion-de-actores-y-requisitos). ### Referencias Las citas reproducen el texto publicado por su fuente. Los recortes se marcan con "[...]" y la negrita es de esta guía. [^iua-actors]: [IUA, Table 34.1-1 IUA Profile - Actors and Transactions](https://profiles.ihe.net/ITI/IUA/index.html#341-iua-actors-transactions-and-content-modules): "Authorization Client \| Get Access Token \| R [...] Incorporate Access Token \| R [...] Get Authorization Server Metadata \| O [...] Resource Server \| Incorporate Access Token \| R [...] Introspect Token \| O (Note 1) [...] Get Authorization Server Metadata \| O [...] Note 1: **Optionality of this transaction is "R" for an actor that supports the Token Introspection Option.**" [^iua-options]: [IUA, Table 34.2-1 IUA - Actors and Options, Note 1](https://profiles.ihe.net/ITI/IUA/index.html#342-iua-actor-options): "**Authorization Server or Resource Server Actors shall support at least one of the following options: JWT Token, SAML, or Token Introspection.** The Authorization Client is not and does not need to be aware of the token processing options." [^atna-fhir-feed]: [RESTful ATNA (Query and Feed), Rev. 3.6, §9.2.7.1 ATX: FHIR Feed Option](https://www.ihe.net/uploadedFiles/Documents/ITI/IHE_ITI_Suppl_RESTful-ATNA.pdf): "The ATX: FHIR Feed Option enables **sending ATNA audit records using RESTful capabilities and FHIR resources**. An Audit Record Repository that supports this option shall implement the two RESTful interactions defined in the Record Audit Event [ITI-20] transaction. **A Secure Node, Secure Application or Audit Record Forwarder that supports this option shall at least support one of the two RESTful interactions** defined in the Record Audit Event [ITI-20] transaction." [^mhds-groupings]: [MHDS, Table 1:50.3-1 Required Actor Groupings](https://profiles.ihe.net/ITI/MHDS/volume-1.html#1503-mhds-required-actor-groupings): "Document Registry \| Required \| **CT / Time Client** [...] Required \| **ATNA / Secure Node or Secure Application with the STX: TLS 1.2 with the BCP195 Option and the ATX: FHIR Feed Option** [...] Required \| **MHD / Document Responder** [...] Required \| **MHD / Document Recipient with the Comprehensive Metadata Option** [...] Required \| **PMIR / Patient Identity Consumer** [...] if the Authorization Option \| **IUA / Resource Server with the The IUA Authorization Server Metadata Option** if the Authorization Option \| **IUA / Authorization Server with the The IUA Authorization Server Metadata Option** [...] if the UnContained References Option \| **mCSD / Care Services Selective Consumer** [...] if the SVCM Validation Option \| SVCM / Terminology Consumer". [^mhds-binary]: [MHDS Vol. 1, §1:50.1.1.2 Storage of Binary](https://profiles.ihe.net/ITI/MHDS/volume-1.html#150112-storage-of-binary): "This might be other centralized infrastructure, distributed infrastructure, or **within the system implementing the Document Source**. [...] When this is used by the Community, **the service hosting the Binary shall**: persist the Binary for the lifecycle expected of the Community; provide access to the community members; **use the security model agreed to by the community members**." [^mhds-pic]: [MHDS Vol. 1, §1:50.1 MHDS Actors, Transactions, and Content Modules](https://profiles.ihe.net/ITI/MHDS/volume-1.html#1501-mhds-actors-transactions-and-content-modules): "PMIR - Patient Identity Consumer provides **patient identity synchronization and specifically the merge function** to be applied to any data managed in the Document Registry." [§1:50.1.1.1.3 When the grouped PMIR Patient Identity Consumer – is triggered](https://profiles.ihe.net/ITI/MHDS/volume-1.html#1501113-when-the-grouped-pmir-patient-identity-consumer--is-triggered): "**No behavior is expected of the Document Registry on receipt of a feed containing create, delete, or update**, although the Document Registry may consume and persist these to support the Document Registry requirements to validate Patient references as a recognized Patient within the Community." [^mhds-subject]: [MHDS Vol. 1, §1:50.1.1.1.1 When the grouped MHD Document Recipient – is triggered](https://profiles.ihe.net/ITI/MHDS/volume-1.html#1501111-when-the-grouped-mhd-document-recipient--is-triggered): "The Document Registry SHALL validate that the subject of the DocumentReference, and List Resources is the same Patient, and that **Patient is a recognized and active Patient within the Community**. The Patient identity must be recognized and active by the PMIR Patient Identity Registry in the document sharing community. **This may be accomplished by a query of the PMIR Patient Identity Registry**, by way of a cached internal patient database, or other means." [^mhds-source-comprehensive]: [MHDS, §1:50.4.2.1 Use Case #1: Publication of a new document with persistence](https://profiles.ihe.net/ITI/MHDS/volume-1.html#150421-use-case-1-publication-of-a-new-document-with-persistence): "**The MHD Comprehensive Metadata Option is required of the MHD Document Source** as the MHD Document Recipient within the MHDS Document Registry will implement the Comprehensive Metadata Option." [^oidc-op]: [OpenID Connect Core 1.0, §1.2 Terminology](https://openid.net/specs/openid-connect-core-1_0.html#Terminology): "OpenID Provider (OP): **OAuth 2.0 Authorization Server that is capable of Authenticating the End-User** and providing Claims to a Relying Party about the Authentication event and the End-User." [^smart-openid]: [SMART App Launch, Scopes for requesting identity data](https://hl7.org/fhir/smart-app-launch/scopes-and-launch-context.html#scopes-for-requesting-identity-data): "Some apps need to authenticate the end-user. This can be accomplished by **requesting the scope openid**. [...] When these scopes are requested (and the request is granted), **the app will receive an id_token that comes alongside the access token**. This token must be validated according to the OIDC specification." [^mhd-uncontained]: [MHD, §1:33.2.3 UnContained Reference Option](https://profiles.ihe.net/ITI/MHD/5.0.0/1332_actor_options.html#13323-uncontained-reference-option): "When this longitudinal consistency is managed, then the author, authenticator, sourcePatientInfo, and author entries **do not need to be a contained copy of the information known at the time of publication** ITI-65 since a Reference to the information in these directories will be valid over the full lifecycle of the entries." [§2:3.65.4.1.2.2 Patient Identity](https://profiles.ihe.net/ITI/MHD/5.0.0/ITI-65.html#23654122-patient-identity): "**When the UnContained Reference Option is used, there is no need to populate the sourcePatient extension.**" [^balp-creator]: [BALP, §1:52.1.1.1 Audit Creator](https://profiles.ihe.net/ITI/BALP/volume-1.html#152111-audit-creator): "The Audit Creator shall detect the defined auditable events and record a complaint [sic] AuditEvent as defined. **The Audit Creator shall be grouped with an ATNA Secure Application or ATNA Secure Node with support for ATNA ATX:FHIR Feed Option** defined in the RESTful ATNA Supplement for the recording of the compliant AuditEvent to the Audit Record Repository." [^pmir-registry-queries]: [PMIR Vol. 1, §1:49.1 PMIR Actors, Transactions, and Content Modules](https://profiles.ihe.net/ITI/PMIR/volume-1.html#1491-pmir-actors-transactions-and-content-modules): la Tabla 1:49.1-1 da al "Patient Identity Registry" las transacciones "Mobile Patient Identifier Cross-reference Query [ITI-83]" y "Mobile Patient Demographics Query [ITI-78]" como "Responder" con opcionalidad "**R**". "Note 1: **The Patient Identity Registry shall respond to [ITI-83] queries** using the requirements in that transaction for the Patient Identity Cross-Reference Manager." "Note 2: **The Patient Identity Registry shall respond to [ITI-78] queries** using the requirements in that transaction for the Patient Demographics Supplier." ## Casos de uso y flujos Esta sección recorre los casos de uso que la arquitectura soporta. Cada uno se cuenta desde el punto de vista de quien lo vive y se acompaña del flujo entre actores, con las transacciones y el orden en que ocurren. El detalle de cada transacción está en el Volumen 2. Los casos siguen las tres historias de las figuras de la [sección 2.2](volume-1-actors.html), el laboratorio que publica, el hospital que consulta y la persona que accede a lo suyo, precedidas por la identidad del paciente, que es condición de todas. La publicación, la consulta y el acceso del paciente son independientes entre sí y ocurren en cualquier orden y con cualquier frecuencia. La incorporación de un miembro, que precede a todo, es un procedimiento administrativo y no un caso de uso de esta guía. ### Identidad del paciente #### Descripción del caso de uso Una persona existe en la comunidad desde que la fuente autoritativa de identidad la alimenta al Master Patient Index. El custodio que la atiende declara a la comunidad qué [identidad local](appendix-glossary.html#identidad-local) le corresponde. El Master Patient Index vincula esa identidad con la [identidad maestra](appendix-glossary.html#identidad-maestra) y, desde entonces, los documentos que ese custodio publique sobre esa persona quedan asociados a la misma identidad maestra que los publicados por los demás miembros. Un miembro que declaró sus identidades locales pregunta con su propio identificador de la persona y obtiene la identidad maestra enlazada, que es como la comunidad la nombra. Un miembro que solo consume no declara ninguna, y pregunta con el identificador nacional de la persona, cuyo dominio la comunidad siempre reconoce. Ninguno de los dos obtiene los identificadores de los demás miembros. Un miembro que no dispone de ningún identificador conocido por la comunidad puede, si declara la Opción de Demografía, buscar por datos demográficos entre las identidades maestras y, si declara la Opción de Coincidencia Demográfica, pedir las que más se parecen a unos datos incompletos. Lo que un miembro declara vincula. Nunca crea una persona, nunca fusiona dos y nunca modifica lo que la identidad maestra dice de ella. #### Flujo del proceso ![Alimentación y resolución de la identidad del paciente](hix-flujo-identidad.svg) **Figura 2.5-1:** Alimentación y resolución de la identidad del paciente 1. La fuente autoritativa de identidad alimenta la identidad maestra de la persona mediante [ITI-93](https://profiles.ihe.net/ITI/PMIR/ITI-93.html). 2. El custodio declara su identidad local mediante [ITI-104](https://profiles.ihe.net/ITI/PIXm/ITI-104.html) ante el Master Patient Index, en su propio dominio de identificadores y con el identificador nacional de la persona. El Master Patient Index comprueba que el dominio corresponde a la organización del token y vincula la identidad local con la maestra. Por defecto, si la persona no tiene identidad maestra, rechaza la declaración e indica el motivo, como explica la [sección 2.2](volume-1-actors.html#regla-de-identidad). 3. Un consumidor resuelve su identificador a la identidad maestra mediante [ITI-83](https://profiles.ihe.net/ITI/PIXm/ITI-83.html) ante el Master Patient Index y, si declara la Opción de Demografía, busca por datos demográficos mediante [ITI-78](https://profiles.ihe.net/ITI/PDQm/ITI-78.html) o, con la Opción de Coincidencia Demográfica, mediante [ITI-119](https://profiles.ihe.net/ITI/PDQm/ITI-119.html). ### Publicación de un documento #### Descripción del caso de uso Un laboratorio termina un resultado y lo publica en la comunidad. Envía los metadatos y conserva el documento. Desde ese momento el resultado es localizable por cualquier miembro autorizado, sin que el laboratorio deba anticipar quién lo buscará ni conocer a nadie más que a la comunidad. Lo publica con el [propósito de uso](appendix-glossary.html#proposito-de-uso) de la atención, `TREAT`. El laboratorio nombra al paciente con el identificador nacional de la persona y con el MRN que él mismo declaró, se nombra a sí mismo como [custodio](appendix-glossary.html#custodio), indica dónde está el documento con una ruta relativa a su propio endpoint y etiqueta su confidencialidad. La comunidad comprueba que el laboratorio publica solo por sí mismo y solo sobre pacientes que él mismo declaró, resuelve la identidad maestra y registra el [puntero](appendix-glossary.html#puntero). Si rechaza la publicación, dice por qué. Conviene que el laboratorio no dé por publicado un documento hasta recibir la confirmación. #### Flujo del proceso ![Publicación de un documento](hix-flujo-publicacion.svg) **Figura 2.5-2:** Publicación de un documento 1. El custodio conserva el documento en su repositorio y obtiene del Authorization Server un token para publicar. 2. El custodio publica los metadatos, agrupados en un SubmissionSet, mediante [ITI-65](https://profiles.ihe.net/ITI/MHD/5.0.0/ITI-65.html) ante el Document Registry. Bajo la Opción de Almacenamiento Central, incluye el contenido. 3. El Document Registry comprueba que el custodio del puntero es la organización que el token declara y que esa organización es un miembro activo según el directorio, que la URL de contenido es relativa y que el puntero lleva etiqueta de confidencialidad. Rechaza la publicación que no cumpla alguna de esas condiciones e indica el motivo. 4. El Document Registry resuelve a la identidad maestra, mediante [ITI-83](https://profiles.ihe.net/ITI/PIXm/ITI-83.html), el identificador nacional con el que el custodio nombró al paciente, y la escribe como sujeto del puntero, que conserva también la identidad local. El Document Registry lo registra a nombre del custodio y responde. Si el paciente no resuelve a una identidad maestra, o el custodio no declaró esa identidad local, la publicación se rechaza. ### Consulta del expediente por un profesional #### Descripción del caso de uso Un profesional de un hospital atiende a la misma persona y necesita su historial. Consulta la comunidad con el identificador que su propio sistema conoce de la persona, o con su identificador nacional, y con el propósito de uso de la atención habitual, `TREAT`. Obtiene la lista de documentos que la política le permite ver y recupera el que le interesa. No sabe, ni necesita saber, qué organización lo custodia. La recuperación atraviesa dos tramos autorizados. El profesional llega a la comunidad con un [token del solicitante](appendix-glossary.html#token-del-solicitante), y la comunidad llega al custodio con un [token mediado](appendix-glossary.html#token-mediado) para ese único custodio, que el custodio valida por sí mismo. La [sección 2.6](volume-1-security.html#modelo-de-confianza) compara los dos tokens y dice qué lleva cada uno. Si el custodio de un documento no responde, esa recuperación lo indica, sin que se confunda con un documento inexistente. La localización y las demás recuperaciones no se ven afectadas. En una urgencia la historia cambia en dos puntos. El profesional consulta con el propósito de uso `ETREAT`, y qué permite frente a `TREAT` lo fija la política de la comunidad, por ejemplo divulgar documentos que en atención habitual exigirían un consentimiento. Y si la persona llega sin un identificador fiable, el hospital puede buscarla por sus datos demográficos bajo la Opción de Demografía o la Opción de Coincidencia Demográfica, como en la [Figura 2.2-2](volume-1-actors.html#figuras-2-2). La búsqueda la habilita el scope del token, no el propósito. El propósito se evalúa después, en la [decisión de divulgación](appendix-glossary.html#decision-de-divulgacion). #### Flujo del proceso ![Localización y recuperación mediada](hix-flujo-localizacion.svg) **Figura 2.5-3:** Localización y recuperación mediada 1. El [consumidor](appendix-glossary.html#consumidor) obtiene del Authorization Server un token cuya audiencia incluye al Record Locator Service y localiza mediante [ITI-67](https://profiles.ihe.net/ITI/MHD/5.0.0/ITI-67.html). En una urgencia sin identificador conocido, busca antes a la persona por datos demográficos mediante ITI-78 o ITI-119 ante el Master Patient Index. 2. El Record Locator Service comprueba el token mediante [ITI-102](https://profiles.ihe.net/ITI/IUA/index.html#3102-introspect-token-iti-102) y consulta el Document Registry mediante ITI-67 con el identificador que recibió. El Document Registry lo resuelve a la identidad maestra mediante ITI-83. El Record Locator Service evalúa la decisión de divulgación sobre cada puntero y devuelve los divulgados, con URL de contenido que apuntan a sí mismo. 3. El consumidor recupera mediante [ITI-68](https://profiles.ihe.net/ITI/MHD/5.0.0/ITI-68.html) sobre una de esas URL. 4. El Record Locator Service relee el puntero y vuelve a evaluar la divulgación. Cuando el contenido queda en el custodio, resuelve su endpoint en el directorio mediante [ITI-90](https://profiles.ihe.net/ITI/mCSD/ITI-90.html) y obtiene mediante [HIX-1](volume-2-hix-1.html) un token para ese custodio. 5. El Record Locator Service recupera el documento del custodio mediante ITI-68. El custodio valida el token con las claves públicas del Authorization Server y entrega el documento, que el Record Locator Service entrega al consumidor. Bajo la Opción de Almacenamiento Central, lo recupera del Document Registry en lugar del custodio, con un token mediado para él. ### Acceso del paciente a su expediente #### Descripción del caso de uso Una persona abre una aplicación de su elección y accede a sus propios documentos. La aplicación no la opera la comunidad y no tiene autoridad permanente sobre nada, solo lo que esta persona le concedió y mientras dure. La persona tiene una identidad verificada ante el Authorization Server. Cómo la obtiene es política de la comunidad. Al lanzar la aplicación, el Authorization Server la autentica, resuelve esa identidad a la identidad maestra y emite un token cuyo contexto de paciente es ella misma. La aplicación no elige a qué paciente accede. El contexto viene fijado en el token y el Record Locator Service confina cada consulta a ese paciente. El propósito de uso dice quién actúa, normalmente la propia persona, con el código `PATRQT` de la [Tabla 2.2-3](volume-1-actors.html#tabla-2-2-3). La comunidad decide si un familiar o un representante legal puede actuar en su nombre, y en qué condiciones. A partir de ahí, sus consultas y recuperaciones son las de cualquier otro solicitante. Este caso es el que permite a HIX servir a la persona lo que es suyo, y no solo lo que la política de la comunidad permite entre organizaciones. #### Flujo del proceso ![Acceso del paciente a su expediente](hix-flujo-paciente.svg) **Figura 2.5-4:** Acceso del paciente a su expediente 1. La [aplicación del paciente](appendix-glossary.html#aplicacion-del-paciente) inicia [HIX-2](volume-2-hix-2.html). El Authorization Server autentica a la persona, obtiene su autorización para la aplicación, resuelve su identidad verificada a la identidad maestra mediante ITI-83 y emite el token con ese contexto de paciente y el propósito de uso que corresponde a quien actúa. 2. La aplicación localiza y recupera mediante ITI-66, ITI-67 e ITI-68 a través del Record Locator Service, que confina cada operación al paciente del contexto. ### Casos previstos Los siguientes casos forman parte de la arquitectura y se especificarán en versiones posteriores de esta guía. La arquitectura ya fija dónde se aplican y qué información necesitan. - **Consentimiento anticipado del paciente.** La persona registra una directiva que permite o restringe la divulgación de sus documentos por clase de solicitante, propósito de uso, categoría de documento y ventana de validez. Se evalúa en cada operación bajo la Opción de Consentimiento. - **Administración del consentimiento desde una aplicación.** La persona concede a una aplicación de su elección permiso para leer y escribir sus directivas. - **Acceso solicitado por un miembro cuando no hay directiva.** Un miembro dirige a la persona al Authorization Server, que autoriza ese acceso específico. El token resultante lleva el contexto de paciente y la divulgación avanza bajo una autoridad que un momento antes no existía. - **Acceso con anulación de la política.** Un profesional accede a documentos que la política ordinaria no le permitiría, declarando el propósito de uso `BTG`. Cómo se admite lo fija cada comunidad, como indica la [Tabla 2.2-3](volume-1-actors.html#tabla-2-2-3). HIX ya exige que quede registrado en la auditoría, como fija la [sección 2.6](volume-1-security.html#acceso-de-emergencia). - **Identidad del personal sanitario.** El Authorization Server federa hacia el proveedor de identidad de cada institución en lugar de alojar cuentas de profesionales. ## Consideraciones de seguridad Esta sección describe el modelo de confianza de HIX, los controles que la arquitectura especifica y las decisiones que cada comunidad debe tomar por política. Sigue el orden de las consideraciones de seguridad de MHDS, es decir, políticas y gestión de riesgo, controles técnicos y aplicación al intercambio de documentos ([MHDS Vol. 1, §1:50.5](https://profiles.ihe.net/ITI/MHDS/volume-1.html#1505-mhds-security-considerations))[^mhds-security], e intercala el modelo de confianza de HIX, que MHDS no necesita porque no tiene mediador. Como IHE, esta guía resuelve problemas de interoperabilidad mediante estándares. No define políticas de privacidad ni de seguridad, gestión de riesgo, funcionalidad clínica, controles físicos ni controles generales de red ([MHDS Vol. 1, §1:50.5.1](https://profiles.ihe.net/ITI/MHDS/volume-1.html#15051-policies-and-risk-management))[^mhds-policy]. Lo que sigue separa lo que queda en manos de la comunidad de lo que fija la arquitectura. ### Políticas y gestión de riesgo MHDS advierte que el marco de políticas de una comunidad debe definirse antes de construirla[^mhds-security]. Las secciones anteriores dejan a la política de la comunidad una serie de decisiones que aquí se reúnen. - Qué organizaciones pueden ser miembros, quién lo certifica, bajo qué condiciones dejan de serlo y quién financia la infraestructura central. La [Tabla 2.1-2](volume-1-concepts.html#tabla-2-1-2) de compromisos de la arquitectura lo señala como el riesgo principal de la comunidad a largo plazo. - Qué propósitos de uso se admiten, con qué condiciones y qué documentos alcanza cada uno, en particular qué permite `ETREAT` frente a `TREAT`, como indica la [Tabla 2.2-3](volume-1-actors.html#tabla-2-2-3). - Qué política de divulgación aplica mientras el modelo de consentimiento no esté especificado, como señala la [sección 2.3](volume-1-options.html). - Qué custodios pueden ejercer la Opción de Almacenamiento Central y quién lo decide. - Cómo se verifica que los custodios etiquetan correctamente la confidencialidad de sus documentos. - Cómo obtiene una persona la identidad verificada con la que se autentica ante el Authorization Server, como señala la [sección 2.5](volume-1-usecases.html). - Si un familiar autorizado o un representante legal puede actuar en nombre de una persona, cómo se acredita esa relación y qué paciente queda como contexto de su token, como señala [HIX-2](volume-2-hix-2.html#peticion-de-autorizacion). - Qué solicitantes pueden buscar pacientes por datos demográficos y qué identidades maestras se les revelan por esa vía, como exigen la Opción de Demografía y la Opción de Coincidencia Demográfica. - Cuánto tiempo se conservan los registros de auditoría, quién puede consultarlos y qué ocurre con una operación cuando el Audit Record Repository no está disponible. - Qué constituye un acceso de emergencia, cómo se admite, cómo lo indica el solicitante al pedir el token y qué consecuencias tiene invocarlo. - Si el acceso de red a los custodios se cierra de modo que la vía mediada sea la única alcanzable, o si esa restricción es solo defensa en profundidad. - Cómo se protegen y vigilan el Record Locator Service y las claves del Authorization Server, como señala la [sección 2.6.5](volume-1-security.html#riesgos-residuales). - Qué vida máxima admite el Authorization Server para los tokens de los solicitantes, y si se exige a los custodios rechazar un `jti` que ya vieron. - Cómo autoriza el Record Locator Service sus llamadas a los actores centrales desplegados como sistemas distintos, con HIX-1, con un token propio o de otra forma que cumpla la [sección 2.2](volume-1-actors.html#record-locator-service), sabiendo que con un token propio un mediador comprometido alcanza lo que ese token permite sin un solicitante, como señala la [sección 2.6.5](volume-1-security.html#riesgos-residuales). - Si se admite la introspección en el custodio, con la dependencia del Authorization Server en cada recuperación que conlleva, como señala la [sección 2.6.2](volume-1-security.html#validacion-en-el-custodio). ### Modelo de confianza El límite de confianza pasa entre cada miembro y la infraestructura central, como establece la [sección 2.1](volume-1-concepts.html). Una recuperación cruza ese límite dos veces, del solicitante a la comunidad y de la comunidad al custodio, y cada cruce lleva un token de un régimen distinto. El primero es el token que el solicitante obtiene del Authorization Server, destinado a los Resource Servers centrales, que el Record Locator Service comprueba por introspección. El segundo es el [token mediado](appendix-glossary.html#token-mediado) que el Record Locator Service obtiene con [HIX-1](volume-2-hix-1.html) para cada custodio y cada actor central desplegado como un sistema distinto que alcanza, y que el destino valida por sí mismo. Hacia un actor central, la comunidad puede autorizar en su lugar un token propio del Record Locator Service, como fija la [sección 2.2](volume-1-actors.html#record-locator-service). La [Tabla 2.6-1](volume-1-security.html#tabla-2-6-1) los compara. **Tabla 2.6-1:** Los dos regímenes de token | | Token del solicitante | Token mediado | | --- | --- | --- | | Quién lo obtiene | El miembro con ITI-71, o la aplicación del paciente con [HIX-2](volume-2-hix-2.html) | El Record Locator Service con [HIX-1](volume-2-hix-1.html) | | Audiencia | Los Resource Servers centrales que define la comunidad, o solo el Record Locator Service si lo obtiene la aplicación del paciente | Un único custodio, o los actores centrales que el Authorization Server asocia al `resource` del intercambio | | Vida | La que fije el Authorization Server | Dos minutos como máximo, y nunca más que la vida restante del token del solicitante | | Cómo se valida | El Record Locator Service, por introspección con ITI-102 una vez por operación. Otro Resource Server central, preferiblemente también por introspección, o por sí mismo con la JWT Token Option | En el destino, con las claves que publica el Authorization Server ([JWKs](https://www.rfc-editor.org/info/rfc7517/)), sin necesidad de introspección | | Sujeto | El sistema del miembro, o la persona que lanzó la aplicación | El mismo | | Extensiones de IUA | Del miembro, la organización y el propósito de uso. De la aplicación del paciente, el propósito de uso, y la organización si la aplicación tiene una registrada | Las mismas | | Scope | El concedido al solicitante | Solo el de la transacción que motivó el intercambio | | Contexto de paciente | Solo si lo obtuvo una aplicación del paciente | El mismo, en el claim `patient`, si lo hay | | Actor | Ninguno | El Record Locator Service, en el claim `act` | > **Nota.** El token propio que la [sección 2.2](volume-1-actors.html#record-locator-service) admite para las llamadas a los actores centrales es del primer régimen. El Record Locator Service lo obtiene con ITI-71, con ese actor como audiencia y solo las transacciones autorizadas como scope, nunca ITI-68, y el destino lo valida como el de cualquier solicitante. No nombra a ningún solicitante, y por eso cada llamada se registra bajo el identificador de correlación de la operación que la motivó. El sujeto del token del solicitante es el sistema del miembro, porque el Authorization Server autentica a ese cliente y no a una persona, y en ese caso IUA pone como sujeto al cliente. La organización y el propósito de uso van en las extensiones que IUA define para el token ([IUA, §3.71.4.2.2.1](https://profiles.ihe.net/ITI/IUA/index.html#3714221-json-web-token-option))[^iua-sub]. Cuando el token lo obtiene una aplicación del paciente, el sujeto es la persona que la lanzó. El token de un miembro no identifica a la persona que actúa dentro de su organización. IUA define extensiones para ello, como `subject_name` y `subject_role`, pero no define de dónde obtiene el Authorization Server esos datos ni con qué flujo, y HIX tampoco lo fija. Por eso la auditoría de la comunidad llega hasta la organización, y la del miembro, hasta la persona. De la tabla se siguen cuatro reglas. De cada una conviene decir qué fija HIX, de qué depende y qué queda en manos de la comunidad. **Un token mediado nunca vale ante dos custodios.** El formato no lo impone. El claim `aud` de un JWT admite una lista de audiencias ([RFC 7519, §4.1.3](https://www.rfc-editor.org/rfc/rfc7519.html#section-4.1.3))[^rfc7519-aud], y RFC 9068 recomienda rellenarlo con el recurso que el cliente indicó al pedir el token ([RFC 9068, §3](https://www.rfc-editor.org/rfc/rfc9068.html#section-3))[^rfc9068-aud]. HIX lo restringe cuando el destino es un custodio, porque de eso depende que un custodio no pueda reutilizarlo ante otro. Ante actores centrales, un mismo `resource` puede corresponder a varios Resource Servers, igual que en el token del miembro. El token de un miembro, en cambio, nombra en `aud` a los Resource Servers centrales que define la comunidad, y nunca a un custodio, y el de la aplicación del paciente nombra solo al Record Locator Service. > **Nota.** Cómo pide cada cliente su token y qué Resource Servers quedan en su `aud` según el despliegue lo detallan [ITI-71](volume-2-authorization.html#iti-71) y [HIX-2](volume-2-hix-2.html#peticion-de-autorizacion) en el Volumen 2. **El token del solicitante no sale de la infraestructura central.** El Record Locator Service no lo reenvía a ningún custodio ni actor central. Ante cada custodio presenta un token mediado para ese destino. Ante cada actor central desplegado como un sistema distinto presenta también uno, salvo que la comunidad autorice un token propio, como fija la [sección 2.2](volume-1-actors.html). Así el solicitante nunca tiene una credencial que valga ante un custodio, y un custodio nunca recibe una que valga ante otro. **El custodio puede validar el token sin preguntar al Authorization Server.** Todo lo que necesita está en el token y en las claves que el Authorization Server publica. Esa publicación es su única dependencia, y la resuelve por adelantado, conservando las claves y renovándolas cuando aparece un identificador de clave que no conoce. La subsección siguiente detalla la validación y dice cuándo una comunidad puede añadirle la introspección. **El Record Locator Service no accede por cuenta propia a ningún custodio ni al contenido.** No tiene credenciales permanentes hacia ningún custodio, ni hacia el Document Registry para ITI-68. Cada recuperación la hace a nombre de un solicitante, con el token mediado para ese destino, y así queda auditada. De esta forma el Record Locator Service no puede alcanzar documentos sin una petición de un solicitante que lo justifique, y una credencial suya comprometida no da acceso a ningún documento por sí sola. Hacia los demás actores centrales, la guía recomienda el token mediado y la comunidad puede autorizar un token propio, como fija la [sección 2.2](volume-1-actors.html#record-locator-service). El Document Registry, para sus consultas ITI-83 e ITI-90, y el Authorization Server, para su consulta ITI-83, usan un token propio que obtienen con el grant Client Credentials, como fija la [sección 2.2](volume-1-actors.html). #### Validación en el custodio El custodio recibe el token mediado y lo valida como RFC 9068 pide a todo Resource Server que recibe un access token en forma de JWT ([RFC 9068, §4](https://www.rfc-editor.org/rfc/rfc9068.html#section-4))[^rfc9068-validate]. Eso cubre la firma con las claves que publica el Authorization Server, el rechazo de un `alg` con valor `none`, que el emisor sea exactamente el Authorization Server de la comunidad, que el tipo de token sea `at+jwt`, que la audiencia lo contenga y que el token no haya expirado. HIX añade las comprobaciones siguientes, que el custodio **SHALL** hacer además. 1. Que el algoritmo de firma es uno de los que la comunidad admite. 2. Que la audiencia es exactamente él, y no solo que lo contenga, porque un token mediado para un custodio nunca nombra a otro. 3. Que el momento de emisión es coherente con la vida máxima de dos minutos. 4. Que lleva un sujeto y un identificador de token. 5. Que el cliente al que se emitió es el Record Locator Service. 6. Que el scope cubre la transacción que recibe. El custodio **SHOULD** comprobar además que el actor declarado en el claim `act` es el Record Locator Service. Las comprobaciones que más pesan son la audiencia y el cliente. La audiencia sola no basta, porque un token emitido directamente a otro cliente para esa misma audiencia la pasaría. El cliente es lo que vuelve estructural que solo el Record Locator Service pueda alcanzar a un custodio en nombre de alguien, porque el Authorization Server no emite por otro camino un token con esa audiencia. El claim `act` lo confirma, porque es la forma en que OAuth 2.0 Token Exchange declara que hubo delegación y quién actúa ([RFC 8693, §4.1](https://www.rfc-editor.org/rfc/rfc8693.html#section-4.1))[^rfc8693-act]. El custodio **SHALL** validar el token mediado con las claves que publica el Authorization Server, y esa validación basta para aceptarlo. HIX no exige introspección en el custodio. El custodio **MAY** comprobarlo además por introspección, con la [Token Introspection Option](https://profiles.ihe.net/ITI/IUA/index.html#3424-token-introspection-option) de IUA y [ITI-102](https://profiles.ihe.net/ITI/IUA/index.html#3102-introspect-token-iti-102), si la comunidad lo admite. Entonces cada recuperación depende del Authorization Server en el momento de atenderla, y esa dependencia se asume a sabiendas. #### Lo que un token prueba y lo que no Un custodio que recibe un token mediado puede comprobar por sí mismo cinco cosas. - Que lo emitió el Authorization Server de la comunidad. - Que el Record Locator Service lo pidió en nombre de un solicitante concreto. - Que vale ante él y ante nadie más. - Que autoriza solo la transacción para la que se intercambió. El token del solicitante puede llevar varios scopes, pero el Record Locator Service pide en el intercambio únicamente el de la transacción que va a realizar, por ejemplo el de ITI-68 al recuperar. El scope es siempre el identificador de la transacción IHE, también en el token de la aplicación del paciente, como explica [HIX-2](volume-2-hix-2.html). - Que expira en dos minutos como máximo. El token no nombra ningún documento. Mientras dura, autoriza esa transacción ante ese custodio, sea cual sea el documento. Tampoco nombra al paciente, porque el token de un miembro no lleva ninguno, como explica la [sección 2.1](volume-1-concepts.html). La excepción es la aplicación del paciente. Su contexto de paciente, fijado con [HIX-2](volume-2-hix-2.html), se conserva en el intercambio. Quien confina las consultas a ese expediente es el Record Locator Service, como punto de aplicación de la política de la comunidad. El custodio **MAY** comprobar además ese contexto por su cuenta, resolviendo con [ITI-83](https://profiles.ihe.net/ITI/PIXm/ITI-83.html) la identidad maestra del paciente de cada documento. Lo que el token sí aporta es el contexto con el que se decide, en las extensiones de IUA. Quién pide, para qué organización, con qué propósito de uso y, si lo hay, sobre qué paciente. Ese contexto acota lo que puede alcanzarse con el token, y con él se decide qué documento se entrega, en tres capas y en este orden. 1. La [decisión de divulgación](appendix-glossary.html#decision-de-divulgacion), que la infraestructura central aplica sobre los punteros antes de mover contenido. 2. La política local del custodio sobre su propio endpoint. 3. La auditoría, que no previene pero acota y detecta. #### Contención de una credencial comprometida El Authorization Server **SHALL** revocar los tokens vigentes de un cliente al deshabilitarlo, de modo que la siguiente introspección los declare inactivos, que es el estado que RFC 7662 prevé para un token revocado ([RFC 7662, §2.2](https://www.rfc-editor.org/rfc/rfc7662.html#section-2.2))[^rfc7662-active], y ningún intercambio pueda partir de ellos. Un token mediado ya emitido no tiene ciclo de vida propio. El Record Locator Service lo usa una sola vez, en la transacción que lo motivó, y expira en dos minutos como máximo, así que una transacción ya en curso termina. Lo que contiene una credencial comprometida es que los tokens obtenidos con ella dejen de valer, no que cambie la credencial. Si el Authorization Server los revoca también al rotar el secreto o la clave de un cliente es decisión de su implementación. Si no lo hace, hay que revocarlos aparte. ### Controles técnicos de seguridad y privacidad HIX especifica los siguientes controles. Cada uno remite a la sección que lo fija. - **Autenticación de sistemas.** Toda conexión entre dos participantes se autentica en ambos extremos con ATNA, como fija la [sección 2.4](volume-1-groupings.html), salvo la de la aplicación del paciente, que se autentica con su token de [HIX-2](volume-2-hix-2.html). Ningún participante acepta tráfico anónimo. Bajo la [Opción de Canal de Interconexión](volume-1-options.html#opcion-de-canal-de-interconexion), la autenticación mutua del tramo entre organizaciones la aporta la red de intercambio. - **Autorización.** Toda transacción que inicia un miembro, y toda llamada que el Record Locator Service hace a un custodio o a un actor central, presenta un token emitido por el Authorization Server de la comunidad y destinado a quien la recibe, como fija la [sección 2.2](volume-1-actors.html). - **Delegación acotada.** El token con el que la comunidad alcanza a un custodio se emite para ese único custodio y un solo tipo de transacción, a nombre del solicitante original y con el Record Locator Service como actor, como fija la [sección 2.2](volume-1-actors.html#authorization-server). - **Mínimo privilegio.** El scope de un token mediado se limita a la transacción que motivó el intercambio, como fija la [sección 2.2](volume-1-actors.html#authorization-server). Poder localizar un documento nunca da poder para recuperarlo. - **Confidencialidad en tránsito.** Todo tramo entre participantes viaja cifrado, incluido el que atraviesa un canal de interconexión bajo la Opción de Canal de Interconexión. El tramo entre un custodio y su propio servidor de seguridad es responsabilidad del custodio, como fija la [sección 2.3](volume-1-options.html). - **Divulgación decidida sobre los punteros.** La política se evalúa en la infraestructura central, una vez por consulta, sobre los metadatos del índice y antes de que se mueva contenido, como fija la [sección 2.1](volume-1-concepts.html). - **Auditoría en ambos extremos.** El miembro que solicita y la infraestructura central registran la localización. Infraestructura central y custodio registran la recuperación. Ningún tramo queda sin testigo. - **Trazabilidad entre tramos.** Los registros de una misma divulgación comparten un identificador de correlación, de modo que la interacción completa pueda reconstruirse. - **Identidad del paciente.** Solo la fuente autoritativa crea identidades maestras. Lo que un miembro declara vincula su identidad local con una de ellas, en su propio dominio, y queda registrado como una afirmación suya. ### Aplicación al intercambio de documentos #### Seguridad básica Todo actor de HIX, salvo la aplicación del paciente, es un Secure Node o Secure Application de ATNA y un Time Client de CT, como fija la [sección 2.4](volume-1-groupings.html). Los actores centrales registran sus eventos en el Audit Record Repository de la comunidad y cada miembro registra los de su lado, con el contenido que cada perfil define para su transacción a partir de los patrones de BALP. El Record Locator Service **SHALL** registrar tanto la solicitud que recibe como cada recuperación que origina hacia un custodio, bajo un identificador de correlación que él mismo acuña y transmite al custodio, y **SHALL NOT** transmitir hacia el custodio ninguno que el solicitante proponga. Los registros de auditoría **SHALL NOT** contener un token completo ni contenido clínico. BALP pide atar cada evento a su token sin guardar el token ([BALP, §3:5.7.5](https://profiles.ihe.net/ITI/BALP/content.html#3575-oauth-security-token))[^balp-token], y su patrón Minimal lo hace con el `jti`, que guarda en `agent.policy` ([BALP, §3:5.7.5.4](https://profiles.ihe.net/ITI/BALP/content.html#35754-oauth-mapping-to-auditevent))[^balp-jti]. #### Protección según el tipo de documento La política de la comunidad determina qué solicitante alcanza qué documentos. MHDS lo plantea con una tabla de ejemplo que cruza el código de confidencialidad de cada documento con el rol del solicitante, y señala que ese rol y el propósito de uso llegan en el token de IUA ([MHDS Vol. 1, §1:50.5.3.2](https://profiles.ihe.net/ITI/MHDS/volume-1.html#150532-protecting-different-types-of-documents))[^mhds-doctypes]. La arquitectura ofrece el punto donde aplicarla y los datos con los que evaluarla, es decir, quién solicita, en nombre de qué organización, con qué propósito, sobre qué paciente y con qué etiqueta de confidencialidad. La [Tabla 2.6-2](volume-1-security.html#tabla-2-6-2) es la versión de HIX de ese ejemplo, con el propósito de uso en lugar del rol porque es lo que el token de HIX lleva siempre. Es un ejemplo, no un requisito. **Tabla 2.6-2:** Ejemplo de política de acceso por etiqueta de confidencialidad | Etiqueta del documento | Solicitante | Resultado | | --- | --- | --- | | `N`, normal | Profesional de un miembro con propósito `TREAT` | Permitido | | `N`, normal | La propia persona con propósito `PATRQT` | Permitido | | `R`, restringido | Profesional de un miembro con propósito `TREAT` | Permitido con registro reforzado | | `R`, restringido | La propia persona con propósito `PATRQT` | Según política de la comunidad | | `V`, muy restringido | Cualquiera salvo el custodio | Denegado, salvo acceso de emergencia | Cada comunidad define su equivalente y lo aplica en el punto donde toma la decisión de divulgación. La política falla cerrada. Un puntero sin etiqueta se rechaza al publicar, como fija la [sección 2.2](volume-1-actors.html), y el Record Locator Service **SHALL** garantizar que una etiqueta que la política no reconoce se trate como la más restrictiva, también cuando la decisión se evalúa en el Document Registry. FHIR pide a toda guía de implementación decir qué hacer con una etiqueta que no se reconoce, sin prescribir la respuesta ([FHIR R5, Security Labels](https://hl7.org/fhir/R5/security-labels.html))[^fhir-seclabels]. #### Consentimiento del paciente La decisión base aplica la política única de la comunidad, como fija la [sección 2.2](volume-1-actors.html#record-locator-service). La [Opción de Consentimiento](volume-1-options.html#opcion-de-consentimiento) la extiende al consentimiento de cada paciente, cuyo modelo se especificará a partir de PCF, como explica la [sección 2.1](volume-1-concepts.html#divulgacion). #### Superficies de identidad Las transacciones de identidad también divulgan. ITI-83 revela que un identificador corresponde a una persona que la comunidad conoce, e ITI-78 e ITI-119 revelan qué identidades maestras coinciden con unos datos demográficos, o se les parecen. Ninguna revela las identidades locales de otros miembros, como fijan la [sección 2.2](volume-1-actors.html) para ITI-83 y las opciones de Demografía y de Coincidencia Demográfica de la [sección 2.3](volume-1-options.html) para ITI-78 e ITI-119. Estas superficies las habilita el scope del token, no el propósito de uso, y la comunidad decide qué solicitantes pueden ejercerlas y qué identidades maestras se revelan por datos demográficos. #### Acceso de emergencia MHDS pide reconocer los modos de emergencia desde el diseño, y advierte que anular una restricción del paciente por peligro inminente no es romper la política sino una condición explícita dentro de ella ([MHDS Vol. 1, §1:50.5.1](https://profiles.ihe.net/ITI/MHDS/volume-1.html#15051-policies-and-risk-management))[^mhds-emergency]. HIX distingue dos casos con los propósitos de uso de la [Tabla 2.2-3](volume-1-actors.html#tabla-2-2-3). Con `ETREAT`, un profesional autorizado atiende una urgencia y la política de la comunidad decide qué le permite frente a `TREAT`. Con `BTG`, accede quien no está autorizado para ese acceso, con anulación de la política, que es lo que HL7 define para ese código[^btg]. HIX no define cuándo procede ninguno de los dos ni cómo los pide el solicitante, porque IUA no define ningún mecanismo para ello. El Authorization Server **SHALL** emitirlos como propósito de uso solo cuando su registro los admita para ese cliente, y el Record Locator Service **SHALL** registrar en la auditoría el propósito de emergencia con el que divulgó. ### Riesgos residuales La arquitectura no impide que un componente se vea comprometido. Eso depende de cómo se construye, despliega y opera cada sistema, y queda fuera de esta guía, como también queda fuera de IHE y hasta OAuth 2.0. Las causas son las de cualquier sistema, como un supply chain attack sobre una dependencia o una imagen, el robo de credenciales o de claves de firma, una misconfiguration, una vulnerabilidad sin parchar o un insider. Lo que busca HIX es minimizar la superficie de ataque aplicando least privilege a cada acceso, de modo que un componente comprometido alcance lo menos posible. De ahí salen el token mediado de [HIX-1](volume-2-hix-1.html), que nunca vale ante dos custodios y autoriza un solo tipo de transacción, y las decisiones que esta guía deja a la comunidad, reunidas en la [sección 2.6.1](volume-1-security.html#politicas-y-gestion-de-riesgo). Para las llamadas del Record Locator Service a los actores centrales desplegados como sistemas distintos, las dos formas de autorización de la [sección 2.2](volume-1-actors.html#record-locator-service) tienen costos distintos. HIX-1 no deja al mediador ninguna credencial que valga sin una petición viva y lleva al destino el sujeto original, pero añade un intercambio por llamada. El token propio ahorra ese intercambio y es más simple de operar, pero es una credencial permanente con la que un mediador comprometido alcanza sin solicitante lo que ese token permite, como consultar el directorio o localizar punteros, aunque nunca un documento; el destino solo ve al mediador como sujeto. La comunidad asume estos costos al elegir cómo autoriza las llamadas. #### Si un componente se ve comprometido - **Record Locator Service.** No tiene acceso arbitrario a documentos ni custodios. Solo ve el tráfico que transita por él y los tokens de los solicitantes, y solo alcanza lo que esos tokens permiten mientras están vigentes. - **Authorization Server.** Puede emitir cualquier token, porque es la raíz de confianza. Nada dentro de HIX lo acota, y proteger sus claves es la primera responsabilidad de la comunidad. - **Document Registry.** Solo posee metadatos, salvo el contenido que conserva bajo la [Opción de Almacenamiento Central](volume-1-options.html#opcion-de-almacenamiento-central). Expone qué documentos existen de cada persona, pero no la dirección de los custodios. - **Credenciales robadas de un miembro.** Con ellas se obtienen tokens como ese miembro, con el scope, la organización y los propósitos que su registro admite. Solo se puede afectar a los pacientes y documentos de su propio dominio, y fuera de él solo hacer las consultas que la decisión de divulgación le permita. Ningún token suyo vale ante un custodio. Deshabilitar el cliente revoca sus tokens vigentes, como fija la [sección 2.6.2](volume-1-security.html#contencion-de-una-credencial-comprometida). - **Credenciales robadas del Record Locator Service.** Con ellas no se alcanza ningún documento ni custodio, porque cada intercambio exige además el token de un solicitante. Por eso el Record Locator Service no puede hacer casi nada sin un miembro que interactúe con él. Si la comunidad le da un token propio hacia actores centrales, con esas credenciales se alcanza lo que ese token permite, como consultar el directorio o localizar punteros, nunca un documento, acotado por la auditoría y por los límites de tasa que fije la comunidad. Cuando el despliegue reúne en un mismo sistema al Record Locator Service y a otros actores centrales, comprometer ese sistema compromete todo lo que reúne, y esa es la contrapartida que acepta quien elige ese despliegue. Deshabilitar el cliente revoca sus tokens vigentes. - **Un token mediado robado.** Vale ante el destino que nombra su `resource`, nunca ante dos custodios, para un solo tipo de transacción y durante dos minutos como máximo. El custodio **MAY** rechazar un `jti` que ya vio. #### Límites que acota la política de la comunidad - **Revocación.** Quien valida el token por sí mismo mediante JWKs no ve una revocación hasta que el token expira. - **Enumeración.** La búsqueda por datos demográficos permite enumerar pacientes dentro de lo que la política revela. - **Etiquetado.** Un custodio puede etiquetar mal la confidencialidad de un documento. ### Perfiles y controles MHDS cierra sus consideraciones de seguridad con la relación entre sus controles y los perfiles IHE que los aportan ([MHDS Vol. 1, §1:50.5.4](https://profiles.ihe.net/ITI/MHDS/volume-1.html#15054-ihe-security-and-privacy-controls)). La [Tabla 2.6-3](volume-1-security.html#tabla-2-6-3) hace lo mismo para HIX. **Tabla 2.6-3:** Relación entre controles y perfiles o especificaciones | Control | Perfil o especificación que lo aporta | | --- | --- | | Autenticación de sistemas | ATNA | | Autorización y scope | IUA, OAuth 2.0 | | Delegación acotada y mínimo privilegio | RFC 8693, RFC 8707 | | Validación local del token mediado | RFC 9068 | | Introspección de tokens | IUA, RFC 7662 | | Autorización con participación de la persona | SMART App Launch, OpenID Connect | | Confidencialidad en tránsito | ATNA | | Relojes sincronizados | CT | | Auditoría | ATNA, BALP | | Identidad del paciente | PMIR, PIXm, PDQm | | Localización de endpoints | mCSD | | Divulgación controlada | Opción de Consentimiento, y PCF cuando se especifique | ### Referencias Las citas reproducen el texto publicado por su fuente. Los recortes se marcan con "[...]" y la negrita es de esta guía. [^mhds-security]: [MHDS Vol. 1, §1:50.5 MHDS Security Considerations](https://profiles.ihe.net/ITI/MHDS/volume-1.html#1505-mhds-security-considerations): "It is especially important for the reader to understand that **the scope of an IHE profile is only the technical details necessary to ensure interoperability**. It is up to any organization building a community to understand and carefully implement the policies of that community and to perform the appropriate risk analysis. [...] **The policy landscape that the community is built on needs to be defined well before the community is built.**" [^mhds-policy]: [MHDS Vol. 1, §1:50.5.1 Policies and Risk Management](https://profiles.ihe.net/ITI/MHDS/volume-1.html#15051-policies-and-risk-management): "IHE solves interoperability problems via the implementation of technology standards. **It does not define Privacy or Security Policies**, Risk Management, Healthcare Application Functionality, Operating System Functionality, Physical Controls, or even general Network Controls." [^mhds-emergency]: [MHDS Vol. 1, §1:50.5.1 Policies and Risk Management](https://profiles.ihe.net/ITI/MHDS/volume-1.html#15051-policies-and-risk-management): "An important set of policies are those around emergency modes. [...] **When these use cases are factored in up-front, the mitigations are reasonable.** [...] Need to override a patient specified privacy block due to eminent danger to that patient – **this override is not a breaking of the policy but would need to be an explicit condition within the policy.**" [^mhds-doctypes]: [MHDS Vol. 1, §1:50.5.3.2 Protecting different types of documents](https://profiles.ihe.net/ITI/MHDS/volume-1.html#150532-protecting-different-types-of-documents): "This differentiation of the types of data can be represented using a diagram like found in Table 50.5.3.2-1: Sample Access Control Policies, showing an ‘X’ where the defined Role (rows) would have permitted access to data tagged with the given (columns) ConfidentialityCode (U-Unrestricted, L-Low, M-Moderate, N-Normal, R-Restricted, V-Very Restricted). [...] **These roles would be conveyed from the requesting organization through the use of the Internet User Authorization (IUA) Profile.** [...] Additional information can be carried such as the PurposeOfUse, what the user intends to use the data for. Note that **Privacy Policies and Access Control rules can leverage any of the user context, patient identity, or document metadata** discussed above." [^fhir-seclabels]: [FHIR R5, Security Labels](https://hl7.org/fhir/R5/security-labels.html): "Local agreements and implementation profiles for the use security labels should describe how the security labels connect to the relevant consent and policy statements, and in particular: [...] **What to do if a resource has an unrecognized security label on it** [...]" [^rfc7519-aud]: [RFC 7519, §4.1.3 "aud" (Audience) Claim](https://www.rfc-editor.org/rfc/rfc7519.html#section-4.1.3): "**In the general case, the "aud" value is an array of case-sensitive strings**, each containing a StringOrURI value. In the special case when the JWT has one audience, the "aud" value MAY be a single case-sensitive string containing a StringOrURI value." [^rfc9068-aud]: [RFC 9068, §3 Requesting a JWT Access Token](https://www.rfc-editor.org/rfc/rfc9068.html#section-3): "If the request includes a "resource" parameter (as defined in [RFC8707]), **the resulting JWT access token "aud" claim SHOULD have the same value as the "resource" parameter in the request.**" [^rfc9068-validate]: [RFC 9068, §4 Validating JWT Access Tokens](https://www.rfc-editor.org/rfc/rfc9068.html#section-4): "Resource servers receiving a JWT access token MUST validate it in the following manner. The resource server MUST verify that the "typ" header value is "at+jwt" or "application/at+jwt" and reject tokens carrying any other value. [...] The issuer identifier for the authorization server [...] MUST exactly match the value of the "iss" claim. The resource server MUST validate that **the "aud" claim contains a resource indicator value corresponding to an identifier the resource server expects for itself**. [...] The resource server MUST validate the signature of all incoming JWT access tokens according to [RFC7515] using the algorithm specified in the JWT "alg" Header Parameter. **The resource server MUST reject any JWT in which the value of "alg" is "none".** The resource server MUST use the keys provided by the authorization server. The current time MUST be before the time represented by the "exp" claim." [^rfc8693-act]: [RFC 8693, §4.1 "act" (Actor) Claim](https://www.rfc-editor.org/rfc/rfc8693.html#section-4.1): "The act (actor) claim provides a means within a JWT to express that **delegation has occurred and identify the acting party to whom authority has been delegated**." [^rfc7662-active]: [RFC 7662, §2.2 Introspection Response](https://www.rfc-editor.org/rfc/rfc7662.html#section-2.2): "active. REQUIRED. **Boolean indicator of whether or not the presented token is currently active.** [...] a "true" value return for the "active" property will generally indicate that a given token has been issued by this authorization server, **has not been revoked by the resource owner**, and is within its given time window of validity". [^btg]: [v3-ActReason, BTG](https://terminology.hl7.org/CodeSystem-v3-ActReason.html#v3-ActReason-BTG): "break the glass. **To perform policy override operations on information for provision of immediately needed health care for an emergent condition** affecting potential harm, death or patient safety **by end users who are not provisioned for this purpose of use**. Includes override of organizational provisioning policies and may include override of subject of care consent directive restricting access." [ETREAT](https://terminology.hl7.org/CodeSystem-v3-ActReason.html#v3-ActReason-ETREAT): "Emergency Treatment. To perform one or more operations on information for provision of **immediately needed health care for an emergent condition**." [^balp-jti]: [BALP, §3:5.7.5.4 oAuth mapping to AuditEvent](https://profiles.ihe.net/ITI/BALP/content.html#35754-oauth-mapping-to-auditevent): "oAuth field \| Comprehensive AuditEvent \| Minimal AuditEvent [...] **jti (JWT ID) \| agent[user].policy \| agent[user].policy**" [^balp-token]: [BALP, §3:5.7.5 OAuth Security Token](https://profiles.ihe.net/ITI/BALP/content.html#3575-oauth-security-token): "There is still a need to include some evidence in the AuditEvent to tie this audit log entry with a specific token, but **the whole token should not be recorded for security reasons**." [^iua-sub]: [IUA, §3.71.4.2.2.1 JSON Web Token Option](https://profiles.ihe.net/ITI/IUA/index.html#3714221-json-web-token-option): "sub (required): **If known, unique identifier of the user; the client_id otherwise** [JWT, Section 4.1]. client_id (required): identifier of the client for which the token is issued." Y en §3.71.4.2.2.1.1 JWT IUA extension: "The Authorization Server and Resource Server shall support the following extensions to the JWT access token: **subject_name** (optional): The user's name as String. **subject_organization_id** (optional): Unique identifier of the user's organization. [...] **subject_role** (optional): Coded values indicating the user's roles. [...] **purpose_of_use** (optional): Purpose of use for the request. [...] The above claims shall be wrapped in an "extensions" object with key 'ihe_iua'". # Volumen 2. Transacciones El [Volumen 1](volume-1.html) fija la arquitectura de HIX, es decir, qué actores tiene la comunidad, qué hace cada uno y por qué. Este volumen entra en el detalle de las transacciones entre esos actores. De cada una dice qué lleva la petición, qué se responde, cuándo se rechaza y qué se registra. Cuando una regla ya está en el Volumen 1, aquí se enlaza en lugar de repetirla. Solo dos transacciones se especifican completas, [Mediated Token Exchange \[HIX-1\]](volume-2-hix-1.html) y [Patient Application Launch \[HIX-2\]](volume-2-hix-2.html), porque son propias de HIX y ningún perfil las define. Las demás vienen de perfiles IHE, y HIX las usa tal como las definen. De ellas este volumen solo dice con qué restricciones las usa la comunidad y lo muestra con ejemplos. Lo que este volumen no dice se aplica tal como lo publican IHE y OAuth 2.0. ## Cómo leer este volumen - **[Autorización](volume-2-authorization.html)** dice con qué restricciones usa HIX ITI-71 e ITI-102, con los que el Authorization Server emite y comprueba los tokens. - **[Mediated Token Exchange \[HIX-1\]](volume-2-hix-1.html)** especifica completo el intercambio con el que el Record Locator Service obtiene un token para cada destino. - **[Patient Application Launch \[HIX-2\]](volume-2-hix-2.html)** especifica completo el lanzamiento con el que la aplicación del paciente obtiene su token. - **[Identidad del paciente](volume-2-identity.html)** dice con qué restricciones usa HIX ITI-93, ITI-104, ITI-83, ITI-78 e ITI-119. - **[Publicación](volume-2-publication.html)** dice con qué restricciones usa HIX ITI-65. - **[Localización y recuperación](volume-2-retrieval.html)** dice con qué restricciones usa HIX ITI-66, ITI-67, ITI-68 e ITI-90. Cada página abre con lo que comparten sus transacciones. Después dedica una sección a cada transacción IHE, siempre con los mismos cuatro apartados y en el orden en que una transacción IHE presenta su alcance, sus mensajes y su auditoría. 1. **Alcance en HIX.** Quién inicia la transacción y quién la responde, en términos de actores HIX. 2. **Petición.** Los parámetros y elementos que HIX fija, con enlace a la sección exacta del perfil. 3. **Respuesta y rechazos.** Las condiciones de rechazo que HIX aplica, cada una con su motivo. 4. **Auditoría.** Una remisión a la [Tabla 3-2](volume-2.html#tabla-3-2), salvo que HIX añada algo. HIX-1 y HIX-2 no siguen esa plantilla abreviada sino la completa de IHE, desde el alcance y los roles de actor hasta las consideraciones de seguridad y la auditoría. ## Reglas comunes Las reglas de esta sección se aplican a varias transacciones. Provienen del Volumen 1, salvo la regla sobre respuestas FHIR, que se establece aquí. ### Peticiones a un Resource Server El Resource Server **SHALL** rechazar la petición que no cumpla estas reglas. 1. Lleva un token conforme a ITI-72 cuya audiencia incluye a ese Resource Server, según la [sección 2.2](volume-1-actors.html#descripcion-de-actores-y-requisitos). 2. El scope del token incluye el identificador de la transacción IHE, por ejemplo `ITI-67`. Esto también se aplica al token de una aplicación del paciente, según la [sección 2.6](volume-1-security.html#modelo-de-confianza). 3. El Resource Server toma del token la organización, el propósito de uso y, si corresponde, el contexto de paciente del solicitante. No los toma de la petición, como establece la [sección 2.2](volume-1-actors.html#record-locator-service). El Authorization Server fija la organización desde su propio registro y solo emite propósitos de uso que su registro admite, según sus [requisitos](volume-1-actors.html#authorization-server). ### Respuestas de error FHIR Todo actor que rechaza una transacción FHIR **SHALL** incluir un OperationOutcome en la respuesta, junto con el status code del error. ### Identificador de correlación El Record Locator Service genera el identificador de correlación y lo envía al custodio en el header `X-Request-Id`, como detalla [Localización y recuperación](volume-2-retrieval.html#iti-68). No reenvía un identificador propuesto por el solicitante, según la [sección 2.6](volume-1-security.html#seguridad-basica). ### Registros de auditoría Ningún registro de auditoría contiene un token completo ni contenido clínico, según la [sección 2.6](volume-1-security.html#seguridad-basica). ## Índice de transacciones La [Tabla 3-1](volume-2.html#tabla-3-1) reúne las veinte transacciones de HIX, agrupadas por la página que las especifica. De cada una dice el perfil que la define, qué actor la inicia y cuál la responde, y su nombre enlaza a su especificación. Las del último grupo HIX las usa sin restricciones propias, y por eso su nombre enlaza a IHE. La tabla incluye las transacciones de las Tablas [2.2-1](volume-1-actors.html#tabla-2-2-1) y [2.2-2](volume-1-actors.html#tabla-2-2-2) y las que traen consigo las agrupaciones de la [Tabla 2.4-2](volume-1-groupings.html#tabla-2-4-2). **Tabla 3-1:** Transacciones de HIX | Transacción | Perfil | Inicia | Responde | | --- | --- | --- | --- | | **Tokens y autorización** | | | | | [Get Access Token \[ITI-71\]](volume-2-authorization.html#iti-71) | IUA | Custodio, consumidor, fuente autoritativa de identidad, Record Locator Service, para su token de actor y, si la comunidad lo autoriza, para un token propio hacia los actores centrales, el Document Registry, para sus consultas ITI-83 e ITI-90, y el propio Authorization Server para su consulta ITI-83 | Authorization Server | | [Introspect Token \[ITI-102\]](volume-2-authorization.html#iti-102) | IUA | Record Locator Service, Document Registry, Master Patient Index y directorio de la comunidad, y el custodio cuando la comunidad admite la introspección | Authorization Server | | [Mediated Token Exchange \[HIX-1\]](volume-2-hix-1.html) | HIX | Record Locator Service | Authorization Server | | [Patient Application Launch \[HIX-2\]](volume-2-hix-2.html) | HIX | Aplicación del paciente | Authorization Server | | [Incorporate Access Token \[ITI-72\]](volume-2.html#peticiones-a-un-resource-server) | IUA | Todo Authorization Client, es decir, los miembros, la aplicación del paciente, la fuente autoritativa de identidad, el Record Locator Service, el Document Registry en sus consultas ITI-83 e ITI-90 y el Authorization Server en su consulta ITI-83 | Todo Resource Server, es decir, el Record Locator Service, el custodio, el Document Registry, el Master Patient Index y el directorio de la comunidad | | **Identidad del paciente** | | | | | [Mobile Patient Identity Feed \[ITI-93\]](volume-2-identity.html#iti-93) | PMIR | Fuente autoritativa de identidad, y el Master Patient Index hacia el Document Registry | Master Patient Index y Document Registry | | [Patient Identity Feed FHIR \[ITI-104\]](volume-2-identity.html#iti-104) | PIXm | Custodio | Master Patient Index | | [Mobile Patient Identifier Cross-reference Query \[ITI-83\]](volume-2-identity.html#iti-83) | PIXm | Consumidor, Document Registry y Authorization Server, y opcionalmente el custodio | Master Patient Index | | [Mobile Patient Demographics Query \[ITI-78\]](volume-2-identity.html#iti-78) | PDQm | Consumidor | Master Patient Index | | [Patient Demographics Match \[ITI-119\]](volume-2-identity.html#iti-119) | PDQm | Consumidor | Master Patient Index | | **Publicación** | | | | | [Provide Document Bundle \[ITI-65\]](volume-2-publication.html#iti-65) | MHD | Custodio | Document Registry | | **Localización y recuperación** | | | | | [Find Document Lists \[ITI-66\]](volume-2-retrieval.html#iti-66) | MHD | Consumidor y aplicación del paciente, y el Record Locator Service hacia el Document Registry | Record Locator Service y Document Registry | | [Find Document References \[ITI-67\]](volume-2-retrieval.html#iti-67) | MHD | Consumidor y aplicación del paciente, y el Record Locator Service hacia el Document Registry | Record Locator Service y Document Registry | | [Retrieve Document \[ITI-68\]](volume-2-retrieval.html#iti-68) | MHD | Consumidor y aplicación del paciente, y el Record Locator Service hacia el custodio o, bajo la Opción de Almacenamiento Central, el Document Registry | Record Locator Service y custodio, o el Document Registry bajo la Opción de Almacenamiento Central | | [Find Matching Care Services \[ITI-90\]](volume-2-retrieval.html#iti-90) | mCSD | Record Locator Service y Document Registry | Directorio de la comunidad | | **Auditoría** | | | | | [Record Audit Event \[ITI-20\]](volume-2.html#auditoria) | ATNA | Todo actor salvo la aplicación del paciente | El Audit Record Repository de la comunidad, o el del propio miembro | | **Sin restricciones de HIX** | | | | | [Subscribe to Patient Updates \[ITI-94\]](https://profiles.ihe.net/ITI/PMIR/ITI-94.html) | PMIR | Patient Identity Subscriber, que puede ser el Document Registry o la operación de la comunidad | Master Patient Index | | [Get Authorization Server Metadata \[ITI-103\]](https://profiles.ihe.net/ITI/IUA/index.html#3103-get-authorization-server-metadata-iti-103) | IUA | Todo Authorization Client y todo Resource Server | Authorization Server | | [Maintain Time \[ITI-1\]](https://profiles.ihe.net/ITI/TF/Volume2/ITI-1.html#3.1) | CT | Todo actor salvo la aplicación del paciente | Time Server que designa la comunidad | | [Authenticate Node \[ITI-19\]](https://profiles.ihe.net/ITI/TF/Volume2/ITI-19.html#3.19) | ATNA | Todo actor salvo la aplicación del paciente, al abrir una conexión | El actor con el que se conecta | El scope de cada transacción es su identificador, como fija la regla 2 para las [peticiones a un Resource Server](volume-2.html#peticiones-a-un-resource-server). [HIX-2](volume-2-hix-2.html) pide además `openid`, `fhirUser`, `launch/patient` y, para renovar el token, `offline_access`. ITI-71, HIX-1, HIX-2, ITI-72, ITI-102, ITI-103, ITI-20, ITI-1 e ITI-19 no tienen scope propio. ITI-71, HIX-1 y HIX-2 son las que piden los scopes, ITI-72 la que los transporta, y las demás forman parte de la infraestructura de seguridad de la comunidad. En HIX-1, el Record Locator Service pide el scope de la transacción que va a realizar ante el destino. ## Auditoría Todo actor de HIX, salvo la aplicación del paciente, registra sus eventos como recursos AuditEvent con Record Audit Event [ITI-20], como fija la [sección 2.4](volume-1-groupings.html#lo-que-casi-todos-agrupan). Los actores centrales los envían al Audit Record Repository de la comunidad y cada miembro registra los de su lado. Este volumen especifica ITI-20 aquí, una sola vez, para todas las transacciones. ITI-20 se usa bajo la opción ATX: FHIR Feed. Un evento suelto viaja con la interacción Send Audit Resource Request, que es un `create` de FHIR, y varios juntos con Send Audit Bundle Request, que es un `batch` ([RESTful ATNA, §3.20.4.2 y §3.20.4.4](https://www.ihe.net/uploadedFiles/Documents/ITI/IHE_ITI_Suppl_RESTful-ATNA.pdf))[^atna-feed]. HIX la usa sin parámetros ni condiciones de rechazo propios. Lo que HIX fija es el contenido de los eventos, con las reglas comunes del [identificador de correlación](volume-2.html#identificador-de-correlacion) y de los [registros de auditoría](volume-2.html#registros-de-auditoria). El contenido de cada evento es el que el perfil de la transacción define en su sección de auditoría. La mayoría de los perfiles lo construye sobre los patrones de BALP para las interacciones REST de FHIR, que son Create, Read, Update, Delete y Query, cada uno con una variante para cuando hay un paciente identificado ([BALP, §3:5.7.3](https://profiles.ihe.net/ITI/BALP/content.html#3573-restful-activities))[^balp-rest]. La [Tabla 3-2](volume-2.html#tabla-3-2) dice qué evento corresponde a cada transacción y quién lo registra. **Tabla 3-2:** Eventos de auditoría por transacción | Transacción | Patrón BALP | Quién registra | | --- | --- | --- | | ITI-71 | Ninguno. IUA define su propio evento, User Authentication con el subtipo ITI-71 ([IUA, §3.71.5.1](https://profiles.ihe.net/ITI/IUA/index.html#37151-security-audit-considerations))[^iua-audit] | El Authorization Server y el cliente que pide el token | | ITI-72 | Ninguno propio. El Resource Server registra la identidad del token en el evento de la transacción que lo lleva ([IUA, §3.72.5.1](https://profiles.ihe.net/ITI/IUA/index.html#37251-security-audit-considerations))[^iua-audit], y en un AuditEvent la añade con uno de los patrones OAuth Security Token de BALP ([BALP, §3:5.7.5](https://profiles.ihe.net/ITI/BALP/content.html#3575-oauth-security-token))[^balp-token] | El cliente y el Resource Server | | ITI-102 | Ninguno propio. El Resource Server usa el resultado de la introspección como atributos del evento ([IUA, §3.102.5.1](https://profiles.ihe.net/ITI/IUA/index.html#310251-security-audit-considerations))[^iua-audit] | El Record Locator Service, y el Document Registry, el Master Patient Index y el custodio cuando la usan | | HIX-1 | IHE no define ningún evento para un intercambio de tokens. Lo especifica [Mediated Token Exchange \[HIX-1\]](volume-2-hix-1.html#consideraciones-de-auditoria) | El Authorization Server | | HIX-2 | El evento de ITI-71 ([IUA, §3.71.5.1](https://profiles.ihe.net/ITI/IUA/index.html#37151-security-audit-considerations))[^iua-audit]. Lo detalla [Patient Application Launch \[HIX-2\]](volume-2-hix-2.html#consideraciones-de-auditoria) | El Authorization Server | | ITI-93 | Ninguno. PMIR define su propio evento, un Patient Record de ITI-20 que registran igual quien lo envía y quien lo recibe ([PMIR, §2:3.93.5.1](https://profiles.ihe.net/ITI/PMIR/ITI-93.html#239351-security-audit-considerations))[^pmir-audit] | La fuente autoritativa de identidad, el Master Patient Index y el Document Registry | | ITI-104 | PatientUpdate en el custodio, que no distingue un alta de una actualización, y PatientCreate o PatientUpdate en el Master Patient Index, que sí los distingue ([PIXm, §2:3.104.5.1](https://profiles.ihe.net/ITI/PIXm/ITI-104.html#2310451-security-audit-considerations))[^pixm-audit] | El custodio y el Master Patient Index | | ITI-83 | PatientQuery ([PIXm, §2:3.83.5.1](https://profiles.ihe.net/ITI/PIXm/ITI-83.html#238351-security-audit-considerations))[^pixm-audit] | Quien consulta y el Master Patient Index | | ITI-78 | Query ([PDQm, §2:3.78.5.1](https://profiles.ihe.net/ITI/PDQm/ITI-78.html#237851-security-audit-considerations))[^pdqm-audit] | El consumidor y el Master Patient Index | | ITI-119 | Query ([PDQm, §2:3.119.5.1](https://profiles.ihe.net/ITI/PDQm/ITI-119.html#2311951-security-audit-considerations))[^pdqm-audit] | El consumidor y el Master Patient Index | | ITI-65 | Ninguno. MHD define su propio evento, con criterios similares a los de ITI-41 ([MHD, §2:3.65.5.1](https://profiles.ihe.net/ITI/MHD/5.0.0/ITI-65.html#236551-security-audit-considerations))[^mhd-audit] | El custodio y el Document Registry | | ITI-66 | PatientQuery, en la versión que publica MHD ([MHD, §2:3.66.5.1](https://profiles.ihe.net/ITI/MHD/5.0.0/ITI-66.html#236651-security-audit-considerations))[^mhd-audit] | El consumidor, el Record Locator Service en sus dos papeles y el Document Registry | | ITI-67 | PatientQuery, en la versión que publica MHD ([MHD, §2:3.67.5.1](https://profiles.ihe.net/ITI/MHD/5.0.0/ITI-67.html#236751-security-audit-considerations))[^mhd-audit] | El consumidor, el Record Locator Service en sus dos papeles y el Document Registry | | ITI-68 | PatientRead, en la versión que publica MHD ([MHD, §2:3.68.5.1](https://profiles.ihe.net/ITI/MHD/5.0.0/ITI-68.html#236851-security-audit-considerations))[^mhd-audit] | El consumidor, el Record Locator Service en sus dos papeles y el custodio, o el Document Registry bajo la Opción de Almacenamiento Central | | ITI-90 | Query o Read, según la interacción ([mCSD, §2:3.90.5.1](https://profiles.ihe.net/ITI/mCSD/ITI-90.html#239051-security-audit-considerations))[^mcsd-audit] | El Record Locator Service, el Document Registry y el directorio de la comunidad | El Record Locator Service registra la solicitud que recibe y cada recuperación que origina hacia un custodio, bajo un mismo identificador de correlación, como fija la [sección 2.6](volume-1-security.html#seguridad-basica). En ITI-66, ITI-67 e ITI-68 la tabla le da dos papeles, porque MHD pide registrar tanto al Document Responder, que es su papel ante el solicitante, como al Document Consumer, que es su papel ante el Document Registry o el custodio ([MHD, §2:3.67.5.1.1 y §2:3.67.5.1.2](https://profiles.ihe.net/ITI/MHD/5.0.0/ITI-67.html#2367511-document-consumer-audit))[^mhd-roles]. La aplicación del paciente no registra eventos. Su actividad la registran el Authorization Server al lanzarla y el Record Locator Service en cada consulta, como dice la [sección 2.4](volume-1-groupings.html#lo-que-casi-todos-agrupan). ITI-103, ITI-1 e ITI-19 no tienen fila, porque su especificación no define un evento propio. Los eventos generales de seguridad, como un fallo de autenticación de un nodo, son los de la tabla de ITI-20 que todo Secure Node o Secure Application debe poder registrar ([ITI TF-2, §3.20.4.1.1.1](https://profiles.ihe.net/ITI/TF/Volume2/ITI-20.html#3.20.4.1.1.1))[^iti20-triggers]. ## Referencias Las citas reproducen el texto publicado por su fuente. Los recortes se marcan con "[...]" y la negrita es de esta guía. [^atna-feed]: [RESTful ATNA (Query and Feed), Rev. 3.6, §3.20.4.2 Send Audit Resource Request Message – FHIR Feed Interaction](https://www.ihe.net/uploadedFiles/Documents/ITI/IHE_ITI_Suppl_RESTful-ATNA.pdf): "A Secure Node, Secure Application or Audit Record Forwarder, that supports the ATX: FHIR Feed Option, uses this message to **post a single AuditEvent Resource** to the Audit Record Repository **using a FHIR create interaction** [...]". §3.20.4.4 Send Audit Bundle Request Message – FHIR Feed Interaction: "A Secure Node, Secure Application or Audit Record Forwarder that supports the ATX: FHIR Feed Option uses this message to **post a Bundle of AuditEvent Resources** to the Audit Record Repository **using a FHIR batch interaction** [...]" [^balp-rest]: [BALP, §3:5.7.3 RESTful activities](https://profiles.ihe.net/ITI/BALP/content.html#3573-restful-activities): "When a FHIR RESTful interaction happens, **the following AuditEvent patterns can be used**. [...] There are two sets of profiles distinguished by **Patient as a subject** being mandated to be populated." La tabla de esa sección nombra los patrones Create, Read, Update, Delete y Query, y sus variantes PatientCreate, PatientRead, PatientUpdate, PatientDelete y PatientQuery. [^iua-audit]: [IUA, §3.71.5.1 Security Audit Considerations](https://profiles.ihe.net/ITI/IUA/index.html#37151-security-audit-considerations): "The Authorization Client or Authorization Server that is grouped with an ATNA Secure Node or Secure Application **shall be able to send an audit event as defined below** [...] EventID [...] **EV(110114, DCM, "User Authentication")** [...] EventTypeCode [...] **EV("ITI-71", IHE, "User Authorization")**". [§3.72.5.1 Security Audit Considerations](https://profiles.ihe.net/ITI/IUA/index.html#37251-security-audit-considerations): "When an ATNA Audit message needs to be generated by the Resource Server and the user is authenticated by way of a JWT Token, **the ATNA Audit message UserName element shall record the JWT Token information** [...]". [§3.102.5.1 Security Audit Considerations](https://profiles.ihe.net/ITI/IUA/index.html#310251-security-audit-considerations): "**Resource Servers shall use the introspection results as authorization claims when formulating audit messages**, as specified in ITI TF-2 3.72.5.1." [^balp-token]: [BALP, §3:5.7.5 OAuth Security Token](https://profiles.ihe.net/ITI/BALP/content.html#3575-oauth-security-token): "**There are three patterns defined: opaque, minimal, and comprehensive.** [...] The profiling AuditEvent defined here is **the AuditEvent that the Client and Server would record when using IUA with the ITI TF-2: 3.72 Incorporate Access Token [ITI-72]** to secure some RESTful transaction." [^pmir-audit]: [PMIR, §2:3.93.5.1 Security Audit Considerations](https://profiles.ihe.net/ITI/PMIR/ITI-93.html#239351-security-audit-considerations): "The Mobile Patient Identity Feed transaction is **a Patient Record Message event** as defined in ITI TF-2: 3.20.4.1.1.1-1. **Note that the same audit message is recorded by both Supplier and Consumer.** The difference being the Audit Source element. [...] The actors involved shall record audit events according to the Audit Event for Mobile Patient Identity Feed by the Supplier and Consumer." Ese perfil, [IHE.PMIR.Feed.Audit](https://profiles.ihe.net/ITI/PMIR/StructureDefinition-IHE.PMIR.Feed.Audit.html), deriva directamente de AuditEvent y no de un patrón de BALP. [^pixm-audit]: [PIXm, §2:3.104.5.1 Security Audit Considerations](https://profiles.ihe.net/ITI/PIXm/ITI-104.html#2310451-security-audit-considerations): "The Security audit logging will conform to the RESTful interactions following **IHE-BALP Basic Audit Logging Patterns**." §2:3.104.5.1.1 Patient Identity Source Audit: "The Patient Identity Source **can't distinguish a Create from a Update**" y "The Patient Identity Source **will log a Delete or Update**". §2:3.104.5.1.2 Patient Identifier Cross-reference Manager Audit: "The Patient Identifier Cross-Reference Manager can distinguish a Create and Update so **is expected to record Create and Update specifically**." [§2:3.83.5.1 Security Audit Considerations](https://profiles.ihe.net/ITI/PIXm/ITI-83.html#238351-security-audit-considerations) dice lo mismo para ITI-83, y su perfil [IHE.PIXm.Query.Audit.Manager](https://profiles.ihe.net/ITI/PIXm/StructureDefinition-IHE.PIXm.Query.Audit.Manager.html) dice "**Build off of the IHE BasicAudit Patient Query event**". [^pdqm-audit]: [PDQm, §2:3.78.5.1 Security Audit Considerations](https://profiles.ihe.net/ITI/PDQm/ITI-78.html#237851-security-audit-considerations): "The Mobile Patient Demographics Query Transaction is **a Query Information event** as defined in Table 3.20.4.1.1.1-1. **The actors involved SHALL record audit events** according to the following". [§2:3.119.5.1](https://profiles.ihe.net/ITI/PDQm/ITI-119.html#2311951-security-audit-considerations) dice lo mismo para ITI-119. Sus perfiles, como [IHE.PDQm.Query.Audit.Supplier](https://profiles.ihe.net/ITI/PDQm/StructureDefinition-IHE.PDQm.Query.Audit.Supplier.html), dicen "**Build off of the IHE BasicAudit Query event**". [^mhd-audit]: [MHD, §2:3.65.5.1 Security Audit Considerations](https://profiles.ihe.net/ITI/MHD/5.0.0/ITI-65.html#236551-security-audit-considerations): "**The security audit criteria are similar to those for the Provide and Register Document Set-b [ITI-41] transaction** as this transaction does export a document." Sus perfiles, como [IHE.MHD.ProvideBundle.Audit.Recipient](https://profiles.ihe.net/ITI/MHD/5.0.0/StructureDefinition-IHE.MHD.ProvideBundle.Audit.Recipient.html), derivan directamente de AuditEvent. Para ITI-67, el perfil [IHE.MHD.FindDocumentReferences.Audit.Responder](https://profiles.ihe.net/ITI/MHD/5.0.0/StructureDefinition-IHE.MHD.FindDocumentReferences.Audit.Responder.html) dice "**Build off of the IHE BasicAudit PatientQuery event**", como los de ITI-66, y para ITI-68 [IHE.MHD.RetrieveDocument.Audit.Responder](https://profiles.ihe.net/ITI/MHD/5.0.0/StructureDefinition-IHE.MHD.RetrieveDocument.Audit.Responder.html) dice "**Build off of the IHE BasicAudit PatientRead event**". MHD 5.0.0 publica esos patrones en su propio paquete, sobre FHIR R5. [^mhd-roles]: [MHD, §2:3.67.5.1.1 Document Consumer Audit](https://profiles.ihe.net/ITI/MHD/5.0.0/ITI-67.html#2367511-document-consumer-audit): "**The Document Consumer when grouped with ATNA Secure Node or Secure Application Actor shall be able to record** a Find Document References Consumer Audit Event Log." [§2:3.67.5.1.2 Document Responder Audit](https://profiles.ihe.net/ITI/MHD/5.0.0/ITI-67.html#2367512-document-responder-audit): "**The Document Responder when grouped with ATNA Secure Node or Secure Application Actor shall be able to record** a Find Document References Responder Audit Event Log." Las secciones [§2:3.66.5.1](https://profiles.ihe.net/ITI/MHD/5.0.0/ITI-66.html#236651-security-audit-considerations) y [§2:3.68.5.1](https://profiles.ihe.net/ITI/MHD/5.0.0/ITI-68.html#236851-security-audit-considerations) dicen lo mismo para ITI-66 e ITI-68. [^mcsd-audit]: [mCSD, §2:3.90.5.1 Security Audit Considerations](https://profiles.ihe.net/ITI/mCSD/ITI-90.html#239051-security-audit-considerations): "Note that when grouped with ATNA Secure Node or Secure Application Actor, **the same audit message is recorded by both Directory and Query Client**. [...] the actors involved shall be able to record audit events according to the **Audit Event for Find Matching Care Services for Read** by the Directory and Query Client or the **Audit Event for Find Matching Care Services for Query** by the Directory and Query Client." Esos perfiles derivan de los patrones Read y Query de BALP. [^iti20-triggers]: [ITI TF-2, §3.20.4.1.1.1 DICOM and IHE Audit Event messages](https://profiles.ihe.net/ITI/TF/Volume2/ITI-20.html#3.20.4.1.1.1): "An actor in any IHE profile, when grouped with a Secure Node or Secure Application, **shall be able to report the relevant events defined in Table 3.20.4.1.1.1-1** (previously Table 3.20.6-1). This table of auditable events is not exhaustive. **Additional reportable events are often identified for specific events in other IHE profiles**, and are documented in that profile or transaction." La tabla incluye "Node-Authentication-failure", "A secure node authentication failure has occurred during TLS negotiation, e.g., invalid certificate." ## Autorización Get Access Token [ITI-71] e Introspect Token [ITI-102] son las transacciones de IUA con las que el Authorization Server emite y comprueba los tokens. HIX las usa tal como las definen IUA y OAuth 2.0, y estas son las restricciones con que las usa. 1. El `resource` es obligatorio y nombra a la infraestructura central, o al Authorization Server en el token de actor de [HIX-1](volume-2-hix-1.html), nunca a un custodio. 2. El token de un miembro lleva siempre la organización y el propósito de uso que fija el Authorization Server. 3. El Record Locator Service introspecciona cada token una vez por operación. Cada sección detalla estas restricciones y los rechazos que traen consigo. La [Tabla 2.6-1](volume-1-security.html#tabla-2-6-1) resume qué lleva cada token de HIX y cómo se valida. ### Get Access Token [ITI-71] #### Alcance en HIX Con ITI-71 y el grant Client Credentials obtienen sus tokens los miembros, la fuente autoritativa de identidad, el Record Locator Service, para su token de actor de [HIX-1](volume-2-hix-1.html) y, si la comunidad lo autoriza, para un token propio hacia los actores centrales, el Document Registry, para sus consultas ITI-83 e ITI-90, y el Authorization Server, para su propia consulta ITI-83. La aplicación del paciente obtiene el suyo con [HIX-2](volume-2-hix-2.html), y el token mediado sale de [HIX-1](volume-2-hix-1.html). #### Petición La petición es la de [IUA](https://profiles.ihe.net/ITI/IUA/index.html#3714121-client-credential-grant-type). HIX exige el parámetro `resource` que define RFC 8707 ([RFC 8707, §2](https://www.rfc-editor.org/rfc/rfc8707.html#section-2))[^rfc8707-resource], para limitar dónde se puede usar un access token. En el token de un miembro, el `resource` nombra a la infraestructura central, así que el token vale solo ante sus Resource Servers y nunca ante un custodio ni ante otro Resource Server fuera de ella. **Ejemplo.** Un laboratorio quiere declarar a un paciente local y publicar un resultado de laboratorio. Para ello pide al Authorization Server, con el grant `client_credentials`, un token para la infraestructura central con los scopes `ITI-104` e `ITI-65`. ```http POST /token HTTP/1.1 Authorization: Basic Base64(:) Content-Type: application/x-www-form-urlencoded grant_type=client_credentials &resource= &scope=ITI-104+ITI-65 ``` El Authorization Server pone en `aud` la lista de Resource Servers centrales que la comunidad define para ese `resource`, como prevé IUA, que limita esa lista a los Resource Servers esenciales para interactuar con el `resource`, normalmente solo el propio Resource Server ([IUA, §3.71.4.1.3](https://profiles.ihe.net/ITI/IUA/index.html#371413-expected-actions))[^iua-71-actions]. En HIX el `resource` nombra a la infraestructura central, y los esenciales son los Resource Servers centrales que la atienden. Cuáles son depende del [despliegue](volume-1-groupings.html#sobre-los-despliegues), y el miembro pide el token de la misma forma en todos los casos. El token puede ser opaco o un JWT, a elección de la implementación. Si es un JWT, sigue [RFC 9068](https://www.rfc-editor.org/rfc/rfc9068.html#section-2), y un Resource Server central distinto del Record Locator Service puede validarlo por sí mismo con las claves del Authorization Server, como permite la [sección 2.2](volume-1-actors.html#descripcion-de-actores-y-requisitos). Ese Resource Server no ve entonces una revocación hasta que el token expira. El Record Locator Service, que introspecciona siempre, la ve en la operación siguiente. > **Nota.** RFC 9068 recomienda que el `aud` de un JWT tenga el mismo valor que el `resource`, pero no lo exige ([RFC 9068, §3](https://www.rfc-editor.org/rfc/rfc9068.html#section-3))[^rfc9068-aud]. HIX sigue en esto a IUA, que prevé una lista de Resource Servers para un único `resource`. Lo que RFC 9068 sí exige es que la autorización del token no sea ambigua, y en HIX no lo es, porque cada scope es una transacción que atiende un único Resource Server. La organización y el propósito de uso los fija el Authorization Server desde su registro, como dice la regla 3 para las [peticiones a un Resource Server](volume-2.html#peticiones-a-un-resource-server). Cómo indica el solicitante que necesita un propósito de emergencia lo decide la comunidad, porque IUA no define ningún mecanismo para ello. El Authorization Server solo lo emite si su registro lo admite para ese cliente, como fija la [sección 2.6](volume-1-security.html#acceso-de-emergencia). #### Respuesta y rechazos La respuesta es la definida en [IUA](https://profiles.ihe.net/ITI/IUA/index.html#371422-message-semantics). El token de un miembro incluye siempre las [extensiones de IUA](https://profiles.ihe.net/ITI/IUA/index.html#3714221-json-web-token-option) `subject_organization_id` y `purpose_of_use`, con los valores que el Authorization Server obtiene de su registro, como establece la [sección 2.2](volume-1-actors.html#authorization-server). El token de una persona lleva `purpose_of_use` y el contexto de paciente, y `subject_organization_id` solo si la aplicación tiene una organización registrada, como fija [HIX-2](volume-2-hix-2.html), y el token de actor del Record Locator Service no lleva ninguna de las dos. Además de las validaciones que define IUA, el Authorization Server **SHALL** rechazar la petición en los casos de la [Tabla 3.1-1](volume-2-authorization.html#tabla-3-1-1). Responde con la [respuesta de error de OAuth 2.0](https://www.rfc-editor.org/rfc/rfc6749.html#section-5.2) y el código de error que indica la tabla, definido en [RFC 8707](https://www.rfc-editor.org/rfc/rfc8707.html#section-2) o en RFC 6749. **Tabla 3.1-1:** Rechazos que HIX aplica a ITI-71 | Condición | Error | | --- | --- | | La petición no lleva `resource`, lleva más de uno o nombra uno que el Authorization Server no tiene registrado | `invalid_target` | | El `resource` nombra a un custodio | `invalid_target`, igual que ante un `resource` no registrado | | El scope pide una transacción que el registro del Authorization Server no concede a ese cliente | `invalid_scope` | | El scope pide `launch/patient`, que solo admite la autorización de una persona en [HIX-2](volume-2-hix-2.html) | `invalid_scope` | | El cliente está deshabilitado | `invalid_client`, con el código HTTP 401 | > **Nota.** Un `resource` que nombra a un custodio recibe la misma respuesta que uno no registrado. Así nadie puede usar el Authorization Server para averiguar qué custodios hay en la comunidad. #### Auditoría La petición se registra con el evento que IUA define para ITI-71, según la [Tabla 3-2](volume-2.html#tabla-3-2). ### Introspect Token [ITI-102] #### Alcance en HIX Con ITI-102 comprueban el token del solicitante los actores centrales que lo reciben directamente. El Record Locator Service lo hace siempre. Los demás, como el Document Registry o el Master Patient Index cuando atienden directamente a los miembros, pueden en cambio validarlo por sí mismos si es un JWT, como fija la [sección 2.2](volume-1-actors.html#descripcion-de-actores-y-requisitos). Un custodio también puede introspeccionar el token mediado, además de validarlo con las claves del Authorization Server, si la comunidad lo admite, como fija la [sección 2.6](volume-1-security.html#validacion-en-el-custodio). #### Petición La petición es la de [IUA](https://profiles.ihe.net/ITI/IUA/index.html#3102412-message-semantics), y quien pregunta se identifica con las credenciales que acuerda con el Authorization Server ([IUA, §3.102.5](https://profiles.ihe.net/ITI/IUA/index.html#31025-security-considerations))[^iua-102-security]. El Record Locator Service introspecciona el token en cada operación que atiende y no reutiliza el resultado en operaciones posteriores, como exige la [sección 2.2](volume-1-actors.html#record-locator-service). Así, en cuanto el Authorization Server revoca un token, el Record Locator Service lo rechaza desde la operación siguiente. > **Nota.** IUA permite cachear el resultado de una introspección hasta el `exp` que trae ([IUA, §3.102.4.2.3](https://profiles.ihe.net/ITI/IUA/index.html#3102423-expected-actions))[^iua-102-rs]. HIX lo desaconseja, porque un resultado `active=true` cacheado sigue aceptando un token que ya fue revocado. Por esta razón, la [sección 2.2](volume-1-actors.html#descripcion-de-actores-y-requisitos) fija que quien introspecciona **SHOULD NOT** reutilizar el resultado en operaciones posteriores. #### Respuesta y rechazos La respuesta es la de [IUA](https://profiles.ihe.net/ITI/IUA/index.html#3102422-message-semantics). Solo pueden introspeccionar los actores centrales y, si la comunidad lo admite, los custodios. A cualquier otro el Authorization Server le responde con el código HTTP 401, como prevé IUA para quien no tiene acceso al introspection endpoint ([IUA, §3.102.4.1.3](https://profiles.ihe.net/ITI/IUA/index.html#3102413-expected-actions))[^iua-102-actions]. En el token de una persona, la respuesta lleva además `patient`, como fija [HIX-2](volume-2-hix-2.html). De la respuesta, el Resource Server toma la organización, el propósito de uso y, si lo hay, el contexto de paciente, y comprueba `aud` y `scope`, como fijan las reglas 1 a 3 para las [peticiones a un Resource Server](volume-2.html#peticiones-a-un-resource-server). Si el token está inactivo o no cumple esas reglas, rechaza la petición con el código HTTP 401, como pide IUA ([IUA, §3.72.4.3](https://profiles.ihe.net/ITI/IUA/index.html#37243-expected-actions))[^iua-72-actions], y con el OperationOutcome que exigen las [respuestas de error FHIR](volume-2.html#respuestas-de-error-fhir). Si el Authorization Server no responde, rechaza la petición con el código HTTP 503, porque no tiene cómo comprobar el token, como fija la [sección 2.2](volume-1-actors.html#descripcion-de-actores-y-requisitos). **Ejemplo.** Con el token del ejemplo anterior, el laboratorio publica el resultado. Al recibir la publicación, el Document Registry introspecciona el token ante el Authorization Server con sus propias credenciales. En este despliegue el Document Registry y el Master Patient Index atienden directamente a los miembros, así que `aud` nombra a los tres. La extensión `ihe_iua` lleva la organización y el propósito de uso del laboratorio. ```http POST /introspect HTTP/1.1 Authorization: Basic Base64(:) Accept: application/json Content-Type: application/x-www-form-urlencoded token= ``` ```http HTTP/1.1 200 OK Content-Type: application/json { "active": true, "iss": "", "sub": "", "client_id": "", "aud": [ "", "", "" ], "jti": "", "iat": 1790204262, "exp": 1790204562, "scope": "ITI-104 ITI-65", "token_type": "Bearer", "extensions": { "ihe_iua": { "subject_organization_id": "", "purpose_of_use": [ { "system": "http://terminology.hl7.org/CodeSystem/v3-ActReason", "code": "TREAT", "display": "treatment" } ] } } } ``` #### Auditoría La introspección no tiene evento propio. Quien la usa registra su resultado en el evento de la transacción que atiende, según la [Tabla 3-2](volume-2.html#tabla-3-2). ### Referencias Las citas reproducen el texto publicado por su fuente. Los recortes se marcan con "[...]" y la negrita es de esta guía. [^rfc8707-resource]: [RFC 8707, §2 Resource Parameter](https://www.rfc-editor.org/rfc/rfc8707.html#section-2): "**resource Indicates the target service or resource to which access is being requested.** Its value MUST be an absolute URI [...] The parameter can carry the location of a protected resource, typically as an https URL or **a more abstract identifier**." [^rfc9068-aud]: [RFC 9068, §3 Requesting a JWT Access Token](https://www.rfc-editor.org/rfc/rfc9068.html#section-3): "If the request includes a "resource" parameter (as defined in [RFC8707]), **the resulting JWT access token "aud" claim SHOULD have the same value as the "resource" parameter in the request.** [...] **The authorization server MUST NOT issue a JWT access token if the authorization granted by the token would be ambiguous.**" [^iua-71-actions]: [IUA, §3.71.4.1.3 Expected Actions](https://profiles.ihe.net/ITI/IUA/index.html#371413-expected-actions): "**The Authorization Client is recommended to provide a resource value** to limit usability of the requested token to the intended Resource Server. [...] If the Authorization Client presented a resource value in the token request, **the Authorization Server shall limit the list of Resource Server identifiers in the audience claim to only those that are essential to interact with the specified resource** (typically only the Resource Server itself)." [^iua-72-actions]: [IUA, §3.72.4.3 Expected Actions](https://profiles.ihe.net/ITI/IUA/index.html#37243-expected-actions): "If the token includes a scope claim, **the Resource Server shall verify that the scope covers the transaction to the requested resource** [OAuth 2.1, Section 7]. If the token includes an audience claim, **the Resource Server shall verify that the audience includes the Resource Server itself** [OAuth 2.1, Section 7]. [...] **If the token verification, or scope matching, or the access policy enforcement fails, the Resource Server shall respond with a HTTP 401 (Unauthorized) error.**" [^iua-102-security]: [IUA, §3.102.5 Security Considerations](https://profiles.ihe.net/ITI/IUA/index.html#31025-security-considerations): "The Resource Server shall securely identify itself towards the Authorization Server by using credentials agreed between the Authorization Server and Resource Server. **At minimum, the Authorization Server and Resource Server shall support the use of Bearer tokens for Resource Server authentication** as defined in [OAuth2.1, Section 7.2]. **To obtain a bearer token, the Resource Server may request such a token from the Authorization Server, reusing the client credential grant flow** as described in the Get Access Token [ITI-71] transaction [...]". [^iua-102-rs]: [IUA, §3.102.4.2.3 Expected Actions](https://profiles.ihe.net/ITI/IUA/index.html#3102423-expected-actions): "**If the active field is set to "false", the Resource Server shall return HTTP 401 (Not Authorized) for all requests carrying the introspected access token. The Resource Server shall use the introspection results as access token claims in all access control evaluations** [...] The Resource Server may cache introspection results for a given access token in case the introspection result contains an expiry field. **This cache shall not extend the period as defined by the expiry field.**" [^iua-102-actions]: [IUA, §3.102.4.1.3 Expected Actions](https://profiles.ihe.net/ITI/IUA/index.html#3102413-expected-actions): "Upon receiving the introspect request, the Authorization Server shall evaluate the Resource Server's access to the introspect endpoint. **If access is not allowed, the Authorization Server shall return HTTP 401 (Not Authorized).** The Authorization Server shall: [...] Validate the active state of the token (e.g., check expiry or revocation). **Evaluate configured access policies, taking into account the authorization claims related to the token and the Resource Server identity.** [...] **If the one of the above checks fails the Authorization Server shall return an introspection response with the "active" field set to "false"** as described in RFC7662, Section 2.2." ## Mediated Token Exchange [HIX-1] Mediated Token Exchange [HIX-1] es la transacción con la que el Record Locator Service obtiene un token para llamar, en nombre de un solicitante, a un custodio y, según el despliegue, a otro Resource Server central, como fija la [sección 2.2](volume-1-actors.html#record-locator-service). Ningún perfil IHE define esta transacción, y esta página la especifica. ### Alcance El token que el Record Locator Service obtiene del Authorization Server con HIX-1 es el [token mediado](appendix-glossary.html#token-mediado), que vale ante el destino que nombra su `resource`, nunca ante dos custodios, y para un solo tipo de transacción. Lo necesita porque el [token del solicitante](appendix-glossary.html#token-del-solicitante) nunca sale de la infraestructura central, como fija la [sección 2.6](volume-1-security.html#modelo-de-confianza). La [Figura 3.2-1](volume-2-hix-1.html#figura-3-2-1) muestra qué token se presenta en cada llamada de una recuperación y ante qué destino vale. También muestra que el token del solicitante no sale de la infraestructura central. ![Recorrido de los tokens en una recuperación](hix-2-hix-1-recorrido.svg) **Figura 3.2-1:** Recorrido de los tokens en una recuperación Solo el Record Locator Service puede solicitar HIX-1. ### Roles de actor La [Tabla 3.2-1](volume-2-hix-1.html#tabla-3-2-1) muestra el rol de IUA de cada actor de HIX en esta transacción, según la [sección 2.4](volume-1-groupings.html). **Tabla 3.2-1:** Roles de actor | Actor | Rol | Qué hace | | --- | --- | --- | | Record Locator Service | [Authorization Client](https://profiles.ihe.net/ITI/IUA/index.html#34111-authorization-client) | Pide, en nombre de un solicitante, un token para un destino y un solo tipo de transacción | | Authorization Server | [Authorization Server](https://profiles.ihe.net/ITI/IUA/index.html#34112-authorization-server) | Valida los tokens de la petición y emite el token mediado | ### Estándares referenciados HIX-1 se apoya en los documentos siguientes. - [RFC 6749](https://www.rfc-editor.org/rfc/rfc6749), The OAuth 2.0 Authorization Framework, octubre de 2012. Aporta el token endpoint, la autenticación del cliente y la respuesta de error. - [RFC 8693](https://www.rfc-editor.org/rfc/rfc8693), OAuth 2.0 Token Exchange, enero de 2020. Aporta el grant de intercambio, sus parámetros y el claim `act`. - [RFC 8707](https://www.rfc-editor.org/rfc/rfc8707), Resource Indicators for OAuth 2.0, febrero de 2020. Aporta el parámetro `resource` y el error `invalid_target`. - [RFC 9068](https://www.rfc-editor.org/rfc/rfc9068), JSON Web Token (JWT) Profile for OAuth 2.0 Access Tokens, octubre de 2021. Aporta la forma del token mediado y su validación en el destino. - [RFC 7519](https://www.rfc-editor.org/rfc/rfc7519), JSON Web Token (JWT), mayo de 2015. Aporta los claims del token, entre ellos `aud` y `jti`. - [IUA](https://profiles.ihe.net/ITI/IUA/index.html), Internet User Authorization, revisión 2.5, junio de 2026. Aporta ITI-71, con el que el Record Locator Service obtiene su token de actor, ITI-72, con el que presenta el token mediado, y las extensiones `ihe_iua` que el token mediado copia del token del solicitante. > **Nota.** HIX-1 se apoya en ITI-71. El Record Locator Service obtiene con ITI-71 su token de actor, y el intercambio usa el mismo token endpoint del Authorization Server con otro grant. IUA limita [ITI-71](https://profiles.ihe.net/ITI/IUA/index.html#371-get-access-token-iti-71) a los grants Authorization Code y Client Credentials, y de RFC 8693 solo toma el parámetro `requested_token_type` ([IUA, §3.71.4.1.2.1](https://profiles.ihe.net/ITI/IUA/index.html#3714121-client-credential-grant-type)). Admite que sus actores soporten otros grants ([IUA, §34.4.1.1](https://profiles.ihe.net/ITI/IUA/index.html#34411-authorization-grant-types))[^iua-grants], y HIX-1 especifica uno de ellos, el grant Token Exchange de RFC 8693 con un resource indicator de RFC 8707. ### Mensajes La [Figura 3.2-2](volume-2-hix-1.html#figura-3-2-2) muestra los mensajes de la transacción. Los dos primeros corresponden a [ITI-71](volume-2-authorization.html#iti-71): el Record Locator Service usa el grant Client Credentials para obtener su token de actor si no tiene uno vigente. Los dos últimos corresponden a HIX-1. ![Mediated Token Exchange](hix-2-hix-1.svg) **Figura 3.2-2:** Mediated Token Exchange #### Petición de intercambio ##### Evento desencadenante Para llamar a un custodio, el Record Locator Service obtiene un token mediado mediante HIX-1. Para llamar a un actor central desplegado como un sistema distinto lo obtiene también, salvo que la comunidad autorice un token propio, como fija la [sección 2.2](volume-1-actors.html#record-locator-service). Para obtener el token mediado, presenta al Authorization Server su token de actor y el token del solicitante. Las llamadas internas a un mismo sistema no pasan por HIX-1, como fija la [sección 2.2](volume-1-actors.html#record-locator-service). Si el destino es un custodio, primero aplica la decisión de divulgación: un puntero cuya divulgación se niega no origina ningún intercambio, como fija la [sección 2.2](volume-1-actors.html#record-locator-service). En todos los casos, comprueba antes el token del solicitante con ITI-102. ##### Semántica del mensaje La petición sigue RFC 8693: un POST al token endpoint del Authorization Server con los parámetros en el body, codificados como `application/x-www-form-urlencoded` ([RFC 8693, §2.1](https://www.rfc-editor.org/rfc/rfc8693.html#section-2.1))[^rfc8693-request]. > **Nota.** RFC 8693 define `actor_token` como opcional en una solicitud general de Token Exchange ([§2.1](https://www.rfc-editor.org/rfc/rfc8693.html#section-2.1))[^rfc8693-request]. HIX-1 lo requiere porque usa semántica de delegación, en la que `subject_token` representa al solicitante y `actor_token` al Record Locator Service, que actúa en su nombre ([§1.1](https://www.rfc-editor.org/rfc/rfc8693.html#section-1.1))[^rfc8693-delegation]. Una petición que solo lleva `subject_token` no expresa delegación ([Apéndice A.1.1](https://www.rfc-editor.org/rfc/rfc8693.html#section-a.1.1))[^rfc8693-impersonation]. Además, separa las dos identidades en juego. La autenticación del cliente prueba quién llama al token endpoint, y el `actor_token` aporta el actor de la delegación que queda en el token mediado. **Tabla 3.2-2:** Parámetros de la petición de intercambio | Parámetro | Valor en HIX | | --- | --- | | `grant_type` | `urn:ietf:params:oauth:grant-type:token-exchange` | | `subject_token` | El token del solicitante, tal como llegó en la petición que el Record Locator Service atiende | | `subject_token_type` | `urn:ietf:params:oauth:token-type:access_token` | | `actor_token` | El token de actor, es decir, el token propio del Record Locator Service. Lo obtiene con [ITI-71](volume-2-authorization.html#iti-71) y el grant Client Credentials, con el Authorization Server como `resource` y sin `scope`, porque solo lo presenta ante él. Puede reutilizarlo mientras esté vigente y lo renueva antes de que venza | | `actor_token_type` | `urn:ietf:params:oauth:token-type:access_token` | | `resource` | Uno solo. Para un custodio, el endpoint que publica el directorio de la comunidad. Para un actor central, el identificador que la comunidad registra para él en el Authorization Server y que ese actor espera en `aud`. Nunca uno que llegue en la petición del solicitante o en un puntero | | `scope` | Solo el identificador de la transacción que el Record Locator Service va a realizar, por ejemplo `ITI-68` ante un custodio, `ITI-67` ante el Document Registry o `ITI-90` ante el directorio de la comunidad | | `requested_token_type` | Opcional. Si se envía, `urn:ietf:params:oauth:token-type:access_token` | El Record Locator Service se autentica en el token endpoint como cliente confidencial, con el método que acuerde con el Authorization Server ([RFC 6749, §2.3](https://www.rfc-editor.org/rfc/rfc6749.html#section-2.3)). La petición no incluye la organización, el propósito de uso ni el contexto de paciente. Estos datos se propagan automáticamente desde el token del solicitante al token mediado, como fija la [sección 2.2](volume-1-actors.html#authorization-server). El `resource` sale del directorio porque el directorio es el único origen de los endpoints que usa la infraestructura central, como fija la [sección 2.2](volume-1-actors.html#directorio-de-la-comunidad). El Authorization Server restringe la audiencia del token a los Resource Servers que asocia a ese `resource`, y a ese único custodio cuando nombra a uno, como recomienda RFC 8707 ([RFC 8707, §2](https://www.rfc-editor.org/rfc/rfc8707.html#section-2)). La petición no lleva `audience`. RFC 8693 lo trataría como otro destino, y el token emitido sería válido en todos los destinos indicados ([RFC 8693, §2.1](https://www.rfc-editor.org/rfc/rfc8693.html#section-2.1) y [§2.1.1](https://www.rfc-editor.org/rfc/rfc8693.html#section-2.1.1))[^rfc8707-resource]. RFC 8693 distingue la delegación de la suplantación: en la delegación, quien actúa conserva su identidad y representa a otro. Aquí, `subject_token` representa al solicitante y `actor_token` al Record Locator Service ([RFC 8693, §1.1](https://www.rfc-editor.org/rfc/rfc8693.html#section-1.1)). El claim `act` del token mediado procede del `actor_token` e identifica al actor de la delegación ([RFC 8693, §4.1](https://www.rfc-editor.org/rfc/rfc8693.html#section-4.1))[^rfc8693-delegation]. El destino **SHOULD** comprobar ese claim, como recomienda la [sección 2.6](volume-1-security.html#validacion-en-el-custodio). ##### Acciones esperadas Además de validar cada token que recibe, como exige RFC 8693 ([RFC 8693, §2.1](https://www.rfc-editor.org/rfc/rfc8693.html#section-2.1))[^rfc8693-request], el Authorization Server **SHALL** comprobar lo siguiente. 1. Que el `subject_token` y el `actor_token` son access tokens vigentes que emitió él. 2. Que la audiencia del `subject_token` incluye al Record Locator Service, de modo que no se intercambie un token pensado para otro destino. 3. Que el `subject_token` no lleva `act`, es decir, que no es un token mediado. Un token mediado no se vuelve a intercambiar. 4. Que el `actor_token` identifica al Record Locator Service, coincide con el cliente autenticado y tiene como audiencia al Authorization Server. 5. Que hay un solo `resource`, registrado como destino y dentro de la delegación registrada para el Record Locator Service. 6. Que el scope identifica una sola transacción y está contenido en la delegación registrada para el Record Locator Service ante el destino. Además, que está contenido en el scope del `subject_token`, salvo cuando la transacción es ITI-90 y la delegación registrada la permite ante el directorio. Después emite el token mediado conforme a la [sección 2.2](volume-1-actors.html#authorization-server), que fija su audiencia, sujeto, extensiones, scope y vida. Si alguna comprobación falla, **SHALL** rechazar la petición como indica la [Tabla 3.2-3](volume-2-hix-1.html#tabla-3-2-3). La respuesta de error es la de OAuth 2.0, con el parámetro `error` y el código HTTP 400, salvo que la tabla indique otro. **Tabla 3.2-3:** Rechazos que HIX añade al intercambio | Condición | Error | Motivo | | --- | --- | --- | | Falta el `actor_token` | `invalid_request` | HIX expresa la delegación como la describe RFC 8693, con el `actor_token` en la petición y el claim `act` en el token resultante ([RFC 8693, §1.1](https://www.rfc-editor.org/rfc/rfc8693.html#section-1.1))[^rfc8693-delegation] | | El `actor_token` no identifica al Record Locator Service | `invalid_request` | El claim `act` sale del `actor_token`, y el destino comprueba que el actor es el Record Locator Service, como fija la [sección 2.6](volume-1-security.html#validacion-en-el-custodio) | | La petición no lleva exactamente un `resource`, o lleva `audience` | `invalid_target` | Un solo `resource` deja la audiencia en manos del Authorization Server, y `audience` añadiría destinos que él no controla, como explica la [sección 2.6](volume-1-security.html#modelo-de-confianza) | | El cliente autenticado no es el Record Locator Service | `unauthorized_client` | Solo el Record Locator Service puede pedir un token a nombre de otro, como fija la [sección 2.2](volume-1-actors.html#authorization-server) | | La autenticación del cliente falla | `invalid_client`, con el código HTTP 401 | RFC 6749 lo exige cuando el cliente se autentica con el header `Authorization`, como en el ejemplo, y lo admite en los demás casos ([RFC 6749, §5.2](https://www.rfc-editor.org/rfc/rfc6749.html#section-5.2))[^rfc8693-error] | | Un token es inválido o ha expirado, el `subject_token` no tiene al Record Locator Service en su audiencia o ya lleva `act`, o el `actor_token` no tiene al Authorization Server en su audiencia | `invalid_request` | RFC 8693 prevé ese código para un `subject_token` o un `actor_token` que no es válido o que la política no acepta ([RFC 8693, §2.2.2](https://www.rfc-editor.org/rfc/rfc8693.html#section-2.2.2))[^rfc8693-error] | | El `resource` no es un destino registrado o queda fuera de la delegación | `invalid_target` | RFC 8707 prevé ese código para un destino que el Authorization Server no acepta ([RFC 8707, §2](https://www.rfc-editor.org/rfc/rfc8707.html#section-2))[^rfc8707-resource] | | El scope está vacío, pide más de una transacción, pide un valor que no es una transacción, como `launch/patient`, no está contenido en la delegación registrada ante el destino, o no está contenido en el scope del solicitante y no es ITI-90 ante el directorio | `invalid_scope` | El token mediado autoriza una sola transacción y cumple los límites de scope de la [sección 2.2](volume-1-actors.html#authorization-server) | #### Respuesta de intercambio ##### Evento desencadenante El Authorization Server responde a cada petición de intercambio con un token mediado o con un error. ##### Semántica del mensaje El Authorization Server responde a un intercambio concedido con el código HTTP 200 y un body JSON con los parámetros de la respuesta de RFC 8693 ([RFC 8693, §2.2.1](https://www.rfc-editor.org/rfc/rfc8693.html#section-2.2.1))[^rfc8693-response]. La [Tabla 3.2-4](volume-2-hix-1.html#tabla-3-2-4) fija sus valores en HIX. **Tabla 3.2-4:** Parámetros de la respuesta de intercambio | Parámetro | Valor en HIX | | --- | --- | | `access_token` | El token mediado, un JWT de acceso conforme a RFC 9068 | | `issued_token_type` | `urn:ietf:params:oauth:token-type:access_token`, porque es un access token que el Record Locator Service no necesita leer | | `token_type` | `Bearer`, porque el Record Locator Service lo presenta con ITI-72 | | `expires_in` | La vida del token en segundos, que no supera los dos minutos ni la vida restante del token del solicitante, como fija la [sección 2.2](volume-1-actors.html#authorization-server) | | `scope` | Puede omitirse, porque el scope concedido es siempre el pedido, como fija la [sección 2.2](volume-1-actors.html#authorization-server) | | `refresh_token` | El Authorization Server **SHALL NOT** incluirlo. El token mediado no se renueva, y cada transacción pide el suyo | El contenido del token mediado se especifica en los requisitos del [Authorization Server](volume-1-actors.html#authorization-server) y lo resume la [Tabla 2.6-1](volume-1-security.html#tabla-2-6-1). El Authorization Server responde a un intercambio rechazado con la respuesta de error de OAuth 2.0 y el código indicado en la [Tabla 3.2-3](volume-2-hix-1.html#tabla-3-2-3). ##### Acciones esperadas El Record Locator Service **SHALL** presentar el token mediado mediante ITI-72 únicamente ante el destino indicado en `resource` y en la transacción para la que lo obtuvo, y **SHALL NOT** entregarlo al solicitante, como fija la [sección 2.6](volume-1-security.html#modelo-de-confianza). Si el intercambio se rechaza, el Record Locator Service **SHALL NOT** llamar al destino, ni con el token del solicitante ni con el token de actor, porque ninguno de los dos vale ante él. La [Tabla 3.6-3](volume-2-retrieval.html#tabla-3-6-3) fija cómo responde al solicitante si el rechazo ocurre durante una recuperación. #### Ejemplo El Record Locator Service pide un token para recuperar con ITI-68 un documento de un custodio. ```http POST /token HTTP/1.1 Authorization: Basic Base64(:) Content-Type: application/x-www-form-urlencoded grant_type=urn:ietf:params:oauth:grant-type:token-exchange &subject_token= &subject_token_type=urn:ietf:params:oauth:token-type:access_token &actor_token= &actor_token_type=urn:ietf:params:oauth:token-type:access_token &resource= &scope=ITI-68 ``` El Authorization Server concede el intercambio. El token mediado vive 120 segundos, el máximo que admite HIX, y la respuesta no lleva `refresh_token`. ```http HTTP/1.1 200 OK Content-Type: application/json Cache-Control: no-store Pragma: no-cache { "access_token": "", "issued_token_type": "urn:ietf:params:oauth:token-type:access_token", "token_type": "Bearer", "expires_in": 120, "scope": "ITI-68" } ``` El token mediado de la respuesta se decodifica así. Su `aud` es solo el endpoint del custodio, el mismo que la petición llevaba en `resource`. Su `sub` y sus extensiones de IUA son los del token del solicitante, y `client_id` y `act` nombran al Record Locator Service. `exp` queda 120 segundos después de `iat`. ```json { "alg": "RS256", "typ": "at+jwt", "kid": "" } ``` ```json { "iss": "", "aud": "", "sub": "", "client_id": "", "act": { "sub": "" }, "scope": "ITI-68", "iat": 1790788733, "exp": 1790788853, "jti": "", "extensions": { "ihe_iua": { "subject_organization_id": "", "purpose_of_use": [ { "system": "http://terminology.hl7.org/CodeSystem/v3-ActReason", "code": "TREAT", "display": "treatment" } ] } } } ``` Si el token del solicitante tiene contexto de paciente, el token mediado lo lleva en el claim `patient`, con el mismo valor que la respuesta de token de [HIX-2](volume-2-hix-2.html#respuesta-de-token). Si la petición llevara dos `resource`, el Authorization Server la rechazaría con el código HTTP 400 y el error `invalid_target`. ```http HTTP/1.1 400 Bad Request Content-Type: application/json Cache-Control: no-store { "error": "invalid_target" } ``` ### Consideraciones de seguridad La [sección 2.6](volume-1-security.html) fija cómo el destino [valida](volume-1-security.html#validacion-en-el-custodio) el token mediado, cómo se [contiene una credencial comprometida](volume-1-security.html#contencion-de-una-credencial-comprometida) y qué [riesgos quedan](volume-1-security.html#riesgos-residuales). De ellos, cuatro afectan directamente a esta transacción. 1. Un Record Locator Service comprometido solo puede intercambiar los tokens de solicitantes que recibe, mientras están vigentes y dentro de su scope, salvo ITI-90, que la delegación registrada le permite ante el directorio. 2. Un token mediado robado vale ante el destino que nombra su `resource`, nunca ante dos custodios, para un solo tipo de transacción y durante dos minutos como máximo. El Record Locator Service **SHALL** usar cada token mediado solo en la transacción para la que lo pidió, y el destino **MAY** rechazar un `jti` que ya vio. 3. El Authorization Server **SHALL NOT** revelar en `error_description` qué destinos existen ni el contenido de un token. 4. La vida máxima de dos minutos solo significa lo mismo en cada extremo si los relojes coinciden, y por eso cada actor es Time Client de CT, como fija la [sección 2.4](volume-1-groupings.html#lo-que-casi-todos-agrupan). #### Consideraciones de auditoría IHE no define ningún evento de auditoría para un intercambio de tokens. IUA solo define un evento de auditoría para la emisión de tokens en ITI-71 ([IUA, §3.71.5.1](https://profiles.ihe.net/ITI/IUA/index.html#37151-security-audit-considerations))[^iua-audit], y HIX-1 no es ITI-71. La obtención del token de actor sí es un ITI-71, y se registra como indica la [Tabla 3-2](volume-2.html#tabla-3-2). El Authorization Server **SHALL** registrar cada intercambio, concedido o rechazado. En ese registro **SHALL** enlazar, por su `jti`, el token del solicitante, el token de actor y, si lo emitió, el token mediado ([RFC 7519, §4.1.7](https://www.rfc-editor.org/rfc/rfc7519.html#section-4.1.7))[^jti]. Si rechazó el intercambio, enlaza los tokens de la petición que pueda identificar. El registro no contiene ningún token completo, como dice la regla común de los [registros de auditoría](volume-2.html#registros-de-auditoria). Ese enlace permite seguir una divulgación desde el token del solicitante hasta el token mediado. El destino también registra este último por su identificador, como fija la [sección 2.6](volume-1-security.html#seguridad-basica). > **Nota.** El `jti` identifica un token sin reproducirlo. Si el Authorization Server identifica un token opaco por su propio valor, el registro no guarda ese valor sino una evidencia derivada de él. BALP pide vincular el evento al token sin registrar el token completo ([BALP, §3:5.7.5](https://profiles.ihe.net/ITI/BALP/content.html#3575-oauth-security-token))[^balp-token]. ### Referencias Las citas reproducen el texto publicado por su fuente. Los recortes se marcan con "[...]" y la negrita es de esta guía. [^iua-grants]: [IUA, §34.1.1.1 Authorization Client](https://profiles.ihe.net/ITI/IUA/index.html#34111-authorization-client): "The Get Access Token [ITI-71] transaction **is scoped to the Authorization Code and Client Credential grant types** (see ITI TF-1: 34.4.1.1 Authorization Grant Types)." [§3.71.4.1.2.1 Client Credential grant type](https://profiles.ihe.net/ITI/IUA/index.html#3714121-client-credential-grant-type): "requested_token_type (optional): The requested token format shall be urn:ietf:params:oauth:token-type:jwt, urn:ietf:params:oauth:token-type:saml2 or urn:ietf:params:oauth:token-type:access-token [**RFC 8693 OAuth 2.0 Token Exchange**, Section 3]." [§34.4.1.1 Authorization Grant Types](https://profiles.ihe.net/ITI/IUA/index.html#34411-authorization-grant-types): "This profile specifies the use of the Authorization Code and Client Credential grant types. **Actors of this profile may support other grant types as well.**" [^rfc8693-request]: [RFC 8693, §2.1 Request](https://www.rfc-editor.org/rfc/rfc8693.html#section-2.1): "The following parameters are included in the HTTP request entity-body using the **"application/x-www-form-urlencoded" format** [...] grant_type REQUIRED. The value **"urn:ietf:params:oauth:grant-type:token-exchange"** indicates that a token exchange is being performed. [...] **Multiple "resource" parameters may be used** to indicate that the issued token is intended to be used at the multiple resources listed. [...] subject_token REQUIRED. A security token that represents the identity of the party on behalf of whom the request is being made. [...] **actor_token OPTIONAL.** A security token that represents the identity of the acting party. [...] In processing the request, **the authorization server MUST perform the appropriate validation procedures for the indicated token type** and, if the actor token is present, also perform the appropriate validation procedures for its indicated token type." [§3 Token Type Identifiers](https://www.rfc-editor.org/rfc/rfc8693.html#section-3): "urn:ietf:params:oauth:token-type:access_token Indicates that the token is **an OAuth 2.0 access token issued by the given authorization server**." [^rfc8707-resource]: [RFC 8707, §2 Resource Parameter](https://www.rfc-editor.org/rfc/rfc8707.html#section-2): "Its value **MUST be an absolute URI** [...] invalid_target The requested resource is invalid, missing, unknown, or malformed. **The authorization server SHOULD audience-restrict issued access tokens to the resource(s) indicated by the "resource" parameter.**" [RFC 8693, §2.1 Request](https://www.rfc-editor.org/rfc/rfc8693.html#section-2.1): "The "audience" and "resource" parameters may be used together **to indicate multiple target services** with a mix of logical names and resource URIs." [§2.1.1 Relationship between Resource, Audience, and Scope](https://www.rfc-editor.org/rfc/rfc8693.html#section-2.1.1): "The semantics of such a request are that the client is asking for a token with the requested scope that is **usable at all the requested target services**. [...] An authorization server can use the "invalid_target" error code, defined in Section 2.2.2, to inform a client that it requested access to too many target services simultaneously." [^rfc8693-delegation]: [RFC 8693, §1.1 Delegation vs. Impersonation Semantics](https://www.rfc-editor.org/rfc/rfc8693.html#section-1.1): "With delegation semantics, principal A still has its own identity separate from B, and it is explicitly understood that while B may have delegated some of its rights to A, **any actions taken are being taken by A representing B**. [...] Typically, in the request, the "subject_token" represents the identity of the party on behalf of whom the token is being requested while **the "actor_token" represents the identity of the party to whom the access rights of the issued token are being delegated**. [...] The "actor_token" request parameter, however, does provide a means for providing information about the desired actor, and **the JWT "act" claim can provide a representation of a chain of delegation**." [§4.1 "act" (Actor) Claim](https://www.rfc-editor.org/rfc/rfc8693.html#section-4.1): "The act (actor) claim provides a means within a JWT to express that **delegation has occurred and identify the acting party to whom authority has been delegated**." [^rfc8693-impersonation]: [RFC 8693, Appendix A.1.1 Token Exchange Request](https://www.rfc-editor.org/rfc/rfc8693.html#section-a.1.1): "In the following token exchange request, a client is requesting a token with impersonation semantics (**delegation is impossible with only a "subject_token" and no "actor_token"**)." [^rfc8693-error]: [RFC 8693, §2.2.2 Error Response](https://www.rfc-editor.org/rfc/rfc8693.html#section-2.2.2): "If the request itself is not valid or if either the "subject_token" or "actor_token" are invalid for any reason, or are unacceptable based on policy, the authorization server MUST construct an error response, as specified in Section 5.2 of [RFC6749]. **The value of the "error" parameter MUST be the "invalid_request" error code.** If the authorization server is unwilling or unable to issue a token for any target service indicated by the "resource" or "audience" parameters, **the "invalid_target" error code SHOULD be used** in the error response. [...] **Other error codes may also be used, as appropriate.**" [RFC 6749, §5.2 Error Response](https://www.rfc-editor.org/rfc/rfc6749.html#section-5.2): "The authorization server **responds with an HTTP 400 (Bad Request) status code (unless specified otherwise)** and includes the following parameters with the response: **error REQUIRED.** [...] **unauthorized_client** The authenticated client is not authorized to use this authorization grant type. [...] **invalid_scope** The requested scope is invalid, unknown, malformed, or exceeds the scope granted by the resource owner." Sobre invalid_client: "Client authentication failed [...] The authorization server MAY return an HTTP 401 (Unauthorized) status code to indicate which HTTP authentication schemes are supported. **If the client attempted to authenticate via the "Authorization" request header field, the authorization server MUST respond with an HTTP 401 (Unauthorized) status code** and include the "WWW-Authenticate" response header field matching the authentication scheme used by the client." [^rfc8693-response]: [RFC 8693, §2.2.1 Successful Response](https://www.rfc-editor.org/rfc/rfc8693.html#section-2.2.1): "scope **OPTIONAL if the scope of the issued security token is identical to the scope requested by the client**; otherwise, it is REQUIRED. refresh_token OPTIONAL. A refresh token will typically not be issued when the exchange is of one temporary credential (the subject_token) for a different temporary credential (the issued token) for use in some other context. [...] **Profiles or deployments of this specification should clearly document the conditions under which a client should expect a refresh token** [...]" [§3 Token Type Identifiers](https://www.rfc-editor.org/rfc/rfc8693.html#section-3): "The intent of this specification is that "urn:ietf:params:oauth:token-type:access_token" be an indicator that **the token is a typical OAuth access token issued by the authorization server in question, opaque to the client**, and usable the same manner as any other access token obtained from that authorization server." [^iua-audit]: [IUA, §3.71.5.1 Security Audit Considerations](https://profiles.ihe.net/ITI/IUA/index.html#37151-security-audit-considerations): "The Authorization Client or Authorization Server that is grouped with an ATNA Secure Node or Secure Application **shall be able to send an audit event as defined below** [...] EventID [...] EV(110114, DCM, "User Authentication") [...] EventTypeCode [...] **EV("ITI-71", IHE, "User Authorization")**". [^balp-token]: [BALP, §3:5.7.5 OAuth Security Token](https://profiles.ihe.net/ITI/BALP/content.html#3575-oauth-security-token): "There is still a need to include some evidence in the AuditEvent to tie this audit log entry with a specific token, but **the whole token should not be recorded for security reasons**." [^jti]: [RFC 7519, §4.1.7 "jti" (JWT ID) Claim](https://www.rfc-editor.org/rfc/rfc7519.html#section-4.1.7): "The "jti" (JWT ID) claim **provides a unique identifier for the JWT**." [RFC 9068, §2.2 Data Structure](https://www.rfc-editor.org/rfc/rfc9068.html#section-2.2): "**jti REQUIRED** - as defined in Section 4.1.7 of [RFC7519]." ## Patient Application Launch [HIX-2] Patient Application Launch [HIX-2] es la transacción con la que una aplicación elegida por una persona obtiene del Authorization Server un token destinado al Record Locator Service, cuyo contexto de paciente es la identidad maestra de esa persona. Ningún perfil IHE la define, y esta página la especifica. ### Alcance Con ese token, la aplicación localiza y recupera como cualquier consumidor, limitada a ese paciente, como describe el caso de [acceso del paciente a su expediente](volume-1-usecases.html#acceso-del-paciente-a-su-expediente). > **Nota.** El consentimiento del que habla esta página es el de OAuth 2.0, es decir, la aprobación con la que la persona permite a una aplicación actuar en su nombre ante el Record Locator Service. No debe confundirse con el consentimiento del paciente sobre la divulgación de sus documentos, que decide qué puede ver cada solicitante y que describe la [Opción de Consentimiento](volume-1-options.html#opcion-de-consentimiento). HIX-2 no registra ni modifica ese segundo consentimiento. HIX-2 es [ITI-71](https://profiles.ihe.net/ITI/IUA/index.html#371-get-access-token-iti-71) con el grant Authorization Code y PKCE (Proof Key for Code Exchange), más la renovación del token con el grant de refresh token. IUA limita ITI-71 a los grants Authorization Code y Client Credential, y admite que sus actores soporten otros, como el de refresh token ([IUA, §34.4.1.1](https://profiles.ihe.net/ITI/IUA/index.html#34411-authorization-grant-types))[^iua-grants]. Para el contexto de paciente, HIX-2 adopta determinados elementos de SMART App Launch, que IUA procura no contradecir ([IUA, Relation to SMART-on-FHIR](https://profiles.ihe.net/ITI/IUA/index.html#relation-to-smart-on-fhir))[^iua-smart]. Tiene identificador propio porque en ella el Authorization Server fija el contexto de paciente, algo que ITI-71 no prevé. HIX-2 aplica las reglas de [ITI-71](volume-2-authorization.html#iti-71) de la página de Autorización, con tres diferencias. El `resource` nombra al Record Locator Service y el `aud` del token solo lo nombra a él. El token lleva el propósito de uso y el contexto de paciente, y la organización solo si el registro del Authorization Server asocia una a la aplicación. Y la aplicación solo puede obtener los scopes de ITI-66, ITI-67 e ITI-68. #### Decisiones frente a IUA y SMART App Launch La [Tabla 3.3-1](volume-2-hix-2.html#tabla-3-3-1) reúne qué toma HIX-2 de IUA y de SMART App Launch y en qué se aparta de ellos. El resto de la página aplica estas decisiones sin repetirlas. **Tabla 3.3-1:** Decisiones de HIX-2 frente a IUA y SMART App Launch | Aspecto | IUA | SMART App Launch | HIX-2 | | --- | --- | --- | --- | | Lanzamiento | No lo define | EHR Launch o Standalone Launch[^smart-standalone] | Solo Standalone Launch, sin el parámetro `launch` | | Destino del token | `resource`, opcional y de un solo valor[^iua-code-request] | `aud`, obligatorio, con `resource` como sinónimo opcional[^smart-aud] | `resource`, obligatorio y único | | `redirect_uri` | Obligatorio solo si la aplicación tiene varias URI registradas[^iua-code-request] | Obligatorio[^smart-authorize] | Obligatorio | | PKCE | `code_challenge` obligatorio y método opcional[^iua-code-request] | Solo `S256`, nunca `plain`[^smart-pkce] | Solo `S256` | | Scopes | Uno por transacción de MHD, como `ITI-67`[^iua-mhd-scope] | De recurso, de contexto y de identidad[^smart-scopes] | Los identificadores de transacción, `launch/patient` y `fhirUser` de SMART, y `openid` y `offline_access` de OpenID Connect | | `patient` al renovar | No lo define | Opcional[^smart-refresh] | Obligatorio | | `fhirUser` en la introspección | No lo define | Recomendado[^smart-introspection] | No exigido | HIX exige `patient` en toda respuesta de token, también al renovar, para que la aplicación conozca siempre el contexto vigente. SMART lo deja opcional al renovar[^smart-refresh]. No exige `fhirUser` en la introspección, porque el Record Locator Service confina cada operación con `patient`. SMART App Launch pide el destino con un parámetro llamado `aud` y lo declara equivalente al `resource` de RFC 8707 ([SMART App Launch, Obtain authorization code](https://hl7.org/fhir/smart-app-launch/app-launch.html#obtain-authorization-code))[^smart-aud]. HIX usa `resource`, porque `aud` es el nombre del claim con el que el Authorization Server fija la audiencia del token, que no tiene por qué coincidir con lo que el cliente pidió. El Authorization Server **SHOULD NOT** aceptar el parámetro `aud` en lugar de `resource`. Si una comunidad decide aceptarlo, por ejemplo para admitir aplicaciones SMART ya existentes, el Authorization Server lo trata exactamente como un `resource`. > **Nota.** SMART App Launch exige a sus servidores aceptar el parámetro `aud` y deja `resource` como sinónimo opcional[^smart-aud]. RFC 8707 separa la intención de la restricción, porque el Authorization Server restringe la audiencia del token a partir del `resource`, la comunica en el claim `aud` y puede usar el mismo valor o derivar de él otro identificador ([RFC 8707, §2](https://www.rfc-editor.org/rfc/rfc8707.html#section-2))[^rfc8707-resource]. Por esta razón, HIX-2 se aparta en este punto de SMART App Launch. #### Descubrimiento del Authorization Server SMART App Launch pide que todo endpoint FHIR que exige autorización sirva en su URL base, bajo `/.well-known/smart-configuration`, un documento con los endpoints de autorización y las capacidades que admite ([SMART App Launch, Conformance](https://hl7.org/fhir/smart-app-launch/conformance.html#using-well-known))[^smart-well-known]. Es así como una aplicación SMART encuentra el Authorization Server a partir de la URL que va a consultar. **Experimental.** El Record Locator Service **SHALL** hacer disponible el documento `/.well-known/smart-configuration` en la URL base FHIR que expone a la aplicación del paciente, y el documento **SHALL** describir los endpoints y las capacidades del Authorization Server. Que lo sirva el propio Record Locator Service o lo redirija al Authorization Server lo decide la implementación. La [Tabla 3.3-2](volume-2-hix-2.html#tabla-3-3-2) dice qué declara HIX en él. **Tabla 3.3-2:** Contenido del documento `smart-configuration` | Campo | Valor en HIX | | --- | --- | | `issuer` y `jwks_uri` | Los del Authorization Server como OpenID Provider | | `authorization_endpoint` y `token_endpoint` | Los del Authorization Server | | `grant_types_supported` | `authorization_code` | | `code_challenge_methods_supported` | Solo `S256` | | `capabilities` | `launch-standalone`, `context-standalone-patient`, `sso-openid-connect`, `client-public`, `client-confidential-symmetric` y `permission-offline`. Ninguna de las capacidades de scopes de recurso, porque HIX no los usa | **Ejemplo.** La aplicación pide el documento a partir de la URL base FHIR del Record Locator Service. ```http GET /.well-known/smart-configuration HTTP/1.1 Accept: application/json ``` ```http HTTP/1.1 200 OK Content-Type: application/json { "issuer": "", "jwks_uri": "", "authorization_endpoint": "", "token_endpoint": "", "grant_types_supported": ["authorization_code"], "code_challenge_methods_supported": ["S256"], "capabilities": [ "launch-standalone", "context-standalone-patient", "sso-openid-connect", "client-public", "client-confidential-symmetric", "permission-offline" ] } ``` El Authorization Server sigue publicando sus metadatos de IUA con [ITI-103](https://profiles.ihe.net/ITI/IUA/index.html#3103-get-authorization-server-metadata-iti-103), y los dos documentos describen los mismos endpoints. ### Roles de actor La [Tabla 3.3-3](volume-2-hix-2.html#tabla-3-3-3) muestra los roles de los actores de HIX en la transacción, según la [sección 2.4](volume-1-groupings.html). **Tabla 3.3-3:** Roles de actor | Actor | Rol | Qué hace | | --- | --- | --- | | Aplicación del paciente | [Authorization Client](https://profiles.ihe.net/ITI/IUA/index.html#34111-authorization-client) | Pide, en nombre de la persona que la usa, un token para el Record Locator Service con el contexto de paciente | | Authorization Server | [Authorization Server](https://profiles.ihe.net/ITI/IUA/index.html#34112-authorization-server) y [OpenID Provider](appendix-glossary.html#openid-provider) | Autentica a la persona, obtiene su autorización, fija el contexto de paciente y emite los tokens | Durante el lanzamiento, el Authorization Server también actúa como [Patient Identifier Cross-reference Consumer](appendix-glossary.html#patient-identifier-cross-reference-consumer) de PIXm. Resuelve la identidad de la persona ante el Master Patient Index mediante ITI-83, con un token propio que obtiene con el grant Client Credentials, según la [sección 2.2](volume-1-actors.html#authorization-server). Esa consulta no forma parte de HIX-2. ### Estándares referenciados HIX-2 se apoya en los documentos siguientes. - [IUA](https://profiles.ihe.net/ITI/IUA/index.html), Internet User Authorization, revisión 2.5, junio de 2026. Aporta ITI-71 con el grant Authorization Code y su evento de auditoría. - [SMART App Launch](https://hl7.org/fhir/smart-app-launch/), versión 2.2.0, de 2024. Aporta el Standalone Launch, los scopes `launch/patient` y `fhirUser`, el parámetro `patient` y el claim `fhirUser`. - [OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html), con la fe de erratas 2, diciembre de 2023. Aporta la autenticación de la persona, el `id_token` y los scopes `openid` y `offline_access`. - [RFC 6749](https://www.rfc-editor.org/rfc/rfc6749), The OAuth 2.0 Authorization Framework, octubre de 2012. Aporta el grant de refresh token y las respuestas de error. - [RFC 7636](https://www.rfc-editor.org/rfc/rfc7636), Proof Key for Code Exchange by OAuth Public Clients, septiembre de 2015. Aporta `code_challenge`, `code_verifier` y el método `S256`. - [RFC 8707](https://www.rfc-editor.org/rfc/rfc8707), Resource Indicators for OAuth 2.0, febrero de 2020. Aporta el parámetro `resource` y el error `invalid_target`. - [RFC 9700](https://www.rfc-editor.org/rfc/rfc9700), Best Current Practice for OAuth 2.0 Security, enero de 2025. Aporta la protección de los refresh tokens de los clientes públicos. ### Mensajes La [Figura 3.3-1](volume-2-hix-2.html#figura-3-3-1) muestra los mensajes de la transacción. La petición de autorización y su respuesta pasan por el navegador de la persona. Las peticiones de token van directamente al token endpoint. La renovación solo ocurre si la aplicación obtuvo un refresh token. ![Patient Application Launch](hix-2-hix-2.svg) **Figura 3.3-1:** Patient Application Launch #### Petición de autorización ##### Evento desencadenante La aplicación inicia un lanzamiento cuando la persona la abre y no tiene un token vigente para el Record Locator Service ni un refresh token con el que renovarlo. También lo inicia cuando el Authorization Server rechaza una renovación con `invalid_grant`. Redirige el navegador al authorization endpoint, que descubre con el documento `smart-configuration` o con ITI-103, como explica el [descubrimiento del Authorization Server](volume-2-hix-2.html#descubrimiento). ##### Semántica del mensaje La petición es un GET al authorization endpoint, con los parámetros en la query, como define IUA para el grant Authorization Code ([IUA, §3.71.4.1.2.2](https://profiles.ihe.net/ITI/IUA/index.html#3714122-authorization-code-grant-type))[^iua-code-request]. La [Tabla 3.3-4](volume-2-hix-2.html#tabla-3-3-4) dice qué valor fija HIX en cada parámetro. **Tabla 3.3-4:** Parámetros de la petición de autorización | Parámetro | Valor en HIX | | --- | --- | | `response_type` | `code` | | `client_id` | El identificador con el que la aplicación está registrada en el Authorization Server | | `redirect_uri` | Una de las URI de redirección registradas para la aplicación. El Authorization Server **SHALL** compararla por coincidencia exacta, como exige RFC 9700 ([RFC 9700, §2.1](https://www.rfc-editor.org/rfc/rfc9700.html#section-2.1))[^rfc9700-redirect] | | `state` | Obligatorio, como exige IUA ([IUA, §3.71.4.1.2.2](https://profiles.ihe.net/ITI/IUA/index.html#3714122-authorization-code-grant-type))[^iua-state]. Un valor impredecible que la aplicación genera para cada petición | | `resource` | Uno solo, el identificador del Record Locator Service como Resource Server | | `code_challenge` | El reto que la aplicación deriva de su `code_verifier` | | `code_challenge_method` | `S256` | | `scope` | `openid`, `fhirUser`, `launch/patient` y los identificadores de las transacciones que la aplicación va a realizar, como `ITI-67` e `ITI-68`. Además, `offline_access` si la aplicación quiere un refresh token | Ninguno de los scopes de SMART ni de OpenID Connect autoriza operaciones ante el Record Locator Service. Lo que autoriza son los identificadores de transacción, según la regla 2 para las [peticiones a un Resource Server](volume-2.html#peticiones-a-un-resource-server). La aplicación pide solo los que necesita, como IUA exige a todo Authorization Client ([IUA, §3.71.5](https://profiles.ihe.net/ITI/IUA/index.html#3715-security-considerations))[^iua-security]. El Authorization Server **SHALL NOT** conceder a una aplicación del paciente identificadores de transacción distintos de `ITI-66`, `ITI-67` e `ITI-68`, porque la aplicación solo localiza y recupera los documentos de la persona. **Ejemplo.** La aplicación del paciente pide autorización para buscar y recuperar documentos, y un refresh token. ```http GET /authorize?response_type=code&client_id=&redirect_uri=&state=&resource=&code_challenge=&code_challenge_method=S256&scope=openid+fhirUser+launch/patient+offline_access+ITI-67+ITI-68 HTTP/1.1 ``` ##### Acciones esperadas El Authorization Server valida los parámetros, autentica a la persona y obtiene su autorización para la aplicación, como IUA exige antes de emitir el código ([IUA, §3.71.4.1.3.2](https://profiles.ihe.net/ITI/IUA/index.html#3714132-authorization-code-grant-type))[^iua-code-actions]. Cómo se verifica la identidad de la persona es política de la comunidad, según la [sección 2.6](volume-1-security.html#politicas-y-gestion-de-riesgo). Si la petición lleva `offline_access`, el Authorization Server **SHALL** obtener en cada lanzamiento el consentimiento de la persona para emitir el refresh token, sin reutilizar uno guardado. La aplicación no necesita enviar `prompt=consent`. > **Nota.** OpenID Connect exige al OpenID Provider obtener siempre el consentimiento antes de emitir un refresh token para el acceso sin conexión, y advierte que un consentimiento guardado no siempre basta. Para asegurarlo, la petición lleva `prompt=consent`, salvo que otras condiciones del procesamiento permitan el acceso sin conexión ([OpenID Connect Core, §11](https://openid.net/specs/openid-connect-core-1_0.html#OfflineAccess))[^oidc-offline]. En HIX esa condición es que el Authorization Server pide el consentimiento en cada lanzamiento y nunca reutiliza uno guardado, que es lo mismo que obtendría `prompt=consent`. Por esta razón, HIX-2 no exige a la aplicación enviar `prompt=consent`. Antes de emitir el código, el Authorization Server resuelve mediante ITI-83 la identidad verificada de la persona a su identidad maestra y la fija como contexto de paciente de la autorización, según sus requisitos de la [sección 2.2](volume-1-actors.html#authorization-server). Ese contexto vale para el canje del código y para todas las renovaciones de la misma autorización. El Authorization Server fija también el propósito de uso desde su propio registro, `PATRQT` cuando quien actúa es la propia persona, según la [Tabla 2.2-3](volume-1-actors.html#tabla-2-2-3). Nunca lo toma de la petición, según la regla 3 para las [peticiones a un Resource Server](volume-2.html#peticiones-a-un-resource-server). > **Nota.** HIX-2 no fija cómo actúa una persona en nombre de otra, como un familiar autorizado o un representante legal. Si una comunidad lo admite, define cómo se acredita esa relación, qué paciente queda como contexto y qué propósito de uso lleva el token, como `FAMRQT` o `PWATRNY`. #### Respuesta de autorización ##### Evento desencadenante El Authorization Server responde cuando concede la autorización o cuando la rechaza. ##### Semántica del mensaje Si concede la autorización, el Authorization Server redirige el navegador a la `redirect_uri` con `code` y `state`[^iua-code-request]. Si la rechaza, redirige con `error` y el `state` de la petición ([RFC 6749, §4.1.2.1](https://www.rfc-editor.org/rfc/rfc6749.html#section-4.1.2.1))[^rfc6749-authz-error]. Si la `redirect_uri` o el `client_id` faltan o no son válidos, el Authorization Server **SHALL NOT** redirigir el navegador y **SHOULD** informar del error a la persona, como exige RFC 6749[^rfc6749-authz-error]. El Authorization Server **SHALL** rechazar la petición en las condiciones de la [Tabla 3.3-5](volume-2-hix-2.html#tabla-3-3-5). Los códigos son los que prevén RFC 7636 para PKCE[^rfc7636-error], RFC 8707 para el recurso[^rfc8707-resource] y RFC 6749 para los demás[^rfc6749-authz-error]. **Tabla 3.3-5:** Rechazos en el authorization endpoint | Condición | Error | Motivo | | --- | --- | --- | | Falta `code_challenge`, o `code_challenge_method` no es `S256` | `invalid_request` | HIX admite solo `S256` | | La petición no lleva exactamente un `resource`, contando `aud` si la comunidad lo acepta, o ese valor no es el Record Locator Service | `invalid_target` | El token de la aplicación vale solo ante el Record Locator Service, como resume la [Tabla 2.6-1](volume-1-security.html#tabla-2-6-1) | | El scope pide una transacción distinta de `ITI-66`, `ITI-67` e `ITI-68` | `invalid_scope` | La aplicación del paciente solo localiza y recupera, como fija la [sección 2.4](volume-1-groupings.html#miembros) | | El scope pide transacciones sin `launch/patient` | `invalid_scope` | Un token con transacciones y sin contexto de paciente no quedaría confinado al expediente de la persona | | La identidad verificada de la persona no resuelve a una identidad maestra | `access_denied` | El Authorization Server no fija un contexto de paciente sin identidad maestra, como establece la [sección 2.2](volume-1-actors.html#authorization-server) | | El Master Patient Index no responde | `server_error` | Sin la identidad maestra no hay contexto que fijar. RFC 6749 reserva `temporarily_unavailable` para la sobrecarga o el mantenimiento del propio Authorization Server | **Ejemplo.** El Authorization Server rechaza un lanzamiento cuya identidad verificada no resuelve a una identidad maestra. ```http HTTP/1.1 302 Found Location: ?error=access_denied&state= ``` ##### Acciones esperadas La aplicación comprueba que `state` coincide con el valor que envió[^smart-authorize]. Si recibe el código, lo canjea en el token endpoint. Si recibe un error, no obtiene token. #### Petición de token ##### Evento desencadenante La aplicación envía la petición con el grant Authorization Code al recibir el código en la redirección. Usa el grant de refresh token cuando vence su token y conserva un refresh token vigente. ##### Semántica del mensaje La petición es un POST al token endpoint, con los parámetros en el body en formato `application/x-www-form-urlencoded`. El canje del código sigue IUA[^iua-code-request] y SMART App Launch ([SMART App Launch, Obtain access token](https://hl7.org/fhir/smart-app-launch/app-launch.html#obtain-access-token))[^smart-token]. La renovación sigue RFC 6749 ([RFC 6749, §6](https://www.rfc-editor.org/rfc/rfc6749.html#section-6))[^rfc6749-refresh] y SMART App Launch[^smart-refresh]. La [Tabla 3.3-6](volume-2-hix-2.html#tabla-3-3-6) dice qué valor fija HIX en cada parámetro de los dos grants. **Tabla 3.3-6:** Parámetros de la petición de token | Parámetro | Canje del código | Renovación | | --- | --- | --- | | `grant_type` | `authorization_code` | `refresh_token` | | `code` | El código recibido en la redirección | No se envía | | `redirect_uri` | La misma de la petición de autorización | No se envía | | `code_verifier` | El valor del que la aplicación derivó el `code_challenge` | No se envía | | `refresh_token` | No se envía | El último refresh token que recibió la aplicación | | `scope` | No se envía | Se omite, o pide una parte del scope concedido | | `client_id` | Lo envía la aplicación pública. La confidencial se autentica con su credencial[^iua-code-actions] | Igual que en el canje | SMART App Launch exige el `client_id` en el canje de una aplicación pública[^smart-token]. La aplicación pública **SHALL** enviarlo también al renovar, como admite RFC 6749 ([RFC 6749, §3.2.1](https://www.rfc-editor.org/rfc/rfc6749.html#section-3.2.1))[^rfc6749-client-id], para que el Authorization Server compruebe a qué aplicación emitió el refresh token. **Ejemplo.** Una aplicación pública canjea el código y, más tarde, renueva su token. ```http POST /token HTTP/1.1 Content-Type: application/x-www-form-urlencoded grant_type=authorization_code &code= &redirect_uri= &code_verifier= &client_id= ``` ```http POST /token HTTP/1.1 Content-Type: application/x-www-form-urlencoded grant_type=refresh_token &refresh_token= &client_id= ``` ##### Acciones esperadas En el canje, el Authorization Server verifica el código y comprueba que el `code_verifier` corresponde al `code_challenge` de la autorización, como exigen IUA[^iua-code-actions] y SMART App Launch[^smart-authorize]. Al renovar, el Authorization Server valida el refresh token y comprueba que se emitió a esa aplicación[^rfc6749-refresh]. El Authorization Server **SHALL** emitir el token renovado con el contexto de paciente fijado en la autorización, sin volver a consultar ITI-83, y sin ampliar el scope concedido. Con una aplicación pública, el Authorization Server **SHALL** emitir un refresh token nuevo en cada renovación e invalidar el anterior, o ligar el refresh token a esa instancia de la aplicación, como exige RFC 9700 para los clientes públicos ([RFC 9700, §4.14.2](https://www.rfc-editor.org/rfc/rfc9700.html#section-4.14.2))[^rfc9700-refresh]. Si rota los refresh tokens y recibe uno ya invalidado, **SHALL** revocar el refresh token vigente de esa autorización. RFC 9700 describe esa revocación como la respuesta de la rotación a un refresh token reutilizado[^rfc9700-refresh]. #### Respuesta de token ##### Evento desencadenante El Authorization Server responde a cada petición de token con el token si la concede o con un error si la rechaza. ##### Semántica del mensaje El Authorization Server responde a una petición concedida con el código HTTP 200, un body JSON y los headers `Cache-Control: no-store` y `Pragma: no-cache` que exige IUA ([IUA, §3.71.4.2.2](https://profiles.ihe.net/ITI/IUA/index.html#371422-message-semantics))[^iua-response]. La [Tabla 3.3-7](volume-2-hix-2.html#tabla-3-3-7) dice qué valor fija HIX en cada parámetro. La respuesta a una renovación tiene la misma forma, salvo por el `id_token`. El Authorization Server **SHALL** incluir `patient` en toda respuesta concedida, también en la de una renovación. **Tabla 3.3-7:** Parámetros de la respuesta de token | Parámetro | Valor en HIX | | --- | --- | | `access_token` | El token de la persona, destinado al Record Locator Service. Lleva el propósito de uso y el contexto de paciente, y la organización solo si el registro del Authorization Server asocia una a la aplicación. Lo resume la [Tabla 2.6-1](volume-1-security.html#tabla-2-6-1) | | `token_type` | `Bearer`, porque la aplicación lo presenta con ITI-72 | | `expires_in` | La vida del token en segundos, la que fije el Authorization Server | | `scope` | Solo los identificadores de transacción concedidos, que pueden diferir de los pedidos | | `id_token` | El de OpenID Connect, que acredita la autenticación de la persona y lleva `fhirUser`. Al renovar puede faltar, y si viene conserva el `iss` y el `sub` del original[^oidc-refresh] | | `refresh_token` | Solo si la aplicación pidió `offline_access` y el Authorization Server le concede la renovación | | `patient` | Siempre, también al renovar. Es el identificador del recurso Patient de la identidad maestra fijada como contexto de paciente | | `fhirContext` | HIX no lo fija. SMART App Launch lo admite para contexto adicional, y ningún actor de HIX depende de él | El Authorization Server **SHALL** incluir en el scope del access token solo identificadores de transacción. `openid`, `fhirUser`, `launch/patient` y `offline_access` los consume él al emitir el token y no aparecen en él. El `scope` de la respuesta describe el access token ([RFC 6749, §5.1](https://www.rfc-editor.org/rfc/rfc6749.html#section-5.1))[^rfc6749-token-response], y por eso lleva solo esos identificadores, según la regla 2 para las [peticiones a un Resource Server](volume-2.html#peticiones-a-un-resource-server). La aplicación sabe qué obtuvo de OpenID Connect y de SMART por los parámetros que recibe, es decir, `id_token`, `refresh_token` y `patient`. La respuesta distingue a quien actúa del paciente cuyo expediente se consulta. `sub` y `fhirUser` identifican a la persona que actúa, y `patient` al paciente. En el acceso propio son la misma persona, pero ningún actor deduce el paciente de `sub` ni de `fhirUser`, y el Record Locator Service confina cada operación solo con `patient`. **Ejemplo.** El Authorization Server responde al canje del código con el access token, el `id_token`, un refresh token y el contexto de paciente. ```http HTTP/1.1 200 OK Content-Type: application/json Cache-Control: no-store Pragma: no-cache { "access_token": "", "token_type": "Bearer", "expires_in": 300, "scope": "ITI-67 ITI-68", "id_token": "", "refresh_token": "", "patient": "" } ``` Si rechaza la petición, el Authorization Server responde con la respuesta de error de OAuth 2.0 y el código HTTP 400 ([RFC 6749, §5.2](https://www.rfc-editor.org/rfc/rfc6749.html#section-5.2))[^rfc6749-token-error]. **SHALL** rechazarla en las condiciones de la [Tabla 3.3-8](volume-2-hix-2.html#tabla-3-3-8). **Tabla 3.3-8:** Rechazos en el token endpoint | Condición | Error | Motivo | | --- | --- | --- | | El `code_verifier` no corresponde al `code_challenge` de la autorización | `invalid_grant`[^rfc7636-error] | Lo exige PKCE | | El Authorization Server no puede emitir el token renovado con el contexto de paciente fijado en la autorización | `invalid_grant` | La aplicación vuelve a la petición de autorización, que resuelve el contexto otra vez | | La renovación pide un scope mayor que el concedido | `invalid_scope` | RFC 6749 no permite ampliar el scope al renovar[^rfc6749-refresh] | Que solo la autorización de una persona fije un contexto de paciente lo protege la [Tabla 3.1-1](volume-2-authorization.html#tabla-3-1-1) para ITI-71 y la [Tabla 3.2-3](volume-2-hix-1.html#tabla-3-2-3) para HIX-1. ##### Acciones esperadas La aplicación valida el `id_token` conforme a OpenID Connect, como exige SMART App Launch[^smart-identity]. Presenta el access token con ITI-72 ante el Record Locator Service en las transacciones que su scope autoriza, y ante ningún otro actor. No pide ni asume un paciente distinto del que dice `patient`, como fija la [sección 2.2](volume-1-actors.html#aplicacion-del-paciente). Si recibe un refresh token nuevo al renovar, descarta el anterior[^rfc6749-refresh]. Si una renovación se rechaza con `invalid_grant`, vuelve a la petición de autorización, que resuelve el contexto otra vez. El Record Locator Service comprueba el token con ITI-102 y toma el contexto de paciente de la respuesta de la introspección, como fija la [sección 2.2](volume-1-actors.html#record-locator-service). El Authorization Server **SHALL** incluir `patient` en esa respuesta. Con él, el Record Locator Service confina cada operación al paciente, como describe la [sección 2.5](volume-1-usecases.html#acceso-del-paciente-a-su-expediente). **Ejemplo.** Al recibir una búsqueda ITI-67 de la aplicación, el Record Locator Service introspecciona el token con sus propias credenciales. `aud` nombra solo al Record Locator Service, `sub` a la persona que inició sesión y `patient` repite el contexto de paciente. La extensión `ihe_iua` lleva el propósito de uso `PATRQT`, porque quien actúa es la propia persona. ```http POST /introspect HTTP/1.1 Authorization: Basic Base64(:) Accept: application/json Content-Type: application/x-www-form-urlencoded token= ``` ```http HTTP/1.1 200 OK Content-Type: application/json { "active": true, "iss": "", "sub": "", "client_id": "", "aud": "", "jti": "", "iat": 1790967016, "exp": 1790967316, "scope": "ITI-67 ITI-68", "token_type": "Bearer", "patient": "", "extensions": { "ihe_iua": { "purpose_of_use": [ { "system": "http://terminology.hl7.org/CodeSystem/v3-ActReason", "code": "PATRQT", "display": "patient requested" } ] } } } ``` ### Consideraciones de seguridad La [sección 2.2](volume-1-actors.html#authorization-server) establece los requisitos del Authorization Server para este token. La [sección 2.6](volume-1-security.html#lo-que-un-token-prueba-y-lo-que-no) explica qué prueba el token ante cada destino. La aplicación no elige el paciente. Ningún parámetro de la petición lo identifica, el Authorization Server lo fija en la autorización y el Record Locator Service limita cada operación a ese contexto. La renovación no vuelve a resolver el contexto de paciente. Por eso, una fusión posterior de identidades maestras no cambia los tokens de una autorización vigente. Si la identidad del token es la que la fusión absorbió, la aplicación deja de encontrar los documentos de la persona hasta el siguiente inicio de sesión, que vuelve a consultar ITI-83, y, si la fusión es correcta, nunca alcanza los de otra persona. Ese plazo lo acotan la vida del refresh token y su revocación. El Authorization Server **SHOULD** revocar los refresh tokens de una persona cuando cierra sesión en él, cambia su credencial o retira la autorización a la aplicación. **SHOULD** también dejar vencer el refresh token que la aplicación no usa durante el tiempo que fije la comunidad. > **Nota.** RFC 9700 deja que el Authorization Server revoque los refresh tokens ante un evento de seguridad, como un cambio de contraseña o un cierre de sesión, y recomienda que venzan cuando el cliente deja de usarlos[^rfc9700-refresh]. La aplicación del paciente suele ser un cliente público, y IUA admite que su refresh token sea de larga vida[^iua-security]. Cada nuevo inicio de sesión vuelve además a resolver la identidad con ITI-83. Por esta razón, HIX-2 recomienda revocar el refresh token en esos casos y dejarlo vencer cuando no se usa. Del contexto que fija el lanzamiento, solo `patient` pasa al token mediado de [HIX-1](volume-2-hix-1.html), como establece la [sección 2.2](volume-1-actors.html#authorization-server). El `id_token` y `fhirUser` se quedan en la aplicación. Quien confina las consultas a ese expediente es el Record Locator Service, y el custodio **MAY** comprobarlo además, como explica la [sección 2.6](volume-1-security.html#lo-que-un-token-prueba-y-lo-que-no). #### Consideraciones de auditoría El Authorization Server registra cada lanzamiento y cada renovación, concedidos o rechazados, con el evento que IUA define para ITI-71 ([IUA, §3.71.5.1](https://profiles.ihe.net/ITI/IUA/index.html#37151-security-audit-considerations))[^iua-audit], como indica la [Tabla 3-2](volume-2.html#tabla-3-2). IUA no define un evento para la renovación, y HIX usa para ella el mismo. El evento de IUA no incluye al paciente, porque su único Participant Object es el token[^iua-audit-object]. Cuando hay contexto de paciente, el Authorization Server **SHALL** incluir en el evento la identidad maestra como paciente. Los patrones de BALP con paciente sirven de referencia para hacerlo ([BALP, §3:5.7.3](https://profiles.ihe.net/ITI/BALP/content.html#3573-restful-activities))[^balp-rest]. La consulta ITI-83 con la que el Authorization Server resuelve la identidad se registra con su propio evento, como indica la [Tabla 3-2](volume-2.html#tabla-3-2). Ningún registro contiene un token completo ni un refresh token, según la regla común de los [registros de auditoría](volume-2.html#registros-de-auditoria). El perfil de AuditEvent de este evento se especificará en una versión posterior de esta guía. ### Referencias Las citas reproducen el texto publicado por su fuente. Los recortes se marcan con "[...]" y la negrita es de esta guía. [^iua-grants]: [IUA, §34.1.1.1 Authorization Client](https://profiles.ihe.net/ITI/IUA/index.html#34111-authorization-client): "The Get Access Token [ITI-71] transaction **is scoped to the Authorization Code and Client Credential grant types** (see ITI TF-1: 34.4.1.1 Authorization Grant Types)." [§34.4.1.1 Authorization Grant Types](https://profiles.ihe.net/ITI/IUA/index.html#34411-authorization-grant-types): "This profile specifies the use of the Authorization Code and Client Credential grant types. **Actors of this profile may support other grant types as well.**" [^iua-smart]: [IUA, Relation to SMART-on-FHIR](https://profiles.ihe.net/ITI/IUA/index.html#relation-to-smart-on-fhir): "**IUA is not based on SMART-on-FHIR, but does strive to not conflict with that standard.**" [^iua-mhd-scope]: [IUA, adición a MHD Vol. 2, §3.67.5.2 Use with the Internet User Authorization (IUA) Profile](https://profiles.ihe.net/ITI/IUA/index.html#36752-use-with-the-internet-user-authorization-iua-profile): "**scope: ITI-67 This scope request authorizes the full [ITI-67] transaction.**" [^smart-standalone]: [SMART App Launch, Launch App: Standalone Launch](https://hl7.org/fhir/smart-app-launch/app-launch.html#launch-app-standalone-launch): "In SMART’s standalone launch flow, **a user selects an app from outside the EHR** (for example, by tapping an app icon on a mobile phone home screen)." [Obtain authorization code](https://hl7.org/fhir/smart-app-launch/app-launch.html#obtain-authorization-code): "launch conditional When using the EHR Launch flow, this must match the launch value received from the EHR. **Omitted when using the Standalone Launch.**" [^iua-code-request]: [IUA, §3.71.4.1.2.2 Authorization Code grant type](https://profiles.ihe.net/ITI/IUA/index.html#3714122-authorization-code-grant-type): "**resource (optional): Single valued identifier of the Resource Server endpoint to be accessed** [...] **code_challenge (required)** [...] **redirect_uri (optional)** [...] This parameter is required if the Authorization Client is registered at the Authorization Server with multiple redirect URI, optional otherwise [...] **code_verifier: The original code verifier string.**" [^smart-aud]: [SMART App Launch, Obtain authorization code](https://hl7.org/fhir/smart-app-launch/app-launch.html#obtain-authorization-code): "Note that **the aud parameter is semantically equivalent to the resource parameter defined in RFC8707**. [...] For the current release, **servers SHALL support the aud parameter and MAY support a resource parameter as a synonym for aud**." [^smart-well-known]: [SMART App Launch, FHIR Authorization Endpoint and Capabilities Discovery using a Well-Known Uniform Resource Identifiers (URIs)](https://hl7.org/fhir/smart-app-launch/conformance.html#using-well-known): "**FHIR endpoints requiring authorization SHALL serve a JSON document at the location formed by appending /.well-known/smart-configuration to their base URL.** The server SHALL convey the FHIR OAuth authorization endpoints and any optional SMART Capabilities it supports [...]" [^smart-authorize]: [SMART App Launch, Obtain authorization code](https://hl7.org/fhir/smart-app-launch/app-launch.html#obtain-authorization-code): "Note on PKCE Support: **the EHR SHALL ensure that the code_verifier is present and valid when the code is exchanged for an access token.** [...] **redirect_uri required** Must match one of the client's pre-registered redirect URIs. [...] **code_challenge_method required** [...] **The app SHALL validate the value of the state parameter upon return to the redirect URL** [...]" [^smart-pkce]: [SMART App Launch, Considerations for PKCE Support](https://hl7.org/fhir/smart-app-launch/app-launch.html#considerations-for-pkce-support): "**All SMART apps SHALL support Proof Key for Code Exchange (PKCE).** [...] **SMART servers SHALL support the S256 code_challenge_method and SHALL NOT support the plain method.**" [^smart-scopes]: [SMART App Launch, Scopes for requesting context data](https://hl7.org/fhir/smart-app-launch/scopes-and-launch-context.html#scopes-for-requesting-context-data): "**launch/patient Need patient context at launch time (FHIR Patient resource).**" [Scopes for requesting identity data](https://hl7.org/fhir/smart-app-launch/scopes-and-launch-context.html#scopes-for-requesting-identity-data): "Some apps need to authenticate the end-user. This can be accomplished by **requesting the scope openid**. When the openid scope is requested, apps can also request **the fhirUser scope to obtain a FHIR resource representation of the current user**." [^smart-refresh]: [SMART App Launch, Refresh access token](https://hl7.org/fhir/smart-app-launch/app-launch.html#refresh-access-token): "**no new permissions can be obtained at refresh time** [...] if the app was launched from within a patient context, **parameters to communicate the context values MAY BE included.**" [^smart-introspection]: [SMART App Launch, Token Introspection, Conditional fields in the introspection response](https://hl7.org/fhir/smart-app-launch/token-introspection.html#conditional-fields-in-the-introspection-response): "SMART Launch Context. **If a launch context parameter defined in Scopes and Launch Context (e.g., patient or intent) was included in the original access token response, the parameter SHALL be included in the token introspection response.** [...] ID Token Claims. If an id_token was included in the original access token response, the following claims from the ID Token **SHOULD** be included in the Token Introspection response: [...] fhirUser" [^rfc8707-resource]: [RFC 8707, §2 Resource Parameter](https://www.rfc-editor.org/rfc/rfc8707.html#section-2): "**resource Indicates the target service or resource to which access is being requested.** [...] **invalid_target The requested resource is invalid, missing, unknown, or malformed.** **The authorization server SHOULD audience-restrict issued access tokens to the resource(s) indicated by the "resource" parameter. Audience restrictions can be communicated in JSON Web Tokens [RFC7519] with the "aud" claim** [...] **The authorization server may use the exact "resource" value as the audience or it may map from that value to a more general URI or abstract identifier for the given resource.**" [^iua-security]: [IUA, §3.71.5 Security Considerations](https://profiles.ihe.net/ITI/IUA/index.html#3715-security-considerations): "Access token should be short-lived with a lifetime of 1 hour or less. [...] **Refresh token may be long lived.** [...] To reduce the attack surface, client claims and authorization grants shall be the minimal; i.e., **the authorization grant scope requested by the Authorization Client shall be the minimal required scope** for the resource request to be used for." [^iua-code-actions]: [IUA, §3.71.4.1.3.2 Authorization Code grant type](https://profiles.ihe.net/ITI/IUA/index.html#3714132-authorization-code-grant-type): "**The Authorization Server shall authenticate confidential and credential clients** [...] If valid, **the Authorization Server shall authenticate the user and obtain the user consent** [...]" [^oidc-offline]: [OpenID Connect Core 1.0, §11 Offline Access](https://openid.net/specs/openid-connect-core-1_0.html#OfflineAccess): "**When offline access is requested, a prompt parameter value of consent MUST be used unless other conditions for processing the request permitting offline access to the requested resources are in place. The OP MUST always obtain consent to returning a Refresh Token that enables offline access to the requested resources.** A previously saved user consent is not always sufficient to grant offline access." [^oidc-refresh]: [OpenID Connect Core 1.0, §12.2 Successful Refresh Response](https://openid.net/specs/openid-connect-core-1_0.html#RefreshTokenResponse): "Upon successful validation of the Refresh Token, the response body is the Token Response of Section 3.1.3.3 [...] **except that it might not contain an id_token**. If an ID Token is returned as a result of a token refresh request, the following requirements apply: **its iss Claim Value MUST be the same as in the ID Token issued when the original authentication occurred, its sub Claim Value MUST be the same as in the ID Token issued when the original authentication occurred** [...]" [^rfc6749-authz-error]: [RFC 6749, §4.1.2.1 Error Response](https://www.rfc-editor.org/rfc/rfc6749.html#section-4.1.2.1): "If the request fails due to a missing, invalid, or mismatching redirection URI, or if the client identifier is missing or invalid, **the authorization server SHOULD inform the resource owner of the error and MUST NOT automatically redirect the user-agent to the invalid redirection URI.** [...] **temporarily_unavailable** The authorization server is currently unable to handle the request due to a temporary overloading or maintenance of the server." [^rfc7636-error]: [RFC 7636, §4.4.1 Error Response](https://www.rfc-editor.org/rfc/rfc7636.html#section-4.4.1): "If the server requires Proof Key for Code Exchange (PKCE) by OAuth public clients and the client does not send the "code_challenge" in the request, **the authorization endpoint MUST return the authorization error response with the "error" value set to "invalid_request"**. [...] If the server supporting PKCE does not support the requested transformation, **the authorization endpoint MUST return the authorization error response with "error" value set to "invalid_request"**." [§4.6 Server Verifies code_verifier before Returning the Tokens](https://www.rfc-editor.org/rfc/rfc7636.html#section-4.6): "If the values are not equal, **an error response indicating "invalid_grant"** as described in Section 5.2 of [RFC6749] MUST be returned." [^smart-token]: [SMART App Launch, Obtain access token](https://hl7.org/fhir/smart-app-launch/app-launch.html#obtain-access-token): "For public apps, **authentication is not required because a client with no secret cannot prove its identity** when it issues a call. [...] For confidential apps, authentication is required. [...] **code_verifier required** This parameter is used to verify against the code_challenge parameter previously provided in the authorize request. **client_id conditional Required for public apps.** Omit for confidential apps." [^rfc6749-client-id]: [RFC 6749, §3.2.1 Client Authentication](https://www.rfc-editor.org/rfc/rfc6749.html#section-3.2.1): "**A client MAY use the "client_id" request parameter to identify itself when sending requests to the token endpoint.** In the "authorization_code" "grant_type" request to the token endpoint, an unauthenticated client MUST send its "client_id" to prevent itself from inadvertently accepting a code intended for a client with a different "client_id"." [^rfc6749-refresh]: [RFC 6749, §6 Refreshing an Access Token](https://www.rfc-editor.org/rfc/rfc6749.html#section-6): "**The requested scope MUST NOT include any scope not originally granted by the resource owner, and if omitted is treated as equal to the scope originally granted by the resource owner.** [...] Because refresh tokens are typically long-lasting credentials used to request additional access tokens, **the refresh token is bound to the client to which it was issued**. [...] The authorization server MAY issue a new refresh token, in which case **the client MUST discard the old refresh token and replace it with the new refresh token**." [^iua-state]: [IUA, §3.71.4.1.2.2 Authorization Code grant type](https://profiles.ihe.net/ITI/IUA/index.html#3714122-authorization-code-grant-type): "state (required): An unguessable value used by the client to track the state between the authorization request and the callback to the redirect URI. While this parameter is optional in the OAuth 2.1 Authorization Framework [...] **it is required in this profile for security reasons**." [^rfc9700-redirect]: [RFC 9700, §2.1 Protecting Redirect-Based Flows](https://www.rfc-editor.org/rfc/rfc9700.html#section-2.1): "When comparing client redirection URIs against pre-registered URIs, **authorization servers MUST utilize exact string matching** except for port numbers in localhost redirection URIs of native apps" [^rfc9700-refresh]: [RFC 9700, §4.14.2 Recommendations](https://www.rfc-editor.org/rfc/rfc9700.html#section-4.14.2): "**Authorization servers MUST utilize one of these methods to detect refresh token replay by malicious actors for public clients** [...] The authorization server cannot determine which party submitted the invalid refresh token, **but it will revoke the active refresh token.** [...] **Authorization servers MAY revoke refresh tokens automatically in case of a security event** [...] **Refresh tokens SHOULD expire if the client has been inactive for some time**" [^iua-response]: [IUA, §3.71.4.2.2 Message Semantics](https://profiles.ihe.net/ITI/IUA/index.html#371422-message-semantics): "scope (required): The scope granted by the Authorization Server. [...] refresh_token (optional): A token provided by the Authorization Server which can be used by the Authorization Client **to obtain new access tokens using the same authorization grant**. [...] **The Authorization Server shall include the HTTP Cache-Control response header field with value no-store and the Pragma response header field value no-cache** to the access token response [...]" [^rfc6749-token-response]: [RFC 6749, §5.1 Successful Response](https://www.rfc-editor.org/rfc/rfc6749.html#section-5.1): "scope OPTIONAL, if identical to the scope requested by the client; otherwise, REQUIRED. **The scope of the access token** as described by Section 3.3." [^rfc6749-token-error]: [RFC 6749, §5.2 Error Response](https://www.rfc-editor.org/rfc/rfc6749.html#section-5.2): "The authorization server **responds with an HTTP 400 (Bad Request) status code (unless specified otherwise)** and includes the following parameters with the response: **error REQUIRED.** [...] **invalid_grant** The provided authorization grant (e.g., authorization code, resource owner credentials) or refresh token **is invalid, expired, revoked**, does not match the redirection URI used in the authorization request, or was issued to another client. [...] **invalid_scope** The requested scope is invalid, unknown, malformed, or **exceeds the scope granted by the resource owner**." [^smart-identity]: [SMART App Launch, Scopes for requesting identity data](https://hl7.org/fhir/smart-app-launch/scopes-and-launch-context.html#scopes-for-requesting-identity-data): "**This token must be validated according to the OIDC specification.** To learn more about the user, the app should treat the fhirUser claim as the URL of a FHIR resource representing the current user." [^iua-audit]: [IUA, §3.71.5.1 Security Audit Considerations](https://profiles.ihe.net/ITI/IUA/index.html#37151-security-audit-considerations): "The Authorization Client or Authorization Server that is grouped with an ATNA Secure Node or Secure Application **shall be able to send an audit event as defined below** [...] EventID [...] EV(110114, DCM, "User Authentication") [...] EventTypeCode [...] **EV("ITI-71", IHE, "User Authorization")**". [^iua-audit-object]: [IUA, §3.71.5.1 Security Audit Considerations](https://profiles.ihe.net/ITI/IUA/index.html#37151-security-audit-considerations): "Source (1) Human Requestor (0) Destination (0) Audit Source (Client Authentication Agent) (1) **Participant Object (1)** [...] **Token** [...] ParticipantObjectTypeCode M "2" (System) [...] ParticipantObjectTypeCodeRole M "13" (Security Resource)" [^balp-rest]: [BALP, §3:5.7.3 RESTful activities](https://profiles.ihe.net/ITI/BALP/content.html#3573-restful-activities): "When a FHIR RESTful interaction happens, **the following AuditEvent patterns can be used**. [...] There are two sets of profiles distinguished by **Patient as a subject** being mandated to be populated." ## Identidad del paciente ## Publicación ## Localización y recuperación # Apéndices Los apéndices reúnen material de apoyo que no forma parte normativa de los volúmenes. Por ahora contienen el glosario de actores y términos. ## Glosario Este glosario reúne, en una línea cada uno, los actores y términos que usa esta guía. Los actores propios de HIX se definen en la [sección 2.2](volume-1-actors.html). Los actores IHE enlazan a la página del perfil que los define. ### Actores de HIX **Record Locator Service.** El mediador de la comunidad. Localiza y recupera documentos en nombre de los miembros y aplica la decisión de divulgación sobre los punteros. Es un nombre propio de esta guía, no vocabulario IHE. **Document Registry.** El registro de documentos de la comunidad. Conserva los punteros a los documentos publicados y, bajo la Opción de Almacenamiento Central, el contenido que los custodios le entregan. Toma su nombre y su función del [Document Registry de MHDS](https://profiles.ihe.net/ITI/MHDS/volume-1.html#150111-document-registry), pero es un actor de HIX, definido por los actores que agrupa. **[Authorization Server](https://profiles.ihe.net/ITI/IUA/index.html).** El Authorization Server de IUA. Emite, comprueba e intercambia los tokens que circulan por la comunidad. **Directorio de la comunidad.** Publica las organizaciones participantes, su pertenencia a la comunidad y los endpoints en los que responden. Es el Directory de mCSD y Resource Server de IUA. **Master Patient Index (MPI).** Conserva una identidad maestra por persona y sus enlaces con las identidades locales. Agrupa al Patient Identity Registry de PMIR, al Patient Identifier Cross-reference Manager de PIXm y al Patient Demographics Supplier de PDQm. Es el componente que OpenHIE llama [Client Registry](https://guides.ohie.org/arch-spec/openhie-component-specifications-1/client-registry). **[Audit Record Repository](https://profiles.ihe.net/ITI/TF/Volume1/ch-9.html).** El actor de ATNA que recibe los eventos de auditoría de los actores centrales. **Fuente autoritativa de identidad.** Sistema externo a la comunidad que verifica la identidad de las personas y crea las identidades maestras. Es el Patient Identity Source de PMIR. HIX no la designa. La propuesta para Costa Rica es que sea el EDUS. **Custodio.** El sistema que publica y custodia documentos. Miembro que produce documentos, los conserva, declara las identidades locales de sus pacientes y publica los punteros. **Consumidor.** El sistema que consume documentos. Miembro que localiza y recupera documentos de un paciente a través del Record Locator Service. **Aplicación del paciente.** Aplicación con la que una persona accede a su propio expediente con el contexto de paciente que fija el Authorization Server. ### Actores IHE que HIX agrupa **[Document Source](https://profiles.ihe.net/ITI/MHD/5.0.0/1331_actors_and_transactions.html).** Actor de MHD que publica documentos y sus punteros con ITI-65. **[Document Consumer](https://profiles.ihe.net/ITI/MHD/5.0.0/1331_actors_and_transactions.html).** Actor de MHD que localiza listas y documentos con ITI-66 e ITI-67 y recupera documentos con ITI-68. **[Document Responder](https://profiles.ihe.net/ITI/MHD/5.0.0/1331_actors_and_transactions.html).** Actor de MHD que responde la localización y la recuperación de documentos. **[Document Recipient](https://profiles.ihe.net/ITI/MHD/5.0.0/1331_actors_and_transactions.html).** Actor de MHD que recibe las publicaciones ITI-65. **[Patient Identity Source](https://profiles.ihe.net/ITI/PMIR/volume-1.html).** Actor de PMIR y de PIXm que alimenta identidades de paciente, con ITI-93 o ITI-104. **[Patient Identity Registry](https://profiles.ihe.net/ITI/PMIR/volume-1.html).** Actor de PMIR que conserva las identidades maestras que recibe por ITI-93. **[Patient Identity Consumer](https://profiles.ihe.net/ITI/PMIR/volume-1.html).** Actor de PMIR que recibe por ITI-93 los cambios de las identidades maestras, en particular las fusiones, y los aplica a sus propios datos. **[Patient Identifier Cross-reference Manager](https://profiles.ihe.net/ITI/PIXm/volume-1.html).** Actor de PIXm que recibe identidades locales por ITI-104, las enlaza con la identidad maestra y responde ITI-83. **[Patient Identifier Cross-reference Consumer](https://profiles.ihe.net/ITI/PIXm/volume-1.html).** Actor de PIXm que resuelve un identificador con ITI-83. **[Patient Demographics Supplier](https://profiles.ihe.net/ITI/PDQm/volume-1.html).** Actor de PDQm que responde búsquedas por datos demográficos con ITI-78 y coincidencias probabilísticas con ITI-119. **[Patient Demographics Consumer](https://profiles.ihe.net/ITI/PDQm/volume-1.html).** Actor de PDQm que busca pacientes por datos demográficos con ITI-78 o con ITI-119. **[Directory](https://profiles.ihe.net/ITI/mCSD/volume-1.html#146111-directory).** Actor de mCSD que publica el directorio y responde ITI-90. Hasta mCSD 3 se llamaba Care Services Selective Supplier, y así lo nombra todavía MHDS. **[Query Client](https://profiles.ihe.net/ITI/mCSD/volume-1.html#146112-query-client).** Actor de mCSD que consulta el directorio con ITI-90. Hasta mCSD 3 se llamaba Care Services Selective Consumer, y así lo nombra todavía MHDS. **[Authorization Client](https://profiles.ihe.net/ITI/IUA/index.html).** Actor de IUA que obtiene tokens con ITI-71 y los presenta con ITI-72. **[Resource Server](https://profiles.ihe.net/ITI/IUA/index.html).** Actor de IUA que recibe un token con ITI-72, comprueba que está destinado a él y lo valida, en su caso con ITI-102. **[Secure Node y Secure Application](https://profiles.ihe.net/ITI/TF/Volume1/ch-9.html).** Actores de ATNA. Un sistema que se declara uno u otro autentica sus conexiones, las cifra y registra sus eventos de auditoría con ITI-20. El Secure Node aplica esos servicios de seguridad a todo el sistema. La Secure Application los aplica solo a la aplicación y a los actores que agrupa. **[Time Client](https://profiles.ihe.net/ITI/TF/Volume1/ch-7.html).** Actor de CT que sincroniza el reloj de su sistema mediante ITI-1 con el Time Server que la comunidad designa, propio o una fuente de tiempo externa. ### Términos de esta guía **Miembro.** Organización participante de la comunidad. Figura en el directorio y el Authorization Server reconoce a sus sistemas. **Infraestructura central.** Los actores que opera la comunidad, es decir, el Record Locator Service, el Document Registry, el Authorization Server, el directorio, el Master Patient Index y el Audit Record Repository. **Mediador.** Otro nombre del Record Locator Service, por la función que cumple entre los miembros y los custodios. **Contexto de paciente.** El paciente al que queda confinado un token emitido con [HIX-2](volume-2-hix-2.html), es decir, la identidad maestra de la persona que lanzó la aplicación. **Access token.** La credencial que un cliente presenta ante un Resource Server para pedir acceso, según OAuth 2.0. **Audience.** El Resource Server, o los Resource Servers, ante los que vale un token, en el claim `aud`. **Identidad maestra.** La identidad verificada de una persona, única en la comunidad, creada por la fuente autoritativa de identidad. Lleva un identificador de la persona que la fuente autoritativa reconoce, como la cédula, y los enlaces a las identidades locales. **MRN.** Medical Record Number, el identificador que un miembro asigna a un paciente en su propio dominio, como su número de expediente. Solo tiene sentido dentro de ese dominio, y el Master Patient Index lo enlaza con la identidad maestra. **Identidad local.** El paciente tal como lo conoce un miembro, con su MRN. Cada miembro la declara y la enlaza con la identidad maestra. **Puntero.** El `DocumentReference` que describe un documento sin contenerlo. Sobre él se toma toda decisión de la comunidad antes de mover contenido. **SubmissionSet.** Recurso `List` de MHD que agrupa los punteros de una misma publicación y dice quién los publicó y cuándo. Toda publicación ITI-65 lleva uno, e ITI-66 los devuelve. **Decisión de divulgación.** La evaluación que hace la infraestructura central, en el mediador o en el Document Registry, puntero por puntero y antes de recuperar, de si un documento puede entregarse a quien lo pide. **Propósito de uso.** Código del conjunto PurposeOfUse de HL7 que dice para qué se accede. Viaja en el token y lo evalúa la decisión de divulgación. **Scope.** Lo que autoriza un token en OAuth 2.0. Fija qué transacciones puede pedir su portador. **[OpenID Provider](https://openid.net/specs/openid-connect-core-1_0.html#Terminology).** Authorization Server de OAuth 2.0 que además autentica a la persona y acredita esa autenticación con un `id_token`, según OpenID Connect. En HIX lo es el Authorization Server de la comunidad. **Token del solicitante.** El token que un miembro obtiene con ITI-71, o la aplicación del paciente con [HIX-2](volume-2-hix-2.html). El de un miembro está destinado a los Resource Servers centrales que define la comunidad, y el de la aplicación solo al Record Locator Service. Lleva el sujeto, el propósito de uso y el scope. El de un miembro lleva además su organización, y el de la aplicación del paciente el contexto de paciente y la organización solo si la aplicación tiene una registrada. **Token mediado.** El token que el mediador obtiene con [HIX-1](volume-2-hix-1.html) para el destino que nombra su `resource`, nunca para dos custodios, y un solo tipo de transacción, con el solicitante original como sujeto y el mediador como actor. Se emite para el custodio y, salvo que la comunidad autorice un token propio conforme a la [sección 2.2](volume-1-actors.html#record-locator-service), para cada Resource Server central que la comunidad despliegue como un sistema distinto. **Token de actor.** El token propio que el Record Locator Service obtiene con ITI-71 y el grant Client Credentials, con el Authorization Server como audiencia y sin scope, y presenta como `actor_token` en [HIX-1](volume-2-hix-1.html). Solo vale ante el Authorization Server y no lleva extensiones de IUA. **PEP.** Punto de aplicación de política. El lugar donde se comprueba que una petición cumple las reglas de la comunidad. En HIX, el primero es el mediador. **PDP.** Punto de decisión de política. El lugar donde se toma la decisión que el PEP aplica. En HIX, la decisión de divulgación se toma en la infraestructura central, en el mediador o en el Document Registry.