Conectarse a aplicaciones mediante SMART on FHIR

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

Información general

SMART on FHIR es un estándar de datos que permite a las aplicaciones acceder a la información de los sistemas de historias clínicas electrónicas (HCE). 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 tiene datos de pacientes almacenados en un almacén FHIR de la API Cloud Healthcare, puede desarrollar una aplicación que haga lo siguiente:

  1. Se autentica en el almacén FHIR.
  2. Obtiene 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 autorización y la autenticación.

Entorno de inicio de aplicaciones SMART, ámbitos y contexto de inicio

La API Cloud Healthcare admite el framework, los ámbitos y el contexto de inicio de aplicaciones SMART de la siguiente manera:

Framework de inicio de aplicaciones SMART

La API Cloud Healthcare admite la secuencia de inicio independiente del framework de inicio de aplicaciones SMART.

Una aplicación puede iniciarse desde un sistema de EHR o un portal para pacientes, lo que se denomina "inicio de EHR", o como una aplicación independiente.

Ámbitos

Los permisos de datos clínicos definen los permisos de lectura y escritura para el acceso específico de pacientes y a nivel de usuario. La API Cloud Healthcare admite los siguientes ámbitos de datos definidos en Ámbitos para solicitar datos clínicos:

  • patient
  • user
  • system
Contexto de lanzamiento

Describe el paciente, la consulta u otro contexto actuales en el que se realiza la solicitud. La API Cloud Healthcare admite el contexto de inicio de paciente de Scopes for requesting context data (Ámbitos para solicitar datos de contexto).

Configurar el servidor de autorización para SMART on FHIR

La API Cloud Healthcare proporciona compatibilidad integrada con la aplicación de acceso SMART en FHIR basada en los ámbitos de autorización SMART y el contexto del paciente. Los administradores de almacenes FHIR crean y configuran un servidor de autorización fuera de la API Cloud Healthcare que concede ámbitos de autorización SMART y contexto del paciente.

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

Definir y validar ámbitos de autorización de SMART

Si usas SMARTProxy, puedes saltarte esta sección. SMARTProxy define y valida los ámbitos de autorización de SMART automáticamente.

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

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

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

Tu servidor de autorización concede los ámbitos de autorización de SMART y el contexto del paciente, y los codifica en un token de acceso. A continuación, el proxy lee la información del token de acceso y la transfiere a los encabezados de la solicitud FHIR.

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

Usa los siguientes encabezados HTTP de SMART on FHIR al hacer solicitudes desde el proxy. La aplicación cliente no tiene que definir estos encabezados, ya que solo se transfieren del proxy a la API de Cloud Healthcare.

  • X-Authorization-Scope: uno o varios ámbitos de autorización que usan los formatos de ámbito de autorización estándar de SMART. Por ejemplo, si se define el ámbito de autorización como user/Observation.read, significa que una solicitud solo puede leer un recurso Observation. La API Cloud Healthcare aplica este control de acceso.
  • X-Authorization-Patient: el contexto del paciente de la solicitud. Cuando definas este encabezado, todos los tipos de recursos de la solicitud que puedan estar en un compartimento de paciente deben pertenecer al compartimento de paciente del ID de paciente proporcionado. La API Cloud Healthcare aplica este control de acceso.
  • X-Authorization-Subject: identificador del usuario final que accede a la aplicación cliente de SMART on FHIR. La API Cloud Healthcare registra el asunto en los registros de auditoría.
  • X-Authorization-Issuer: emisor del token de acceso de SMART. La API Cloud Healthcare registra el emisor en los registros de auditoría.

Configurar 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 ámbitos de autorización de SMART y, opcionalmente, el contexto del paciente. La API Cloud Healthcare no tiene requisitos específicos sobre cómo el servidor de autorización genera el token JWT de SMART. Por ejemplo, tu aplicación puede estar registrada para un subconjunto de ámbitos o puede presentar un widget de selección de pacientes para definir 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 tokens JWT.

Token de acceso de ejemplo

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, 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"
}

Configurar SMART en FHIR en la API de Cloud Healthcare

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

Configurar SMARTProxy

Si usas tu propio servidor de autorización en lugar de SMARTProxy, salta esta sección y ve a Configurar una cuenta de servicio Google Cloud .

SMARTProxy es un proxy de software libre de Google que ofrece las siguientes funciones:

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

Cuando haces una solicitud para recuperar datos de la API 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 ámbitos y el contexto del paciente del token SMART y los transfiere a la API Cloud Healthcare mediante cuatro encabezados HTTP.
  4. La API Cloud Healthcare recibe los encabezados y los valida para aplicar el control de acceso a la solicitud. A continuación, la API de Cloud Healthcare devuelve una respuesta al cliente a través de SMARTProxy.

Configurar una cuenta de servicio de Google Cloud

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

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

  • La dirección de correo principal de Cloud Audit Logs está vinculada a la cuenta de servicio.

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

Configurar un almacén FHIR

No es necesario que configure el almacén FHIR que contiene los datos FHIR a los que quiere acceder.

Hacer solicitudes de SMART en FHIR

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

Cuando se hace una solicitud, tu servidor de autorización es el responsable de generar tokens de acceso con el ámbito de autorización de SMART y el contexto de inicio pertinentes.

Métodos admitidos

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

Aplicación del acceso a recursos

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

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

El compartimento de pacientes es fundamental para la lógica de aplicación del acceso en la API Cloud Healthcare. SMART on FHIR tiene una lista de tipos de recursos FHIR que se pueden incluir en un compartimento de paciente. 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 compartimento del paciente". Los tipos de recursos no aptos se denominan "tipos de recursos no aptos para el compartimento del paciente".

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

  • Proporciona el rol patient, user o system en los ámbitos de autorización de SMART. Si proporcionas el rol patient, debes proporcionar un contexto de paciente. El contexto del paciente es un ID lógico del recurso Patient. El recurso Patient ya debe existir en el almacén FHIR o existir después de que se haya realizado la solicitud. De lo contrario, la API Cloud Healthcare rechazará la solicitud.

  • Al crear, leer, actualizar o eliminar un recurso, el resourceType y el tipo de operación (read o write) deben coincidir. De lo contrario, la API Cloud Healthcare rechazará la solicitud.

  • Si proporcionas un ámbito patient que contenga tipos de recursos no aptos para el compartimento de pacientes, como patient/Practitioner.*, la comprobación de validación del ámbito fallará y la API Cloud Healthcare rechazará el ámbito.

  • Puedes definir todos los tipos de recursos con el ámbito user. Si hay un contexto de paciente con un ámbito user, los tipos de recursos aptos para el compartimento de paciente se limitan al contexto de paciente. Los tipos de recursos restantes ignoran el contexto del paciente.

  • La presencia de un contexto de paciente restringe los tipos de recursos aptos para el compartimento de pacientes al paciente en cuestión. Por ejemplo, un recurso Observation debe tener el campo subject que haga referencia al recurso Patient correspondiente para que se pueda acceder a Observation. Consulta los tipos de acceso a compartimentos de pacientes en Resource CompartmentDefinition - Content (CompartmentDefinition de recursos: contenido) para ver una lista de los campos de cada tipo de recurso de compartimento de pacientes a los que se debe hacer referencia para que el recurso se considere dentro del compartimento de pacientes.

  • Las solicitudes pueden contener ámbitos patient y user.

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

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

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