Токены доступа¶

Для некоторых ресурсов системы необходимо обеспечить доступ извне, причём доступ должен быть контролируемым. Для обеспечения такого доступа в версии 4.0 был разработан механизм токенов доступа. Токен удостоверяет возможность доступа субъекта, предоставляющего токен, к соответствующему ресурсу (части системы и/или хранимому в ней содержимому). Это может быть как доступ к объекту данных (файл, аватар и др.), так и части API системы, который в противном случае требовал бы полной авторизации и аутентификации пользователя. Таким образом токены являются механизмом делегирования и удостоверения полномочий для целевого пользователя и/или смежной системы от имени лица, выдавшего токен.

Общая информация¶

Контроль доступа к системе осуществляется с помощью специального токена доступа, который передаётся на клиент в составе следующей структуры:

Поле	Тип данных	Описание
`Token`	`string`	Токен доступа, который используется клиентом при осуществлении доступа к системе и удостоверяет права доступа
`Scope`	`string`	Область действия (скоуп) токена, который используется для валидации токена при осуществлении доступа к системе
`Expires`	`DateTime`	Окончание срока действия токена
`Hash`	`string`	Шестнадцатеричное строковое представление хэша токена

В БД информация о токенах доступа хранится в таблице Tokens, которая имеет следующую структуру:

Поле	Тип данных	Описание
`ID`	`String(128) Not Null`	Уникальный идентификатор токена
`Description`	`String(Max) Not Null`	Описание токена, устанавливается обработчиком, выдавшим токен в соответствии с его логикой работы
`Scope`	`String(256) Not Null`	Область действия (скоуп) токена
`Created`	`DateTime Not Null`	Дата и время создания токена
`Expires`	`DateTime Not Null`	Дата и время окончания действия токена
`CreatedByID`	`Guid Not Null`	Идентификатор сотрудника, создавшего токен
`RefID`	`Guid Null`	Идентификатор ресурса, к которому относится этот токен (может быть не заполнено). Для файлов - идентификатор файла, для версий файлов - идентификатор версии файла
`UserID`	`Guid Null`	Идентификатор сотрудника, для которого был создан токен (может быть не заполнено)
`Options`	`Json Null`	Дополнительная информация по токену в формате `json` (может быть не заполнено)
`FormatID`	`Int32 Not Null`	Идентификатор формата хранения токена из перечисления TokenFormats
`TypeID`	`Int32 Not Null`	Идентификатор типа токена из перечисления TokenTypes. По умолчанию `0` (общий)
`TokenHash`	`Binary(32) Not Null`	Хеш токена
`Signature`	`Binary(32) Not Null`	Подпись токена

Note

Поля токена не могут быть изменены после его создания.

Поддерживаются следующие форматы хранения токенов (TokenFormats):

Открытые (Plain) - используются для доступа к нечувствительным данным.
Защищённые (Protected) - используются для доступа к чувствительным данным системы (файлы и т.п.).

Important

Для Plain токенов в поле с уникальным идентификатором ID записывается актуальный токен доступа к ресурсу. Для Protected токенов в поле ID хранится уникальный идентификатор токена, не совпадающий с актуальным токеном доступа к ресурсу. При этом сам токен доступа не хранится в БД.

Important

Для всех форматов токенов вычисляется хэш по токену доступа (поле TokenHash) и подпись (поле Signature) по полям: FormatID, TypeID, Scope, Description, Created, Expires, RefID, UserID, Options в которые включается актуальное значение токена доступа.

Important

Формат хранения токенов для предоставляемого ресурса выбирается исходя из задачи и не может быть различным для ресурса одного и того же типа.

Поддерживаются следующие типы токенов (TokenTypes):

Content - тип токена для доступа к объектам данных системы, которые не имеют собственной классификации или предназначены для общего использования. Это могут быть данные, медиафайлы, документация и другие элементы, которые не привязаны к конкретным категориям, таким как аватары или файлы.
Avatar - тип токена для доступа к аватарам. Это подтип Content-токенов, которые выделяются для пользователя в единственном экземпляре в рамках единственного скоупа. При запросе токена будет возвращён уже существующий токен, если срок его действия ещё не истёк, в противном случае выделяется новый токен. Могут храниться только в открытом виде (Plain), так как должна быть возможность возвращать токен после его создания в течение некоторого периода. Такие токены актуальны для множества однотипных ресурсов, для каждого из которых не требуется обеспечить отдельный доступ.
File - тип токена для доступа к файлам. Это подтип Content-токенов, которые используются для доступа к файлам (или версиям файлов) по ссылке. Такие токены выделяются каждый раз, когда нужно сформировать ссылку на объект данных. Актуальны в случае, когда к каждому ресурсу в рамках одного типа нужно обеспечить доступ отдельно.
Api - тип токена для доступа к части API системы. Такие токены выделяются администратором системы для внешних интеграционных сервисов, которые взаимодействуют с платформой с использованием RESTful API. В токене хранится вся необходимая информация для авторизации запроса и его логирования в журнале аудита (истории действий).
SaaS - тип токена для доступа к API SaaS. Это подтип Api-токенов, которые используются в интеграции с внешними сервисами на платформе SaaS.
Common - тип токена для доступа к общим ресурсам. Этот тип используется для доступа к части системы и/или её содержимому, не относящемуся ни к одной из других категорий токенов. Такие ресурсы могут включать в себя административные инструменты, настройки системы, а также другие данные. Токены типа Common обеспечивают базовый доступ, часто используются в случаях, когда ресурсы являются универсальными и не требуют специфической авторизации.

Срок действия токена выбирается для каждого типа токена индивидуально, исходя из принципов безопасности и необходимости кэширования предоставляемого ресурса (подробнее в разделе Кэширование возвращаемого контента браузером).

Скоуп может содержать несколько значений и не совпадать с типом токена.

Important

Общая длинна всех значений скоупа не должна превышать 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 - идентификатор контента, определяемый обработчиком
token - токен доступа

Токен доступа может не содержаться в строке запроса, тогда он должен быть указан в стандартном заголовке Authorization (подробней о том, на что влияет указание токена в строке запроса, в разделе Кэширование возвращаемого контента браузером).

Important

Если токен доступа не содержится в ссылке, то её нельзя будет передавать целевым пользователям/системам для получения доступа, поскольку удостоверение на выполнение соответствующей операции (в виде токена) отсутствует.

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

Выделение уникального токена для доступа к объекту данных. Этот этап происходит в рамках сессии пользователя, и здесь может осуществляться проверка прав на создание временной ссылки на контент.
Формирование ссылки на контент.
Получение контента по сформированной ссылке. На этом этапе проверяется валидность переданного токена и возврат запрошенного контента. Для доступа к контенту по ссылке не требуется наличия сессии TESSA, авторизация осуществляется по токену, переданному в запросе.

Important

Для токенов доступа к API запросы на получение контента не поддерживаются.

Внешние временные ссылки на файлы¶

Начиная с версии 4.0.2, в TESSA доступно создание временных внешних ссылок на файлы с использованием механизма токенов доступа. Каждый пользователь, у которого есть соответствующий доступ для карточки, входящей в типовое решение, может создать внешнюю ссылку, по которой можно будет загрузить файл. Максимально доступное время действия ссылки ограничивается настройкой сервера Максимальный период действия ссылки на файл.

Important

Формирование внешней ссылки на файл или версию, загрузка данных, а также управление временем действия ссылки, включая её отзыв до истечения срока действия осуществляется при помощи токенов доступа к содержимому системы.

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

Important

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

Note

Операции создания токена доступа к файлу, получения содержимого файла и отзыва токена доступа фиксируются в Истории действий.

Подробнее о том как создать внешнюю временную ссылку и отозвать её написано в руководстве пользователя.

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

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

Для управления токенами системы реализовано представление Администратор → Права доступа → Токены доступа.

Note

По умолчанию, в нём не задан ни один параметр. Поэтому для отображения данных необходимо задать хотя бы один параметр фильтрации.

В этом представлении также доступна возможность отзыва токена из контекстного меню.

Просмотр и управление токенами доступа к API¶

Начиная с версии 4.1, в TESSA доступно создание токенов доступа к API с использованием механизма токенов доступа. Для администратора доступен просмотр и управление токенами доступа к API из представления, в котором отображаются все токены с основной информацией по ним. Диалоговое окно с представлением открывается из меню системы: Настройки → Токены доступа к API.

Note

В представлении реализован быстрый поиск, в который могут быть переданы “Идентификатор токена”, “Хэш” или сам токен.

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

Создать токен - открывает диалог с параметрами токена для его создания.
Отозвать токен - выполняет отзыв выделенного в представлении токена с его последующим удалением.
Посмотреть историю действий - отображает диалог с записями из истории действий системы, относящимися к выделенному в представлении токену.

Создание токена¶

По нажатию на кнопку будет отображён диалог с параметрами создаваемого токена.

Описание - краткое описание токена в соответствии с его логикой работы. Поле обязательно для заполнения.
Область действия - область действия (скоуп) токена. Используется для валидации токена при проверке доступа к API системы. Представлено в виде списка уникальных значений. Поле обязательно для заполнения.

Tip

При добавлении/удалении скоупов, зарезервированных системой (api-read, api-write), автоматически будут установлены/сняты признаки API: чтение, API: запись.
API: чтение - признак наличия/отсутствия скоупа api-read.
API: запись - признак наличия/отсутствия скоупа api-write.

Important

Скоуп api-write предоставляет доступ к API как для чтения, так и для записи.
Действителен до - дата окончания действия токена. Если дата действия не указана, будет создан токен со сроком действия 3 года от момента создания.

Note

Для выбранного значения даты будет автоматически сформировано время в формате UTC как 23:59:59.
Доступ только из подсети - маска подсети, в соответствии с которой будет выполнена проверка доступа к API для IP-адреса источника запроса.

Note

Маска подсети должна быть задана в формате IPv4 или IPv6 в соответствии со стандартом CIDR.
Пользователь - ссылка на сотрудника, чья учётная запись будет использована для взаимодействия с API платформы. Если пользователь не задан, то будет использоваться учётная запись System.

Important

Убедитесь, что для выбранного пользователя настроены правила доступа для выполнения операций над объектами системы в том числе и для пользователя System.
Язык - ссылка на язык, используемый системой в объектах, которые применяют форматирование и локализацию.

Note

Язык не связан с выбранным пользователем.
Временная зона - ссылка на временную зону, используемую системой в объектах, которые применяют форматирование и временные смещения.

Note

Временная зона не связана с выбранным пользователем.

После успешного создания токена будет отображён диалог, в котором можно отобразить/скрыть созданный токен, а также скопировать его в буфер обмена.

Important

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

Просмотр информации о токене доступа¶

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

В окне будут также отображены:

Хэш токена - шестнадцатеричное строковое представление хэша токена.
Идентификатор токена - уникальный идентификатор токена в формате UUID.

Tip

Идентификатор можно использовать в представлении История действий для фильтрации событий системы, которые были выполнены с использованием токена.
Активность - дата и время последней активности по токену.
Создано - сотрудник, создавший токен.
Дата создания токена - дата и время создания токена.

Отзыв токена доступа¶

Для отзыва токена необходимо выбрать строку в представлении с токеном доступа к API и либо в нижнем тулбаре представления, либо с помощью вызова контекстного меню строки выбрать опцию Отозвать токен. Отобразится диалоговое окно с необязательным полем для ввода комментария (причины отзыва токена).

Доступ к API системы по токену¶

После того как администратор передал токен доступа внешнему сервису, его можно использовать для доступа к API системы.

Для этого в запросе к системе необходимо указать токен в стандартном заголовке Authorization

curl -X 'POST' \
  'http://localhost/api/v1/cards/get' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer NVH4AVES4LHyCVCGaAbTBL' \
  -d '{ "CardID:uuid": "3db19fa0-228a-497f-873a-0250bf0a4ccb" }'

Также, токен может располагаться и в параметре строки запроса (обычно параметр token), если соответствующее API поддерживает получение токена в качестве query-параметра

curl -X 'GET' \
  'http://localhost:5000/service/data-with-api-token?p=test&token=NVH4AVES4LHyCVCGaAbTBL' \
  -H 'accept: text/plain'

Объекты API для взаимодействия с токенами доступа¶

В платформе определены следующие сущности для построения механизма токенов доступа:

ITokenInfo - объект, содержащий информацию о токене. На данный момент используется единственная реализация - TokenInfo.
AccessTokenInfo - объект, содержащий основную информацию о токене доступа.
TokenFormat - перечисление с форматами токенов доступа.
TokenType - перечисление с типами токенов доступа.
TokenScope - объект, содержащий информацию об области действия (скоуп) токена.
TokenOptions - дополнительная информация по токену, сериализуемая в формат json.
TokenInfoBuilder - объект для удобного и динамичного создания объекта ITokenInfo. Для создания строителя используется зависимость TokenInfoBuilderFactory, которую можно получить из Unity-контейнера.
ITokenCache - потокобезопасный кэш токенов доступа в памяти процесса. Для него имеются две реализации - кэш без ограничения по количеству хранимых токенов (TokenInMemoryCache) и кэш с ограничением количества хранимых токенов (TokenInMemoryLruCache - данный кэш реализует механизм LRU (Least Recently Used) для хранения наиболее актуальных токенов по времени их использования).
PlatformResourceTypes - объект с набором платформенных типов ресурсов.
PlatformTokenScopes - объект с набором платформенных скоупов токена.

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

IAccessTokenProvider - предоставляет методы для создания и возврата токена доступа.
IAccessTokenProviderResolver - выполняет получение зависимости IAccessTokenProvider по заданному типу токена.
IAccessTokenGenerator - генерирует уникальные токены доступа и выполняет их валидацию.
ITokenActionHistoryStrategy - стратегия, предоставляющая возможность записи в историю действий событий, связанных с токеном доступа (создание токена, отзыв токена, получение контента по токену и др.).
ITokenRepository - репозиторий для управления токенами доступа. Предоставляет методы для получения, сохранения и удаления токенов.
ITokenRepositoryCached - расширение над ITokenRepository с возможностью кэширования токенов для быстрого доступа к ним.
ITokenRevokingStrategy - стратегия, предоставляющая возможность отзыва и удаления токена по заданным параметрам. Реализация по умолчанию использует ITokenRepositoryCached для удаления токена из кэша и основного хранилища, а также ITokenActionHistoryStrategy для записи события отзыва токена в истории действий.
ITokenSignatureProvider - предоставляет методы подписания и проверки подписи для данных токена.
IContentProvider - предоставляет методы для получения запрашиваемого контента конкретного типа по токену доступа.
IContentProviderResolver - выполняет получение зависимости IContentProvider по заданному типу контента.

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