Єдиний вхід

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

Так

Точний ідентифікатор проєкту 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

Помилка автентифікації або створення сеансу на сервері.

Чи відповіла ця стаття на ваше запитання?