Токены доступа к содержимому системы¶
Для некоторых ресурсов системы необходимо обеспечить доступ извне, причем доступ должен быть контролируемым. Для обеспечения такого доступа в версии 4.0 был разработан механизм временных ссылок на содержимое.
Токены доступа к контенту¶
Контроль доступа к ресурсу осуществляется с помощью специального токена доступа, который на клиент передается в составе следующей структуры.
| Поле | Тип данных | Описание |
|---|---|---|
Token |
string |
Токен доступа, который используется клиентом при запросе контента по ссылке и удостоверяет права доступа |
Scope |
string |
Область действия (скоуп) токена. Используется при валидации токена при получении контента |
Expires |
DateTime |
Окончание срока действия токена |
Hash |
string |
Шестнадцатеричное строковое представление хэша токена |
В БД информация о токенах доступа хранится в таблице Tokens, которая имеет следующую структуру:
| Поле | Тип данных | Описание |
|---|---|---|
ID |
String(128) Not Null |
Уникальный идентификатор токена |
Caption |
String(Max) Not Null |
Описание токена, устанавливается обработчиком, выдавшим токен в соответствии с его логикой работы |
Scope |
String(256) Not Null |
Область действия (скоуп) токена |
Created |
DateTime Not Null |
Дата создания токена |
Expires |
DateTime Not Null |
Дата окончания действия токена |
CreatedByID |
Guid Not Null |
Идентификатор сотрудника, создавшего токен |
RefID |
Guid Null |
Идентификатор ресурса, к которому относится этот токен (может быть не заполнено). Для файлов - идентификатор файла, для версий файлов - идентификатор версии файла |
Ref2ID |
Guid Null |
Дополнительный идентификатор ресурса, к которому относится этот токен (может быть не заполнено). Для файлов и версий файлов - идентификатор карточки |
UserID |
Guid Null |
Идентификатор сотрудника, для которого был создан токен (может быть не заполнено) |
TokenHash |
Binary(32) Not Null |
Хеш токена. Вычисляется для типов токенов |
Signature |
Binary(32) Null |
Подпись токена (может быть не заполнено). Вычисляется только для защищённых protected токенов (см. ниже) |
Токены бывают двух типов:
- Открытые (
plain) - используются для доступа к нечувствительным данным. Токен доступа совпадает с его уникальным идентификаторомID, токен хэшируется и записывается в полеTokenHash, подпись не вычисляется. - Защищённые (
protected) - используются для доступа к чувствительному содержимому системы (файлы и т.п.). Сам токен доступа не хранится в БД, но в ней хранится его хэш в полеTokenHashи подпись в полеSignature, вычисленная по ключевым полям:Caption,Scope,RefID,Ref2ID,UserID,Expiresв которые включается актуальное значение токена доступа.
Important
Для protected токенов в поле ID хранится уникальный идентификатор токена, не совпадающий с актуальным токеном доступа к содержимому.
Для plain токенов в поле ID записывается актуальный токен доступа к содержимому.
Поиск protected токенов при выполнении запроса на получение содержимого осуществляется по следующему алгоритму:
- Переданный в запросе токен доступа хэшируется.
- Поиск в таблице осуществляется по полю
TokenHash. - Если запись для токена была найдена, то для неё вычисляется подпись.
- Вычисленная подпись сравнивается с первоначальной сохраненной подписью.
- Если подписи совпадают, запись токена возвращается, иначе считается, что токен не найден.
Таким образом, поля protected токена не могут быть изменены после его создания.
Important
Способ хранения токенов выбирается на уровне типа содержимого и не может быть различным для содержимого одного и того же типа.
Помимо этого, можно выделить несколько видов токенов:
- Токены, привязанные к пользователю (
UserExclusive). Такие токены выделяются для пользователя в единственном экземпляре в рамках единственного скоупа, и при запросе токена будет возвращен уже существующий токен, если срок его действия еще не истек, в противном случае выделяется новый токен. Могут храниться только в открытом виде (plain), так как должна быть возможность возвращать токен после его создания в течение некоторого периода. Такие токены актуальны для множества однотипных ресурсов, для каждого из которых не требуется обеспечить отдельный доступ (например, аватары пользователей). - Токены, привязанные к ссылке на содержимое (
ContentLinkExclusive). Такие токены выделяются каждый раз, когда нужно сформировать ссылку на содержимое. Актуальны в случае, когда к каждому ресурсу в рамках одного типа нужно обеспечить доступ отдельно (например, ссылки на файлы).
Срок действия токена выбирается для каждого типа контента индивидуально, исходя из принципов безопасности и необходимости кэширования контента по ссылке (подробнее в разделе Кэширование возвращаемого контента браузером).
Скоуп токена может совпадать или не совпадать с типом контента, для одного типа контента могут выделяться токены с разным скоупом, если нужна различная обработка запросов контента в рамках одного типа контента. Кроме этого, в скоупе может быть указано несколько значений, разделенных пробелами, при этом длина каждого значения должна быть небольшой, так как для хранения всех скоупов с учётом пробелов доступно 256 символов. На уровне платформы валидация этого значения не осуществляется, его необходимо проверять в соответствующих обработчиках контента.
Ссылки на контент¶
Ссылки на контент могут быть сформированы двумя способами:
https://server_name/content/{type}/{contentID}?token={token}- ссылка такого вида подходит для использования пользователем в браузере, если при получении контента возникли ошибки, то они отобразятся в читаемом виде в html.https://server_name/api/v1/content/{type}/{contentID}?token={token}- такая ссылка предназначена для использования сервисами, так как является REST методом. Если при получении контента возникли ошибки, то в ответе на запрос будет указан соответствующий код ответа HTTP, а сами ошибки будут указаны в теле формата JSON.
Ссылка содержит следующие параметры:
type- тип контента-
contentID- идентификатор контента, определяемый обработчиком, в форматеbase58(bitcoin)Note
Идентификатор может состоять из нескольких частей, каждая из которых разделяется символом
:. Части могут быть пустыми. -
token- токен доступа
Токен доступа может не содержаться в строке запроса, тогда он должен быть указан в стандартном заголовке Authorization (подробней о том, на что влияет указание токена в строке запроса, в разделе Кэширование возвращаемого контента браузером).
Получение контента по временной ссылке осуществляется в три этапа:
- Выделение уникального токена для доступа к ресурсу. Этот этап происходит в рамках сессии пользователя, и здесь может осуществляться проверка прав на создание временной ссылки на контент.
- Формирование ссылки на контент.
- Получение контента по сформированной ссылке. На этом этапе проверяется валидность переданного токена и возврат запрошенного контента. Для доступа к контенту по ссылке не требуется наличия сессии TESSA, авторизация осуществляется по токену, переданному в запросе.
Внешние временные ссылки на файлы¶
Начиная с версии 4.0.2, в TESSA доступно создание временных внешних ссылок на файлы с использованием механизма токенов доступа к содержимому. Каждый пользователь, у которого есть соответствующий доступ для карточки, входящей в типовое решение, может создать внешнюю ссылку, по которой можно будет загрузить файл. Максимально доступное время действия ссылки ограничивается настройкой сервера Максимальный период действия ссылки на файл.
Important
Формирование внешней ссылки на файл или версию, загрузка данных, а также управление временем действия ссылки, включая её отзыв до истечения срока действия осуществляется при помощи токенов доступа к содержимому системы.
Сформировать ссылку можно только предварительно получив соответствующий токен. Возможность скачивания содержимого файла по внешней ссылке удостоверяется токеном доступа, включаемым в состав ссылки. Запрет скачивания содержимого по выданной ссылке обеспечивается путём отзыва токена доступа удостоверяющего операцию получения содержимого.
Important
Получить токен доступа к файлам/версиям могут только авторизованные в системе пользователи. После получения токена доступа и формирования временной внешней ссылки для загрузки файла/версии авторизация не требуется.
Note
Операции создания токена доступа к файлу, получения содержимого файла и отзыва токена доступа фиксируются в Истории действий.
Подробнее о том как создать внешнюю временную ссылку и отозвать её написано в руководстве пользователя.
Просмотр и управление токенами доступа системы¶
Помимо управления токенами доступа к файлам карточки, для администратора реализована возможность просмотра и управления всеми токенами доступа системы. Помимо файлов, к ним относятся токены аватаров и любые другие, доступные в системе.
Для управления токенами системы реализовано представление Администратор -> Права доступа -> Токены доступа к контенту.
Note
По умолчанию, в нём не задан ни один параметр. Поэтому для отображения данных необходимо задать хотя бы один параметр фильтрации.
В этом представлении также доступна возможность отзыва токена из контекстного меню.