Единый вход

Shayan TaslimОбновлено

Единый вход (SSO) заменяет стандартный процесс входа на вашей публичной доске. Когда посетители нажимают Войти, UserJot перенаправляет их на вашу конечную точку аутентификации, а вы перенаправляете их обратно с подписанным JWT HS256.

Режимы входа на доску (По умолчанию, SSO и Отключен) доступны в плане Professional.

Включить SSO

  1. Откройте Настройки → Вход.

  2. В разделе Аутентификация установите для параметра Вход на доску значение SSO.

  3. В диалоговом окне Включить SSO введите URL перенаправления HTTPS и нажмите Включить SSO. Позже URL можно изменить в разделе URL перенаправления SSO (чтобы полностью очистить URL перенаправления, сначала отключите Вход на доску в разделе SSO).

  4. Скопируйте идентификатор проекта и секрет проекта из раздела Секреты.

URL перенаправления должен использовать https:// (для локального тестирования используйте HTTPS-туннель).

Режимы входа на доску

  • По умолчанию: посетители входят в систему с помощью стандартных учетных записей UserJot.

  • SSO: При нажатии Войти посетители перенаправляются на вашу конечную точку SSO. Обычные аккаунты конечных пользователей UserJot не могут войти напрямую, пока активно SSO (браузеры с существующей сессией UserJot, не связанной с командой, на доске, где доступен только SSO, считаются анонимными, а не переводятся в режим гостя). Владельцы рабочих пространств и администраторы могут войти как с помощью своих аккаунтов UserJot, так и через перенаправление SSO (при использовании SSO их существующая роль в команде сохраняется, traits и companies синхронизируются, а имя, аватар и адрес электронной почты, настроенные через панель управления, остаются без изменений).

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

Как работает перенаправление SSO

Когда посетитель нажимает Войти, UserJot открывает всплывающее окно входа (если всплывающие окна заблокированы, используется перенаправление в той же вкладке) с переходом на настроенный вами URL и параметрами запроса state и redirect:

text
https://yourapp.com/userjot/sso?state=OPAQUE_STATE_FROM_USERJOT&redirect=https%3A%2F%2Fapi.userjot.com%2Fauth%2Fsso

Ваша конечная точка должна лишь сохранить state:

  1. Прочитать параметр запроса state.

  2. Аутентифицируйте пользователя в своем приложении (если пользователь еще не вошел в систему, направьте его через процесс входа и верните на эту конечную точку с исходным значением state).

  3. Подпишите JWT HS256 с помощью секрета проекта.

  4. Перенаправьте браузер на https://api.userjot.com/auth/sso?jwt=<JWT>&state=<STATE>.

Не изменяйте state. Его можно использовать только один раз, он привязан к сеансу браузера и истекает через 15 минут.

Полезная нагрузка JWT

Подпишите токен с помощью HS256, используя свой Секрет проекта (храните секрет на сервере, никогда не размещайте его в клиентском коде). Передача email связывает пользователя с существующим аккаунтом UserJot, только если адрес электронной почты этого аккаунта подтверждён (или если пользователь уже состоит в команде либо привязан с помощью externalId).

Утверждение

Обязательное

Описание

sub

Да

Стабильный идентификатор пользователя в вашей системе

iss

Да

Точный ID проекта UserJot

aud

Да

Точная строка userjot

exp

Да

Время истечения срока действия в формате Unix (рекомендуется от 5 до 15 минут)

iat

Нет

Время выпуска в формате Unix (не должно быть в будущем с учетом погрешности часов)

email

Нет

Адрес электронной почты пользователя (рекомендуется для связывания учетных записей по электронной почте и уведомлений)

firstName

Нет

Имя

lastName

Нет

Фамилия

avatar

Нет

URL аватара

traits

Нет

Плоская карта «ключ — значение» со строками, числами, логическими значениями или null

companies

Нет

Массив членств в компаниях

Пример данных:

JavaScript
const now = Math.floor(Date.now() / 1000);

const payload = {
  sub: 'user_123',
  email: 'jane@example.com',
  firstName: 'Jane',
  lastName: 'Doe',
  iss: 'YOUR_PROJECT_ID',
  aud: 'userjot',
  iat: now,
  exp: now + 10 * 60
};

Данные компании

JSON
{
  "companies": [
    {
      "id": "company_456",
      "name": "Acme Corp",
      "domain": "acme.com",
      "logo": "https://example.com/acme.png",
      "traits": {
        "plan": "enterprise",
        "seats": 42
      }
    }
  ]
}

Пример конечной точки (Hono)

JavaScript
import { Hono } from 'hono';
import jwt from 'jsonwebtoken';

const app = new Hono();

const USERJOT_PROJECT_ID = process.env.USERJOT_PROJECT_ID;
const USERJOT_PROJECT_SECRET = process.env.USERJOT_PROJECT_SECRET;
const USERJOT_CALLBACK_URL = 'https://api.userjot.com/auth/sso';

app.get('/userjot/sso', async (c) => {
  const state = c.req.query('state');
  if (!state) return c.text('Missing state', 400);

  const user = await getCurrentUser(c);

  const token = jwt.sign(
    {
      sub: user.id,
      email: user.email,
      firstName: user.firstName,
      lastName: user.lastName,
      iss: USERJOT_PROJECT_ID,
      aud: 'userjot'
    },
    USERJOT_PROJECT_SECRET,
    { algorithm: 'HS256', expiresIn: '10m' }
  );

  const callback = new URL(USERJOT_CALLBACK_URL);
  callback.searchParams.set('jwt', token);
  callback.searchParams.set('state', state);

  return c.redirect(callback.toString());
});

Ротация секрета проекта

Если нажать Отозвать секрет в разделе Настройки → Вход → Секреты, UserJot немедленно создаст новый секрет проекта. Сразу обновите конечную точку SSO, а также все компоненты для подписи подписанной идентификации и Swift SDK, поскольку токены, подписанные старым секретом, немедленно перестанут работать.

Решение проблем

В стандартном сценарии со всплывающим окном ошибки обратного вызова передаются доске и отображаются в модальном окне входа. Если браузер использует перенаправление в той же вкладке (например, когда всплывающие окна заблокированы), UserJot перенаправляет пользователя обратно на доску с параметром запроса sso_error:

Код ошибки

Значение

invalid_state

Значение state отсутствует, изменено, срок его действия истек (прошло более 15 минут) или оно уже использовано.

invalid_token

Несоответствие подписи, неверный iss/aud, отсутствует sub/exp или срок действия JWT истек.

sso_disabled

Параметр Вход на доску больше не установлен в значение SSO.

config_error

Конфигурация SSO рабочего пространства неполная (отсутствует URL перенаправления или секрет).

invalid_return_to

Проверка URL возврата после входа не пройдена.

auth_failed / session_error

Не удалось выполнить аутентификацию или создать сеанс на сервере.

Эта статья ответила на ваш вопрос?