Health Information Exchange - Local Development build (v0.1.0) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions

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.

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. HIX-2 no registra ni modifica ese segundo consentimiento.

HIX-2 es 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)¹. 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)². 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 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 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

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¹⁰. 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)⁵. 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⁵. 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)¹². 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)¹³. 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 dice qué declara HIX en él.

Tabla 3.3-2: Contenido del documento smart-configuration

Ejemplo. La aplicación pide el documento a partir de la URL base FHIR del Record Locator Service.

GET /.well-known/smart-configuration HTTP/1.1
Accept: application/json

HTTP/1.1 200 OK
Content-Type: application/json

{
  "issuer": "<issuer>",
  "jwks_uri": "<jwks_uri>",
  "authorization_endpoint": "<authorization_endpoint>",
  "token_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, y los dos documentos describen los mismos endpoints.

Roles de actor

La Tabla 3.3-3 muestra los roles de los actores de HIX en la transacción, según la sección 2.4.

Tabla 3.3-3: Roles de actor

Durante el lanzamiento, el Authorization Server también actúa como 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. Esa consulta no forma parte de HIX-2.

Estándares referenciados

HIX-2 se apoya en los documentos siguientes.

• IUA, 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, 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, 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, The OAuth 2.0 Authorization Framework, octubre de 2012. Aporta el grant de refresh token y las respuestas de error.
• RFC 7636, Proof Key for Code Exchange by OAuth Public Clients, septiembre de 2015. Aporta code_challenge, code_verifier y el método S256.
• RFC 8707, Resource Indicators for OAuth 2.0, febrero de 2020. Aporta el parámetro resource y el error invalid_target.
• RFC 9700, 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 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.

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.

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)⁴. La 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

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. La aplicación pide solo los que necesita, como IUA exige a todo Authorization Client (IUA, §3.71.5)¹⁶. 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.

GET /authorize?response_type=code&client_id=<client_id>&redirect_uri=<redirect_uri>&state=<state>&resource=<rls_resource>&code_challenge=<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)¹⁷. Cómo se verifica la identidad de la persona es política de la comunidad, según la sección 2.6.

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)¹⁸. 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. 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. Nunca lo toma de la petición, según la regla 3 para las 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⁴. Si la rechaza, redirige con error y el state de la petición (RFC 6749, §4.1.2.1)¹⁹.

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

El Authorization Server SHALL rechazar la petición en las condiciones de la Tabla 3.3-5. Los códigos son los que prevén RFC 7636 para PKCE²⁰, RFC 8707 para el recurso¹² y RFC 6749 para los demás¹⁹.

Tabla 3.3-5: Rechazos en el authorization endpoint

Ejemplo. El Authorization Server rechaza un lanzamiento cuya identidad verificada no resuelve a una identidad maestra.

HTTP/1.1 302 Found
Location: <redirect_uri>?error=access_denied&state=<state>

Acciones esperadas

La aplicación comprueba que state coincide con el valor que envió⁶. 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⁴ y SMART App Launch (SMART App Launch, Obtain access token)²¹. La renovación sigue RFC 6749 (RFC 6749, §6)²² y SMART App Launch¹⁰. La 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

SMART App Launch exige el client_id en el canje de una aplicación pública²¹. La aplicación pública SHALL enviarlo también al renovar, como admite RFC 6749 (RFC 6749, §3.2.1)²³, 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.

POST /token HTTP/1.1
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=<code>
&redirect_uri=<redirect_uri>
&code_verifier=<code_verifier>
&client_id=<client_id>

POST /token HTTP/1.1
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token=<refresh_token>
&client_id=<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¹⁷ y SMART App Launch⁶.

Al renovar, el Authorization Server valida el refresh token y comprueba que se emitió a esa aplicación²². 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)²⁴. 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²⁴.

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)²⁵. La 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

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)²⁷, y por eso lleva solo esos identificadores, según la regla 2 para las 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/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache

{
  "access_token": "<access_token>",
  "token_type": "Bearer",
  "expires_in": 300,
  "scope": "ITI-67 ITI-68",
  "id_token": "<id_token>",
  "refresh_token": "<refresh_token>",
  "patient": "<patient_id>"
}

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)²⁸. SHALL rechazarla en las condiciones de la Tabla 3.3-8.

Tabla 3.3-8: Rechazos en el token endpoint

Que solo la autorización de una persona fije un contexto de paciente lo protege la Tabla 3.1-1 para ITI-71 y la 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²⁹. 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. Si recibe un refresh token nuevo al renovar, descarta el anterior²². 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. 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.

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.

POST /introspect HTTP/1.1
Authorization: Basic Base64(<client_id>:<client_secret>)
Accept: application/json
Content-Type: application/x-www-form-urlencoded

token=<access_token>

HTTP/1.1 200 OK
Content-Type: application/json

{
  "active": true,
  "iss": "<issuer>",
  "sub": "<person_sub>",
  "client_id": "<patient_app_client_id>",
  "aud": "<rls_audience>",
  "jti": "<jti>",
  "iat": 1790967016,
  "exp": 1790967316,
  "scope": "ITI-67 ITI-68",
  "token_type": "Bearer",
  "patient": "<patient_id>",
  "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 establece los requisitos del Authorization Server para este token. La sección 2.6 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²⁴. La aplicación del paciente suele ser un cliente público, y IUA admite que su refresh token sea de larga vida¹⁶. 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, como establece la sección 2.2. 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.

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)³⁰, como indica la 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³¹. 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)³².

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. Ningún registro contiene un token completo ni un refresh token, según la regla común de los registros de auditoría. 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.