Conectarse a aplicaciones mediante SMART en FHIR

En esta página, se describe cómo usar el estándar SMART (sustitutable Medical Applications, Reusable Technologies) en FHIR v1.1.0 para acceder a los datos de almacenes de FHIR en la API de Cloud Healthcare.

Descripción general

SMART on 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 HCE 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 en FHIR admite los modelos de autorización de OpenID y OAuth 2.0 para autorización y autenticación.

Framework SMART App Launch, alcances y contexto de inicio

La API de Cloud Healthcare admite el framework de inicio de apps SMART, los permisos y el contexto de inicio 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 se puede iniciar desde un sistema existente de HCE o una sesión del portal de pacientes, los cuales se denominan "inicio de HCE" 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 del lanzamiento

Describe el paciente, el encuentro o cualquier otro contexto actual 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 el servidor de autorización para SMART en 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 alcances de autorización SMART y contexto de pacientes.

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

Establecer y validar los alcances de la autorización SMART

Si usas SMARTProxy, puedes omitir esta sección. SMARTProxy establece y valida los alcances de la autorización SMART automáticamente.

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 configurar estos encabezados porque solo se pasan del 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 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 SMART, puedes usar el acelerador de interoperabilidad basado en Apigee HealthAPIx en Apigee para configurar un servidor de autenticación que firme 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 en 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 características:

  • Permite que la API de Cloud Healthcare acepte y valide tokens de acceso SMART.
  • Permite que la implementación de FHIR en la API de Cloud Healthcare incluya tokens de acceso SMART 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 su servidor de autorización JWT.
  3. SMARTProxy lee los alcances y el contexto de los pacientes desde el token SMART y los pasa a la API de Cloud Healthcare mediante 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 una respuesta al cliente 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 registran tu dirección de correo electrónico como la dirección de correo electrónico principal. Cuando usas un proxy para llamar a la API de Cloud Healthcare, este 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 el emisor original se oculta. 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 es necesario que configures el almacén de FHIR que contiene los datos de FHIR a los que accedes.

Realiza SMART en solicitudes 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 de acceso a 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 compartimento de pacientes es fundamental para la lógica de aplicación de acceso en la API de Cloud Healthcare. SMART en 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”.

SMART en solicitudes de FHIR a un almacén de FHIR debe 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 recurso para pacientes. El recurso Paciente ya debe existir en el almacén de FHIR o existir después de que se realiza la solicitud. De lo contrario, la API de Cloud Healthcare la rechazará.

  • Cuando se crea, lee, actualiza o borra un recurso, 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 hay un contexto de paciente con un alcance user, los tipos de recursos aptos para el compartimento del paciente 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 observación debe tener el campo subject que haga referencia al recurso de paciente determinado para que se pueda acceder a la observación. Consulta los tipos de acceso al compartimiento del paciente en Resource CompartmentDefinition - Content para obtener una lista de los campos de cada tipo de recurso del compartimento del paciente a los que se debe hacer referencia para el paciente determinado a fin de que el recurso se considere dentro del compartimiento del paciente.

  • Las solicitudes pueden contener los permisos patient y user.

  • No uses el alcance system con el contexto del paciente; de lo contrario, la solicitud fallará.

  • No uses el alcance system con patient ni 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.