SMART App Launch: основы, контекст запуска, PKCE

Q: Какова разница между областями действия patient/ и user/?

patient/ ограничивает доступ к одному пациенту в контексте запуска; user/ предоставляет доступ ко всему, что разрешено видеть аутентифицированному пользователю, независимо от пациента. Приложения, ориентированные на пациентов, используют patient/ ; приложения для врачей часто используют user/ с контекстом.

Краткий ответ: SMART App Launch (SMART on FHIR) — это спецификация HL7, определяющая, как приложение получает авторизованный доступ к FHIR-серверу от имени пользователя. Это реализация OAuth 2.0 и OpenID Connect с соглашениями, специфичными для FHIR: файл обнаружения по адресу .well-known/smart-configuration; два режима запуска (запуск из ЭМК, когда ЭМК открывает приложение в контексте текущего пациента, и автономный запуск, когда пользователь открывает приложение и выбирает пациента); области действия (scopes) в синтаксисе, понимающем FHIR (patient/Observation.rs означает чтение и поиск наблюдений пациента в контексте); контекст запуска, возвращаемый вместе с токеном (какой пациент, какой визит); и сервисы для бэкэнда для доступа между системами с аутентификацией клиента по подписанному JWT. SMART v2 (с 2021 года) сделал PKCE обязательным, добавил гранулированные области действия и асимметричную аутентификацию клиента, и именно эта версия требуется национальными программами.

Шаг 1: обнаружение

Обнаружение SMART App Launch начинается с того, что приложение получает документ .well-known/smart-configuration сервера FHIR. В нем перечислены конечные точки авторизации и токенов, поддерживаемые возможности (запуск из ЭМК, автономный запуск, публичные и конфиденциальные клиенты, OpenID Connect, разрешения для пациента и пользователя), поддерживаемые области действия, методы проверки кода PKCE и типы предоставления доступа. Таким образом, приложение знает, куда отправить пользователя.

GET https://fhir.example-hospital.org/.well-known/smart-configuration

{
  "issuer": "https://auth.example-hospital.org",
  "authorization_endpoint": "https://auth.example-hospital.org/authorize",
  "token_endpoint": "https://auth.example-hospital.org/token",
  "introspection_endpoint": "https://auth.example-hospital.org/introspect",
  "capabilities": ["launch-ehr", "launch-standalone", "client-public", "client-confidential-asymmetric", "sso-openid-connect", "context-ehr-patient", "context-standalone-patient", "permission-patient", "permission-user", "permission-v2", "permission-offline"],
  "scopes_supported": ["openid", "fhirUser", "launch", "launch/patient", "patient/*.rs", "user/*.rs", "offline_access"],
  "code_challenge_methods_supported": ["S256"],
  "grant_types_supported": ["authorization_code", "client_credentials"]
}

Приложение узнает, куда отправлять пользователя и что поддерживает сервер.

Шаг 2: запуск

SMART App Launch имеет два режима запуска. При запуске из ЭМК врач открывает приложение внутри ЭМК, которая передает параметр iss (сервер FHIR) и непрозрачный токен запуска, кодирующий текущего пациента и визит. При автономном запуске пользователь открывает приложение напрямую, и сервер авторизации просит его выбрать или подтвердить пациента.

Запуск из ЭМК. Врач нажимает на приложение внутри ЭМК; ЭМК открывает URL запуска приложения с двумя параметрами: iss (FHIR-сервер) и launch (непрозрачный токен, который кодирует текущего пациента и визит). Приложение должно передать launch в своем запросе на авторизацию с областью действия launch.

Автономный запуск. Пользователь открывает приложение напрямую; приложение знает FHIR-сервер (выбранный или настроенный) и запрашивает контекст с помощью launch/patient; сервер авторизации просит пользователя выбрать или подтвердить пациента.

Шаг 3: код авторизации с PKCE

Шаг авторизации SMART — это поток кода авторизации OAuth 2.0 с PKCE: приложение отправляет пользователя на конечную точку авторизации с указанием своих областей действия, aud сервера FHIR и проверки кода. Пользователь аутентифицируется и дает согласие. Приложение обменивает возвращенный код и верификатор кода на токен доступа, который поступает вместе с контекстом запуска.

GET https://auth.example-hospital.org/authorize?
  response_type=code&client_id=my-app&redirect_uri=https://app.example.org/cb
  &scope=openid%20fhirUser%20launch%20patient/Observation.rs%20patient/Condition.rs%20offline_access
  &state=af0ifjsldkj&aud=https://fhir.example-hospital.org
  &launch=xyz123&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM&code_challenge_method=S256

Пользователь аутентифицируется (с помощью поставщика удостоверений больницы) и одобряет области действия; сервер перенаправляет обратно с code; приложение обменивает его:

POST https://auth.example-hospital.org/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=...&redirect_uri=https://app.example.org/cb&client_id=my-app&code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk

{
  "access_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "openid fhirUser launch patient/Observation.rs patient/Condition.rs offline_access",
  "refresh_token": "a8c3...",
  "id_token": "eyJhbGciOi...",
  "patient": "Patient/123",
  "encounter": "Encounter/456",
  "fhirUser": "Practitioner/42",
  "need_patient_banner": true,
  "smart_style_url": "https://ehr.example.org/styles/smart.json"
}

Контекст запуска (patient, encounter, fhirUser) поступает вместе с токеном. Публичные клиенты (мобильные и браузерные приложения) используют PKCE и не используют секрет клиента; конфиденциальные клиенты аутентифицируются с помощью секрета или, предпочтительно, с помощью подписанного JWT (private_key_jwt) по асимметричному методу.

Области действия (Scopes)

Области действия SMART on FHIR v2 используют синтаксис context/resource.permissions, где context — это patient, user или system, а permissions объединяют c, r, u, d и s для создания, чтения, обновления, удаления и поиска, как в patient/Observation.rs. Гранулированные области действия добавляют фильтр, openid и fhirUser предоставляют идентификатор пользователя, области действия запуска запрашивают контекст, а offline_access запрашивает токен обновления.

Синтаксис SMART v2: <контекст>/<ресурс>.<разрешения> где контекст — это patient (пациент в контексте), user (то, что может видеть пользователь) или system (бэкэнд), а разрешения — это любые из c создать, r читать, u обновить, d удалить, s искать, в таком порядке: patient/Observation.rs, user/Patient.rs, system/*.cruds. Гранулированные области действия добавляют фильтр: patient/Observation.rs?category=http://terminology.hl7.org/CodeSystem/observation-category|vital-signs. openid fhirUser предоставляют токен идентификации и идентификатор пользователя FHIR; launch, launch/patient, launch/encounter запрашивают контекст; offline_access — токен обновления для использования, когда пользователь отсутствует, online_access — действительный только во время сеанса. Синтаксис v1 (patient/Observation.read) по-прежнему принимается многими серверами.

Сервисы для бэкэнда

Для системы, действующей без пользователя (ночной экспорт, интеграционный движок), SMART Backend Services использует client_credentials с подписанным JWT-утверждением (публичные ключи клиента публикуются по URL JWKS) и области действия system/. Нет пользователя, нет контекста запуска, строгая регистрация.

Безопасное использование

Безопасное использование SMART App Launch означает регистрацию точных URI перенаправления, никогда не использование неявного потока, безопасное хранение и ротацию токенов обновления, проверку state и aud токенов идентификации, проверку токенов при каждом вызове API, принудительное применение как областей действия, так и контекста пациента на уровне данных, чтобы токен одного пациента никогда не читал данные другого, и регистрацию каждого доступа.

Регистрируйте точные URI перенаправления; никогда не используйте неявный поток; безопасно храните токены обновления и периодически их меняйте; проверяйте state; проверяйте aud токенов идентификации; проверяйте токены при каждом вызове API (интроспекция или проверка JWT) и применяйте области действия и контекст пациента на уровне данных, потому что токен для Patient/123 никогда не должен читать Patient/124; регистрируйте каждый доступ (Безопасность и идентификация: карта). SMART также определяет Бренды доступа к пациентам (Patient Access Brands) — способ для приложений показывать пользователям, с какими организациями они могут связаться, и взаимодействует с SMART Health Links для обмена данными по инициативе пациента.

Где это требуется

Правила доступа пациентов в США требуют, чтобы сертифицированные ЭМК поддерживали SMART App Launch и Backend Services; национальные программы в Европе принимают его для доступа приложений (нидерландская MedMij использует OAuth 2.0 с эквивалентными соглашениями); IPS и многие руководства по внедрению предполагают его использование. См. TEFCA и Национальные электронные медицинские карты.

В Anpheros

Платформа Anpheros использует OAuth 2.0 с PKCE для приложений и аутентификацию клиента по подписанному JWT для бэкэндов, с областями действия, основанными на согласии человека, и контекстом пациента, применяемым при каждом запросе. На сайте для разработчиков документированы аутентификация и шаблон SMART on FHIR для бэкэнда для разработки на его основе.

Связанные страницы

Источники

Частые вопросы

Является ли SMART on FHIR тем же самым, что и OAuth 2.0?

Это OAuth 2.0 и OpenID Connect с дополнениями, специфичными для FHIR: обнаружение, контекст запуска, синтаксис областей действия и сервисы для бэкэнда. Любая библиотека OAuth подойдет; соглашения SMART делают приложение переносимым между FHIR-серверами.

Нужен ли мне PKCE для серверного приложения?

В SMART v2 — да, для всех клиентов, использующих поток кода авторизации. Конфиденциальные клиенты добавляют аутентификацию клиента (секрет или подписанный JWT) поверх этого.

Какова разница между областями действия patient/ и user/?

patient/ ограничивает доступ к одному пациенту в контексте запуска; user/ предоставляет доступ ко всему, что разрешено видеть аутентифицированному пользователю, независимо от пациента. Приложения, ориентированные на пациентов, используют patient/; приложения для врачей часто используют user/ с контекстом.

Может ли SMART-приложение записывать в запись?

Если ему предоставлены разрешения на создание или обновление (c, u) в его областях действия, и сервер это разрешает. Многие развертывания предоставляют приложениям для пациентов только чтение и поиск, а запись направляют через специальные ресурсы, такие как QuestionnaireResponse.

Anpheros Platform

Попробуйте бесплатно в песочнице

Первый запрос FHIR за 5 минут. API HL7 FHIR R4 с встроенным согласием пациента: попробуйте в песочнице, затем подключите свое приложение или систему клиники.

Создать бесплатную песочницу Запустить демо-приложение →Стартовый код (Python) →Коллекция Postman →Читать руководства для разработчиков →

Бесплатно · 30 синтетических пациентов · без карты

Это руководство носит информационный характер и не заменяет консультацию врача. Решения о своём здоровье принимайте вместе с врачом. В экстренной ситуации звоните по местному номеру экстренной помощи (112 в Европе).

Автор

Команда Anpheros

Anpheros создает медицинскую карту, которую пациент контролирует и может делиться с любой клиникой, на платформе HL7 FHIR R4, базирующейся в ЕС. Эти руководства помогут вам понять и организовать свое здоровье; они не заменяют вашего врача.

О Anpheros →