Общие положения

Платформа MEDESK предоставляет JSON REST API для внешних по отношению к ней сервисов, и может быть использована для интеграции с МИС или CRM системами, подключении web-портала, организации online-записи на прием и другое.

Для успешного использования сервиса необходимо понимание вопросов организации данных и обеспечения их безопасности.

Безопасность и контроль доступа

Безопасность передачи данных и контроль доступа к ресурсам являются важными вопросами, понимание которых позволит эффективно взаимодействовать с платформой.

Сервис выполняет защиту данных на всех этапах ее обработки: передача осуществляется по шифрованному каналу, а доступ выполняется с учетом надлежащих прав.

Сессия, токены доступа и обновления

При рассмотрении вопросов контроля доступа мы оперируем двумя сущностями:

  • клиент (приложение, скрипт или браузер), инициирующий запрос к ресурсу
  • ресурс (например пациент, организация или событие в календаре), к которому осуществляется доступ

В процессе взаимодействия с сервисом, для каждого клиента создается структура данных - сессия, в которой сохраняются данные об уровне доступа клиента, установленных лимитах/ограничениях, а так же другие важные для обработки запроса параметры.

Клиент имеет ограниченный доступ к сессии - API позволяет получить сведения относительно текущего набора групп безопасности, лимитах/ограничениях и других данных, необходимых для исполнения собственной логики, при этом запрещает возможность их изменения.

Выполняя запрос, клиент обязан сообщить сервису, в рамках какой сессии (а значит с каким уровнем доступа) он должен обрабатываться. Для указания сессии клиент использует токен доступа, который представляет собой уникальную строку символов, полученную им после прохождения процедуры авторизации (поддерживаются стандартные процедуры авторизации Resource Owner Credentials и Client Credentials, определенные OAuth2.0).

Передается токен через Authorization HTTP-заголовок:

"Authorization": "Bearer <access token>”

При отсутствии данного заголовка запрос считается неавторизованным, и результат его обработки зависит от требований, предъявляемых ресурсом, к которому осуществляется доступ.

Все токены, выданные сервисом являются срочными, то есть имеют определенный срок действия, в течение которого предъявление токена дает право на обработку запроса. Узнать время жизни токена можно используя API получения информации о сессии, и в случае необходимости его продления, может быть выполнен его обмен на новый, путем передачи парного токена обновления (полученного в процессе авторизации). Устаревший токен доступа может быть продлен в течение 24ч; по истечении 24ч токены ликвидируются без возможности их повторного использования.

При необходимости выполнения продолжительных операций, время выполнения которых больше срока действия выданного токена, необходимо выполнять его продление, а не повторную авторизацию, так как это гарантирует сохранность рабочей сессии. Выпуск нового токена при авторизации создает новую сессию с параметрами по умолчанию.

В случае компрометирования токена, он может быть заблокирован или запрещен к использованию, что сделает невозможным его дальнейшее использование.

Access Control List, покрытия и уровни доступа

Разграничение прав доступа выполняется на основании ролей, заданных текущей авторизацией, а так же набора правил Access Control List ( ACL ), определенных для большинства ресурсов. Каждое правило определяет уровень доступа, который имеет роль на определенном покрытии. Покрытие, в свою очередь, является именованным набором свойств ресурса; ресурс может иметь любое количество покрытий, при этом любое из его свойств может входить в не более чем одно покрытие. Конкретный набор свойств, входящий в то или иное покрытие, определяется отдельно для каждого ресурса.

Например, ресурс профиль зарегистрированного пользователя имеет следующие покрытия:

  • general
  • details
  • private
  • ...

Покрытие general доступно для чтения большинству авторизованных клиентов и включает в себя такие свойства, как логин пользователя, его ФИО, пол и другую общую информацию. details в свою очередь содержит сведения об опыте работы, контактной информации, образовании и других данных, которые доступны только профилю, а так же сотрудникам организации, работником которой он является. Покрытие private содержит информацию, которая доступна непосредственно профилю, и включает в себя сведения о текущей роли, реквизитах доступа.

Как было указано выше, ACL определяет уровень доступа, который имеет роль на определенном покрытии. Роли, в свою очередь, сохраняются в сессии клиента, и при каждом запросе к защищенному ресурсу, анализируются сервисом, с целью вычисления максимального уровня доступа клиента к данному ресурсу. Запрос выполняется только в случае, если уровень доступа клиента выше значения заданного правилом ACL.

В системе определены следующие уровни доступа:

Наименование | Числовое значение
-------------+------------------
NO_ACCESS    | 0x00
LIST         | 0x01
READ         | 0x02
WRITE        | 0x04
ADD          | 0x08
FULL         | 0x0F

Каждый последующий уровень включает в себя предыдущие, то есть имея уровень WRITE по отношению к ресурсу можно выполнять его поиск - LIST, чтение - READ и изменение - WRITE.

Сведения об уровне доступа к каждому покрытию ресурса содержатся в поле acl, их можно получить выполнив запрос GET /<url ресурса>. Ниже пример содержимого поля acl, полученного по профилю пользователя, который не является сотрудником организации.

{
  "acl": {
    "general": 2,
    "details": 0,
    "grants": 0,
    "subscriptions": 0,
    "memberships": 8,
    "calendars": 0,
    "private": 0,
    "acl": 0
  }
}

Из числовых значений видно, что по данному ресурсу можно получить общую информацию о профиле (general: 2), а так же имеется возможность пригласить его в качестве сотрудника - то есть создать связку профиль-предприятие (memberships: 8).

В общем виде, обработка запроса выполняется в несколько этапов:

  • на основании ACL ресурса вычисляется уровень доступа, достаточный для выполнения операции
  • для всех ролей сессии, вычисляется максимальный уровень доступа на всех покрытиях ресурса, необходимых для обработки запроса
  • обработка запроса, в случае если уровень доступа к ресурсу выше или равен достаточному уровню

Работа с ресурсом

Логика работы сервиса распределена между ресурсами, связанными между собой, и каждый из них имеет свой определенный адрес (URL). Чтение/запись свойств ресурса осуществляется посредством отправки HTTP-запроса по указанному адресу с указанием необходимых параметров. Набор параметров и ограничений на их значения определены для каждого ресурса отдельно, при этом имеется общие правила их использования.

  • Чтение ресурса выполнятся GET-запросом по адресу его расположения. Например, для получения сведений о профиле с идентификатором 1234, используется запрос GET/profiles/1234.
  • Создание ресурса выполнятся POST-запросом на коллекцию, где он должен быть размещен. Параметры нового ресурса передаются через тело запроса. Например, календари хранятся в коллекции /calendars, а значит для создания нового календаря необходимо выполнить запрос POST /calendars.
  • Изменение ресурса выполняется методом PATCH с набором изменяемых свойств и их значений, переданных в теле запроса. Структура свойств для PATCH соответствует структуре, используемой для создания ресурса через POST, за одним исключением - значение null имеет специальное значение и используется для удаления свойств. Например, если ресурс имеет свойство name, то для его изменения:
name: “Новое значение”

а для удаления:

name: null
  • Для удаления используется DELETE-запрос по адресу ресурса