Документерра позволяет создавать документацию, защищенную паролем. Для доступа к такому контенту читатель должен иметь специальную учётную запись авторизованного пользователя.
При интеграции Документерры с веб-приложением или настольным приложением вы, возможно, захотите упростить процесс для своих пользователей и избежать необходимости создания учетной записи авторизованного читателя для каждого из них. Вероятно, вам нужно, чтобы все пользователи вашего приложения автоматически имели доступ к документации, в то время как все остальные посетители не имели такого доступа. Этот подход можно реализовать с помощью технологии единого входа или с помощью токенов авторизации. При использовании единого входа вы можете добавить параметр idp к URL-адресу, чтобы автоматически инициировать процесс входа через определенного поставщика единого входа. Например, если добавить ?idp=Google к URL-адресу любой страницы с закрытым доступом, пользователи будут перенаправлены в Google для аутентификации без отображения страницы входа в Документерру. Подробнее об этом можно узнать здесь: Вход с использованием параметра idp.
Если единый вход вам не подходит, можно использовать другой подход — одноразовые токены для входа. Рассмотрим этот вариант подробнее. Задача состоит в том, чтобы аутентифицировать пользователя вашего приложения на портале документации без запроса логина и пароля. Если пользователь уже имеет доступ к интерфейсу вашего приложения, этого достаточно для предоставления доступа к документации. Это означает, что ваше приложение должно "сообщить" порталу документации, что посетитель авторизован для доступа к руководствам пользователя.
Технически это требует, чтобы ваше приложение получило токен авторизации с вашего сайта документации и убедилось, что этот токен присутствует в каждой ссылке на документацию, по которой пользователь переходит из интерфейса вашего приложения.
Давайте рассмотрим этот процесс авторизации пошагово, чтобы понять, что происходит, когда посетитель пытается получить доступ к защищенному паролем руководству пользователя.
Процесс авторизации
- Читатель переходит по ссылке на документацию. Поскольку страница находится в рамках руководства с ограниченным доступом, система перенаправляет пользователя на страницу входа в систему Документерра.
- Если ссылка не содержит токен авторизации (например, если пользователь поделился ссылкой), пользовательский скрипт проверяет наличие специального параметра в URL, который указывает, что этот пользователь является автором. Если это так, ничего не происходит, и пользователь остаётся на странице входа для продолжения авторизации.
- Если ссылка не содержит специального параметра "тип пользователя", страница входа автоматически перенаправляет читателя на специальную страницу вашего SaaS-приложения (программное обеспечение как услуга), передавая URL целевой страницы как параметр стороннему ПО.
- На странице стороннего приложения проверяется авторизация пользователя. Если пользователь авторизован, приложение выполняет API-запрос для получения токена входа для текущего пользователя. Стороннее ПО генерирует URL-адрес целевой страницы с токеном в качестве параметра и перенаправляет пользователя на этот URL.
- Документерра проверяет предоставленный токен.
- Если токен действителен, система регистрирует пользователя как авторизованного читателя, и отображается запрашиваемая страница.
- Если токен недействителен (истёк или неверен), или если пользователь не имеет доступа к странице согласно правам доступа, Документерра покажет страницу "В доступе отказано" (Access Denied).
Необходимые изменения
Этот рабочий процесс потребует двух изменений: на странице входа в портал Документерры и в самом приложении.
Страница входа в систему Документерра
В брендинг-скрипте портала в системе Документерра необходимо реализовать функцию, которая будет выполнять следующие действия:
- Обработка события загрузки в окне.
- Проверка, является ли текущая страница страницей входа в систему.
- Проверка наличия в URL специального параметра, который позволяет избежать автопереадресации (чтобы ваши авторы не входили в систему через стороннее приложение). Вы можете назвать этот параметр любым удобным для вас именем.
- Если параметр отсутствует, извлечь из URL значение параметра «ReturnUrl» (это будет URL-адрес страницы в кодировке, к которой пытался обратиться читатель).
- Выполнить перенаправление на стороннее ПО, передав параметр «ReturnUrl» на целевую страницу.
Страница авторизации в вашем приложении
Реализуйте параметр URL, который будет принимать URL целевой страницы, передаваемый на страницу входа в систему при перенаправлении. Логика должна выполнять следующие две операции:
- Выполнить вызов API для получения токена входа в систему от Документерры.
- Перенаправить пользователя на страницу, URL которой был передан на страницу стороннего ПО в качестве параметра, и включить в этот URL токен входа в систему.