Настройте единый вход (SSO) для вашего справочного центра.

Для авторизации читателей в вашем справочном центре используйте URL-адрес единого входа (SSO), Messenger или перенаправление с вашего сервера.

2 мин чтения

Когда незарегистрированный пользователь открывает ваш справочный центр, Notiondesk перенаправляет его на страницу вашего приложения, ваш URL-адрес SSO. На этой странице пользователь авторизуется через Messenger или путем перенаправления с вашего сервера, и он возвращается на запрошенную страницу без повторной авторизации.

Быстрый способ: перейдите в «Настройки» > «Доступ» , выберите «Гостевые учетные записи» , затем введите адрес страницы вашего приложения в поле «URL-адрес единого входа» .

Прежде чем начать

  • В вашем справочном центре используется режим доступа для гостевых учетных записей .
  • У вас есть секретный ключ приложения. Создайте его в разделе «Настройки» > «Доступ» , в карточке «Секретный ключ приложения» . Он отображается только один раз, поэтому сохраните его на своем сервере, например, в папке NOTIONDESK_APP_SECRET.
  • Ваш сервер может подписать токен пользователя. Идентифицируйте авторизованных пользователей в Notiondesk. Messenger объясняет значение токена. В разделе «Настройки > Виджет» карточка «Синхронизация информации о пользователе» предоставляет код подписи на Node.js, Python, PHP и Ruby, с заполненным значением site_uuid. Сохраните это значение site_uuid также на вашем сервере, например, в NOTIONDESK_SITE_UUID.
Никогда не подписывайте токен в браузере. Любой, кто знает ваш секретный ключ приложения, может войти в систему как любой пользователь вашего справочного центра.

Шаг 1: Добавьте URL-адрес вашей системы единого входа (SSO).

  1. Перейдите в Настройки > Доступ .
  1. В разделе «Управление доступом» установите режим доступа на «Гостевые учетные записи» . Он сохранится сразу после выбора.
  1. В поле «URL SSO» введите адрес страницы вашего приложения, которая выполняет вход для пользователей, например, https://app.example.com/help-sso.
  1. Нажмите «Сохранить изменения» .

URL для единого входа (SSO) должен начинаться с https://, использовать доменное имя (не localhost) и быть страницей вашего приложения, а не вашего центра поддержки. Если ваш центр поддержки находится на вашем собственном домене, используйте другой хост или тот же хост вне пути центра поддержки: если ваш центр поддержки находится по адресу example.com/help, то example.com/login подойдет.

Когда Notiondesk перенаправляет читателя на ваш URL-адрес SSO, он сохраняет вашу собственную строку запроса и добавляет return_to, полный адрес страницы справочного центра, которую запросил читатель. Он также добавляет два параметра, используемых Messenger. Оставьте их в URL-адресе.

Шаг 2: Войдите в систему на странице единого входа (SSO) для читателей.

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

Вариант А: через мессенджера

Используйте этот вариант, если ваше приложение уже использует Messenger. На странице единого входа (SSO) загрузите Messenger с токеном пользователя, вошедшего в систему. Messenger авторизует читателя в вашем справочном центре и перенаправит его обратно на запрошенную страницу. Больше ничего вызывать не нужно.

Убедитесь, что ваша страница единого входа (SSO):

  • Сначала авторизует пользователя в вашем приложении. Посетитель без токена пользователя не авторизуется в центре поддержки.
  • Загружает Messenger из справочного центра, с которого пришел читатель, с токеном, подписанным секретным ключом приложения этого справочного центра.
  • Подписывает токен при загрузке страницы, срок его действия составляет один час или меньше. Истечение срока действия позже отклоняется.
  • Открывается как обычная страница, а не внутри фрейма, и не устанавливает параметр apiUrl в Messenger.
  • Сохраняет полный адрес, с которого был открыт сайт. Если при входе в систему пользователь сначала переходит на другой сайт или вкладку, верните его на тот же адрес со всеми его параметрами, прежде чем загрузится Messenger.

В разделе «Вход» справочного центра документации Messenger SDK описаны способы установки React, Vue и тегов <script>.

Вариант B: с перенаправлением с вашего сервера.

Используйте этот вариант, если ваше приложение не поддерживает Messenger или если вы предпочитаете авторизовывать читателей на своем сервере.

  1. На странице единого входа (SSO) прочитайте return_to из адреса и сохраните его при входе в систему.
  1. На вашем сервере подпишите токен пользователя для авторизованного пользователя, используя ваш секретный ключ приложения.
  1. Перенаправьте браузер на адрес https://help.example.com/private/sso/jwt?jwt=TOKEN&return_to=RETURN_TO, указав домен вашего справочного центра, токен и return_to, оба значения должны быть закодированы в формате URL. Если справочный центр находится по адресу example.com/help, адрес будет начинаться с https://example.com/help/private/sso/jwt.

Вот пример на Node.js с использованием Express. requireLogin обозначает вашу собственную проверку авторизации: она отправляет пользователя, не вошедшего в систему, на вашу страницу авторизации, а затем обратно по этому адресу с его строкой запроса.

Помните об этих правилах:

const jwt = require('jsonwebtoken');

const HELP_CENTER_URL = 'https://help.example.com';

app.get('/help-sso', requireLogin, (req, res) => {
  const now = Math.floor(Date.now() / 1000);
  const token = jwt.sign(
    {
      type: 'site_contact_app',
      iat: now,
      exp: now + 300,
      user_id: String(req.user.id),
      site_uuid: process.env.NOTIONDESK_SITE_UUID,
      email: req.user.email,
      name: req.user.name,
    },
    process.env.NOTIONDESK_APP_SECRET,
    { algorithm: 'HS256' },
  );

  const target = new URL(`${HELP_CENTER_URL}/private/sso/jwt`);
  target.searchParams.set('jwt', token);
  if (req.query.return_to) {
    target.searchParams.set('return_to', req.query.return_to);
  }
  res.redirect(target.toString());
});
  • Для каждого перенаправления необходимо подписывать новый токен. Токен выполняет авторизацию читателя только один раз.
  • Установите короткий срок действия. 5 минут достаточно, а срок более часа не допускается. Поддерживайте синхронизацию серверных часов: допускается разница до 60 секунд.
  • Размер токена не должен превышать 8 КБ, поэтому любой custom_attributes должен быть небольшим.
  • Передайте return_to обратно без изменений. Без него или с адресом, не относящимся к вашему справочному центру, читатель попадет на главную страницу справочного центра.
  • Перенаправление с вашего сервера. Никогда не размещайте эту ссылку в электронных письмах, поскольку токен содержится в адресе.

Вы также можете перенаправлять пользователей непосредственно на этот адрес из вашего приложения без использования URL-адреса SSO, например, через ссылку «Справка» в меню вашего приложения. Установите значение return_to равным странице справочного центра, которую вы хотите, чтобы они открыли.

Шаг 3: Протестируйте.

  1. Откройте окно браузера в режиме инкогнито и перейдите на страницу вашего справочного центра, для доступа к которой требуется авторизация.
  1. Убедитесь, что вы попали на URL-адрес вашей системы единого входа (SSO), вошли в приложение и вернулись на ту же страницу справочного центра, уже авторизованные.

Если это не сработает, проверьте токен, подписанный вашим приложением:

  1. В разделе «Настройки» > «Доступ» , в подразделе «URL-адрес SSO» , нажмите «Проверить токен входа» . Эта кнопка появится после сохранения URL-адреса SSO.
  1. Вставьте токен, затем нажмите «Проверить токен» . Вы увидите, принимает ли его ваш справочный центр и почему. Токен проверяется и никогда не сохраняется.

Выберите, когда читатели переходят по вашей ссылке для единого входа (SSO).

Переключатель «Требовать авторизацию» , расположенный над полем «URL-адрес SSO» , включен по умолчанию. При его включении каждый незарегистрированный пользователь будет переходить по вашему URL-адресу SSO при открытии справочного центра.

Если эта функция отключена, любой может просматривать ваш справочный центр, и только эти пользователи будут перенаправлены на ваш URL-адрес SSO:

  • Читатели, открывшие статью, для доступа к которой требуется авторизация.
  • Читатели, перешедшие по ссылке в справочный центр, заканчивающейся на nd_sign_in=1, например, https://help.example.com/en/articles/billing?nd_sign_in=1, могут добавить её в список ссылок справочного центра вашего приложения.
  • Читатели, которые нажимают кнопку «Продолжить с вашей учетной записью» на странице входа в справочный центр.

Приглашенные вами гости по-прежнему могут выбрать опцию «Использовать электронную почту и пароль» на странице входа в систему.

Разместите ссылки на гостевые аккаунты, которые вы пригласили, чтобы читатели могли перейти по ним.

Токен для пользователя, которого вы никогда не приглашали, позволяет ему войти в систему как новому читателю. Чтобы предоставить пользователю доступ и роль гостевой учетной записи, которую вы пригласили по электронной почте:

  • Включите в токен пользователя email при первой идентификации. Пользователь, идентифицированный без этого параметра, сохраняет отдельный читательский аккаунт без доступа гостевой учетной записи, даже если вы добавите адрес электронной почты позже.
  • Если ваше приложение не подтвердило адрес электронной почты пользователя, отправьте email_verified: false. Этот пользователь не связан с гостевой учетной записью. Если вы его не укажете, адрес электронной почты будет считаться подтвержденным. Отправьте его как true или false, а не как текст: значение типа "true" будет считаться как false.
  • Гостевая учетная запись привязана к одному user_id. Второй пользователь, вошедший в систему с тем же адресом электронной почты, сохраняет отдельный читательский аккаунт.

Если приглашение гостя еще не отправлено, оно принимается автоматически.

Поиск неисправностей

Проблема Причина Исправить
Читатель попадает на страницу входа с сообщением: «Нам не удалось выполнить автоматический вход. Попробуйте еще раз или войдите ниже». Токен был отклонен: срок его действия истек, он уже был использован, срок действия истекает более чем через час, или он был подписан с помощью другого секретного ключа приложения. Выполните проверку токена авторизации и подпишите новый токен для каждого перенаправления.
Читатель остается на вашей странице единого входа (SSO). В мессенджере отсутствовал пользовательский токен или он был недействителен, адрес потерял свои параметры во время входа в систему, страница находится во фрейме или установлен флаг apiUrl. Выполните проверку токена входа и выберите пункт «Вариант A» в списке.
Читатель авторизован, но попадает на главную страницу. Страница return_to отсутствует или не является страницей вашего справочного центра. Передайте return_to обратно без изменений
Читатели никогда не перенаправляются на ваш URL-адрес SSO. URL-адрес SSO не сохранен, или параметр «Требовать авторизацию» отключен. Сохраните URL-адрес SSO, затем добавьте nd_sign_in=1 к ссылкам вашего справочного центра или включите параметр «Требовать авторизацию».
При сохранении введите URL-адрес, начинающийся с https://. URL-адрес SSO не является адресом https:// Используйте адрес страницы вашего приложения, указанный в поле https://.
«Перейдите на страницу вашего приложения, а не в справочный центр», — при сохранении. URL-адрес SSO находится по адресу вашего справочного центра. Воспользуйтесь другим хостом или путем, отличным от центра поддержки.
При проверке токена авторизации отображается сообщение "Этот токен пока недействителен". iat — это значение в миллисекундах, или же время вашего сервера опережает заданное. Используйте секунды и синхронизируйте часы сервера.
Читатель не получит доступ к гостевой учетной записи, которую вы пригласили. Токен изначально не содержал email, или email_verified отсутствует. __СОХРАНЕНО_2__ См. раздел «Ссылка для читателей на гостевые аккаунты, которые вы пригласили» выше.

Часто задаваемые вопросы

Читатели заходят в систему дважды?

Нет. Пользователи, вошедшие в ваше приложение, проходят через ваш URL-адрес SSO и возвращаются в систему без авторизации с помощью Notiondesk.

Какой вариант мне следует выбрать?

Вариант А, если ваше приложение уже использует Messenger на странице, которую вы контролируете. Вариант Б, если это не так, или если авторизация осуществляется на вашем сервере.

Могут ли читатели по-прежнему входить в систему, используя адрес электронной почты и пароль?

Да. Приглашенные вами гости могут выбрать опцию «Использовать электронную почту и пароль» на странице входа в справочный центр.

Как долго читатель остается в системе?

До 12 часов. Выход из приложения не приводит к выходу из центра поддержки, поэтому имейте это в виду на компьютерах, используемых совместно.

Кто может изменить URL-адрес SSO?

Владельцы рабочих пространств, администраторы и редакторы.

Как отключить единый вход (SSO)?

Очистите поле URL-адреса SSO и нажмите «Сохранить изменения» . После этого пользователи смогут войти в систему, используя свой адрес электронной почты и пароль.

Связанные статьи

Эта страница была полезной?

Still need help? Ask us