Cómo conectarse a aplicaciones con SMART on FHIR

En esta página, se describe cómo usar el estándar SMART (Tecnologías Reutilizables, Aplicaciones Médicas Sustituibles) en FHIR v1.1.0 para acceder a los datos en los almacenes de FHIR en la API de Cloud Healthcare.

Descripción general

SMART en FHIR es un estándar de datos que permite que las aplicaciones accedan a la información en sistemas de registros de salud electrónicos (EHR). Un desarrollador de aplicaciones puede escribir una sola aplicación que se conecte a cualquier sistema de EHR que haya adoptado el estándar.

Por ejemplo, si tienes datos de pacientes almacenados en un almacén de FHIR en la API de Cloud Healthcare, puedes desarrollar una aplicación que haga lo siguiente:

  1. Se autentica en el almacén de FHIR.
  2. Recupera los datos del paciente.
  3. Muestra los datos del paciente en una interfaz de usuario.

SMART on FHIR admite los modelos de autorización OpenID y OAuth 2.0 para la autenticación y la autorización.

Framework, alcances y contexto de lanzamiento de la app de SMART

La API de Cloud Healthcare admite el framework de lanzamiento de las apps de SMART, los permisos y el contexto de lanzamiento de la siguiente manera:

Framework de lanzamiento de apps de SMART

La API de Cloud Healthcare admite la secuencia de lanzamiento independiente del framework de lanzamiento de las apps de SMART.

Una app puede iniciarse desde un sistema de EHR existente o una sesión del portal de pacientes, que se llaman “lanzamiento de EHR”, o como una app independiente.

Permisos

Los permisos de datos clínicos definen los permisos de lectura y escritura para el acceso específico del paciente y del nivel del usuario. La API de Cloud Healthcare admite los siguientes permisos de datos definidos en Permisos para solicitar datos clínicos:

  • patient
  • user
  • system
Contexto de lanzamiento

Describe el paciente actual, el encuentro o cualquier otro contexto en el que se realiza la solicitud. La API de Cloud Healthcare admite el contexto de inicio del paciente desde los Alcances para solicitar datos de contexto.

Configura tu servidor de autorización para SMART on FHIR

La API de Cloud Healthcare ofrece una compatibilidad integrada con la aplicación de acceso SMART en FHIR basada en los permisos de autorización SMART de entrada y el contexto de los pacientes. Los administradores de almacenes de FHIR crean y configuran un servidor de autorización fuera de la API de Cloud Healthcare que otorga permisos de autorización de SMART y contexto del paciente.

Si una aplicación cliente obtiene un token de acceso que representa los permisos de autorización de SMART otorgados y el contexto del paciente, la API de Cloud Healthcare no especifica qué flujo de trabajo de inicio debe usar la aplicación cliente con el servidor de autorización externo.

Configura y valida los permisos de autorización de SMART

Si usas SMARTProxy, puedes omitir esta sección. SMARTProxy establece y valida los permisos de autorización de SMART de forma automática.

Los permisos de autorización de SMART usan el siguiente formato:

( 'patient' | 'user' | 'system') '/' ( resourceType | '*' ) '.' ( 'read' | 'write' | '*' )

Los permisos de autorización de SMART y los contextos de los pacientes se pasan a la API de Cloud Healthcare mediante los encabezados HTTP X-Authorization-. La API de Cloud Healthcare usa estos encabezados para aplicar el control de acceso a los datos en los almacenes de FHIR.

Tu servidor de autorización otorga los permisos de SMART y el contexto de los pacientes, y los codifica en un token de acceso. Luego, el proxy lee la información en el token de acceso y la pasa a los encabezados de la solicitud de FHIR.

Si no tienes un servidor de autorización, puedes usar el acelerador de interoperabilidad basado en Apigee HealthAPIx en Apigee.

Usa los siguientes SMART en los encabezados HTTP FHIR cuando realices solicitudes desde el proxy. La aplicación cliente no necesita establecer estos encabezados, ya que solo se pasan desde el proxy a la API de Cloud Healthcare.

  • X-Authorization-Scope: Uno o más permisos de autorización que usan los formatos de permiso de autorización SMART estándar. Por ejemplo, establecer el alcance de autorización en user/Observation.read significa que una solicitud solo puede leer un recurso de Observation. La API de Cloud Healthcare aplica este control de acceso.
  • X-Authorization-Patient: El contexto del paciente de la solicitud. Cuando configuras este encabezado, cualquier tipo de recurso en la solicitud que sea apto para estar en un compartimiento para pacientes debe pertenecer al compartimiento para pacientes del ID de paciente proporcionado. La API de Cloud Healthcare aplica este control de acceso.
  • X-Authorization-Subject: Un identificador para el usuario final que accede a SMART en una aplicación cliente de FHIR. La API de Cloud Healthcare registra el asunto en Registros de auditoría.
  • X-Authorization-Issuer: La entidad emisora del token de acceso SMART. La API de Cloud Healthcare registra el emisor en Registros de auditoría.

Configura los tokens de acceso del servidor de autorización

Para emitir un token JWT, debes configurar un servidor de autorización. El token JWT contiene los permisos de autorización SMART y, de forma opcional, el contexto del paciente. La API de Cloud Healthcare no tiene requisitos específicos sobre cómo el servidor de autorización crea el token JWT de SMART. Por ejemplo, tu aplicación puede estar registrada para un subconjunto de permisos o la aplicación puede presentar un widget de selección de pacientes a fin de establecer el contexto del paciente.

Si no tienes un servidor de autorización que configure tokens JWT de SMART, puedes usar el acelerador de interoperabilidad basado en Apigee HealthAPIx en Apigee para configurar un servidor de autenticación que firme los tokens JWT.

Token de acceso de muestra

En el siguiente ejemplo, se muestra un token de acceso codificado en Base64:

eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzM4NCJ9.eyJpc3MiOiJzbWFydC50b2tlbi5vcmciLCJpYXQiOjE2MTI4ODQwODUsImV4cCI6MTY0NDQyMDA4NSwiYXVkIjoid3d3LmV4YW1wbGUuY29tIiwic3ViIjoiZG9jdG9yLmpvZUBleGFtcGxlLmNvbSIsInNjb3BlIjoidXNlci9QcmFjdGl0aW9uZXIucmVhZCBwYXRpZW50LyouKiIsInBhdGllbnQiOiJwYXRpZW50MTIzIn0.lC0ouNuXNcj7FxQ83NU_MInULWo0wvyiNuaMt2RbFzBOnnMP_IXJdCeNnw3SQzUV

Después de decodificar el token de acceso, este contiene la siguiente carga útil:

{
  "iss": "smart.token.org",
  "iat": 1612884085,
  "exp": 1644420085,
  "aud": "www.example.com",
  "sub": "doctor.gabriela@example.com",
  "scope": "user/Practitioner.read patient/*.*",
  "patient": "patient123"
}

Configura SMART on FHIR en la API de Cloud Healthcare

En esta sección, se describen los pasos que debes seguir para comenzar a usar SMART en FHIR con datos en la API de Cloud Healthcare.

Configura SMARTProxy

Si usas tu propio servidor de autorización en lugar de SMARTProxy, omite esta sección y continúa con Configura una cuenta de servicio de Google Cloud.

SMARTProxy es un proxy de código abierto de Google que proporciona las siguientes funciones:

  • Permite que la API de Cloud Healthcare acepte y valide los tokens de acceso SMART.
  • Permite que la implementación de FHIR en la API de Cloud Healthcare incluya tokens de acceso inteligentes como parte del modelo de permisos y administración de la API.

Cuando realizas una solicitud para recuperar datos de la API de Cloud Healthcare a través de SMARTProxy, la solicitud sigue estos pasos:

  1. SMARTProxy acepta una solicitud que contiene un token SMART de un cliente.
  2. SMARTProxy valida el token SMART a través de tu servidor de autorización JWT.
  3. SMARTProxy lee los permisos y el contexto de los pacientes del token SMART y los pasa a la API de Cloud Healthcare a través de cuatro encabezados HTTP.
  4. La API de Cloud Healthcare recibe los encabezados y los valida para aplicar el control de acceso en la solicitud. Luego, la API de Cloud Healthcare le muestra al cliente una respuesta a través de SMARTProxy.

Configura una cuenta de servicio de Google Cloud

Un proxy solo puede tener una cuenta de servicio de Google Cloud. Si varios clientes usan el mismo proxy, los clientes deben usar la misma cuenta de servicio. Ten cuidado cuando compartas una cuenta de servicio con varios clientes por los siguientes motivos:

  • Para leer los datos de FHIR en la API de Cloud Healthcare, la cuenta de servicio tiene permisos amplios de lectura y escritura.

  • La dirección de correo electrónico principal de los registros de auditoría de Cloud está vinculada a la cuenta de servicio.

    Por ejemplo, si llamas a la API de Cloud Healthcare con tu Cuenta de Google para la autenticación, los Registros de auditoría de Cloud registrarán tu dirección de correo electrónico como la principal. Cuando usas un proxy para llamar a la API de Cloud Healthcare, el proxy usa su propia cuenta de servicio, y la dirección de correo electrónico de la cuenta de servicio es la dirección de correo electrónico principal, por lo que se oculta el llamador original. Para guardar el usuario final en los metadatos del registro de auditoría, pasa la dirección de correo electrónico del usuario final en el campo sub del token JWT.

Configura una tienda de FHIR

No necesitas configurar el almacén de FHIR que contiene los datos de FHIR a los que accedes.

Realiza solicitudes SMART en FHIR

En esta sección, se proporciona una descripción general de los SMART admitidos en los métodos de FHIR en la API de Cloud Healthcare y cómo se aplica el acceso a los recursos cuando realizas una solicitud SMART en FHIR.

Cuando se realiza una solicitud, tu servidor de autorización es responsable de generar tokens de acceso con el permiso de la autorización de SMART relevante y el contexto de lanzamiento.

Métodos admitidos

La API de Cloud Healthcare admite SMART en FHIR para todos los métodos projects.locations.datasets.fhirStores.fhir, excepto los siguientes:

Aplicación del acceso a los recursos

Cuando se realiza una solicitud SMART en FHIR a un almacén de FHIR, el control de acceso se produce en el siguiente orden:

  1. La API de Cloud Healthcare verifica los permisos en la cuenta de servicio de Google Cloud configurada en el proxy. Si la cuenta de servicio tiene los permisos de IAM correctos en el almacén de FHIR, la solicitud continúa.
  2. La API de Cloud Healthcare verifica si el token SMART tiene los permisos adecuados para acceder a cada recurso de FHIR que solicita la solicitud.

El compartimiento de pacientes es fundamental para la lógica de aplicación de acceso en la API de Cloud Healthcare. SMART on FHIR tiene una lista de tipos de recursos de FHIR que son aptos para incluirse en un compartimiento para pacientes. Los tipos de recursos también tienen sus propios criterios de inclusión. En el resto de esta sección, los tipos de recursos aptos se denominan “tipos de recursos aptos para el compartimiento de los pacientes”. Los tipos de recursos no aptos se denominan “tipos de recursos no aptos para el compartimiento de pacientes”.

Las solicitudes de SMART on FHIR a un almacén de FHIR deben cumplir con los siguientes requisitos:

  • Proporciona la función patient, user o system en los permisos de autorización de SMART. Si proporcionas la función patient, debes proporcionar un contexto de pacientes. El contexto del paciente es un ID lógico de recursos de pacientes. El recurso Patient ya debe existir en la tienda de FHIR o después de que se realiza la solicitud. De lo contrario, la API de Cloud Healthcare rechaza la solicitud.

  • Cuando se crea, se lee, se actualiza o se borra un recurso, el resourceType y el tipo de operación (read o write) deben coincidir, de lo contrario, la API de Cloud Healthcare rechaza la solicitud.

  • Si proporcionas un permiso patient que contiene tipos de recursos que no son aptos para el compartimiento de pacientes, como patient/Practitioner.*, la verificación de validación del permiso fallará y la API de Cloud Healthcare rechazará el permiso.

  • Puedes configurar todos los tipos de recursos con el permiso user. Si un contexto de los pacientes está presente con un permiso user, los tipos de recursos aptos para el compartimiento de los pacientes se restringen al contexto del paciente. Los tipos de recursos restantes ignoran el contexto del paciente.

  • La presencia de un contexto de los pacientes restringe los tipos de recursos aptos para el compartimiento de pacientes, al paciente determinado. Por ejemplo, un recurso de Observation debe tener la referencia de campo subject para que el paciente sea accesible. Consulta los tipos de acceso del compartimiento de pacientes en Resource CompartmentDefinition - Content para obtener una lista de los campos en cada tipo de recurso del compartimiento de pacientes que se deben referir al paciente determinado a fin de que el recurso se considere dentro del compartimiento de pacientes.

  • Las solicitudes pueden contener los permisos patient y user.

  • No uses el permiso system con el contexto del paciente. De lo contrario, la solicitud fallará.

  • No uses el permiso system con el permiso patient o user.

  • Si llamas a un método que accede a varios recursos (por ejemplo, el método fhir.Patient-everything, fhir.executeBundle o fhir.search), el control de acceso se aplica a cada recurso individual.