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