Механизм входа с помощью токенов
Система Документерра предоставляет различные способы управления доступом к контенту портала. Однако в большинстве случаев не стоит заставлять пользователей создавать дополнительный набор учетных данных только для того, чтобы предоставить им доступ к документации. Кроме того, вы можете пожелать, чтобы документация была доступна не для всех.
Поэтому вам необходимо иметь возможность авторизовать пользователей вашего приложения или сервиса на портале в системе Документерра, не заставляя их участвовать в процессе регистрации. Самый безопасный способ сделать это — использовать технологию единого входа (SSO) и, в частности, механизм OpenID Connect для авторизации пользователей по внутренним учетным записям вашего сервиса.
В некоторых ситуациях это может оказаться невозможным, или вы не сможете внедрить технологию единого входа на своей стороне. Например, если вы работаете с десктоп-приложением, которое не требует входа пользователей в систему, и у вас нет конечной точки авторизации в Интернете, подход SSO использовать нельзя. В таких случаях можно использовать другой подход — токены для входа.
Токены для входа
Ваше приложение может создать токен входа для обычного авторизованного читателя, вызвав соответствующий метод API, а затем предоставив ссылки на документацию с этим токеном, включенным в URL-адрес. Ссылка с токеном выглядит следующим образом:
https://myportal.documenterra.co/articles/my-publication/my-topic?t=eyJ0eXAiOiJKV1QiLC
Как видите, в этой ссылке есть только один дополнительный элемент — параметр «t», в качестве значения которого используется токен входа в систему. При использовании такой ссылки портал в системе Документерра автоматически проверит токен и авторизует читателя. Таким образом, вы можете дать ссылку на защищенное паролем руководство пользователя. Включение токена для входа позволит читателю получить доступ к этой странице без ввода пароля.
Токены входа являются одноразовыми, т.е. по умолчанию каждый токен можно использовать только один раз. При желании можно создать многоразовые токены, которые можно использовать несколько раз. Кроме того, по соображениям безопасности у каждого токена есть срок действия, который задается специальным параметром метода создания токенов API. Это означает, что вашему приложению нужно будет время от времени генерировать новые токены для входа в систему для ссылок на документацию.
Поддерживаемые типы ссылок
Вот типы ссылок, которые поддерживают токены в системе Документерра:
- Прямые ссылки на страницы
- Смарт-ссылки
- Ссылки на публикации
- Ссылки с последовательностью символов #!
 |
Примечание |
| При использовании ссылок с последовательностью символов #! параметр token должен быть вставлен перед последовательностью следующим образом: /articles/? t=12345#! my-project/my-topic. |
|
Срок действия токена
Когда кто-то открывает ссылку с токеном, Документерра идентифицирует соответствующего авторизованного читателя (для которого был создан токен) и автоматически авторизует пользователя в текущем сеансе браузера. Если токен создан как одноразовый, он истекает и становится недействительным для использования в будущем — токены имеют ограниченный срок действия. Токены входа становятся недействительными в двух случаях:
- Когда истекает срок его действия.
- Сразу после использования одноразового токена для авторизации.
Обратите внимание, что многоразовый токен для входа можно использовать несколько раз. Если пользователь уже авторизован в сеансе веб-браузера, добавление к ссылке на страницу одноразового токена с истекшим сроком действия или использованного токена не приведет к ошибкам — токен будет проигнорирован.
Если используется действительный одноразовый токен с неистекшим сроком действия и пользователь уже авторизован, токен игнорируется и не истекает. Рекомендуемый подход — генерировать новый токен каждый раз, когда необходимо предоставить пользователю ссылку. Вы также можете получить токен при запуске приложения и использовать его во всех ссылках. В этом случае было бы полезно указать более длительный срок действия токена, поскольку по умолчанию 30 минут может быть недостаточно для того, чтобы конечный пользователь открыл первую ссылку на документацию.
Для получения более подробной информации об истечении срока действия токена, прочитайте следующий раздел: Контроль и истечение срока действия сессии