Створити підписаний JSON Web Token (JWT)

Що таке JWT Builder?

JWT Builder — онлайн-інструмент, що виробляє підписаний JSON Web Token (JWT) з payload JSON і HMAC-секрету. Він призначений для розробників, яким потрібно швидко згенерувати тестовий токен для перевірки поведінки API, симулювання автентифікованої сесії в Postman або відтворення помилки, пов'язаної з терміном дії або областю токена.

На відміну від нашого JWT decoder, який лише зчитує наявний токен, JWT Builder створює повний токен: будує заголовок, кодує payload, обчислює HMAC-підпис і збирає все у компактний формат header.payload.signature, очікуваний усіма JWT-бібліотеками ринку.

Навіщо генерувати JWT?

JWT builder не призначений для емісії виробничих токенів. Це насамперед інструмент розробки та тестування. Ось найпоширеніші сценарії:

• Інтеграційне тестування: генерувати передбачувані JWT для керування E2E-тестами, що звертаються до захищених ендпоінтів без залежності від справжнього провайдера ідентифікаційних даних.
• Моки API: тимчасово замінити дзвінок до IdP JWT-токеном, підписаним локально з тим самим тестовим секретом.
• Локальна розробка: підключитися до власного бекенда, вручну генеруючи токен з потрібними claims, без проходження всього OAuth2 flow.
• Демонстрації: проілюструвати процес автентифікації або workflow на основі дозволів без реального IdP під рукою.
• Відтворення помилок: підробляти прострочений токен, токен з неправильним aud, токен без певних claims, щоб тестувати шляхи помилок вашого API.
• Налагодження кастомного парсера: впроваджувати спеціально побудовані JWT для тестування власного JWT-парсера.

Склад JWT

Підписаний JWT складається з трьох сегментів, розділених крапками, кожен закодований у Base64URL (варіант Base64 без padding та з -/_ замість +//):

• Header: JSON-об'єкт, що описує алгоритм підпису і тип токена, наприклад {"alg":"HS256","typ":"JWT"}. JWT Builder генерує його автоматично на основі вибраного алгоритму.
• Payload: довільний JSON-об'єкт, що містить claims токена (суб'єкт, дозволи, дати закінчення терміну дії). Це частина, яку ви надаєте.
• Signature: HMAC-SHA, обчислений на конкатенації base64url(header) + "." + base64url(payload) з вашим секретним ключем. Саме він гарантує цілісність токена.

Детальні випадки використання

• API mock для E2E тестів: ваш набір Cypress або Playwright має викликати API, що вимагає Authorization: Bearer .... Замість повної організації входу для кожного тесту, підписуємо JWT на льоту зі спільним секретом і впроваджуємо його в заголовок.
• Демонстрація SSO: представлення процесу федеративної автентифікації без залежності від онлайн-IdP.
• Тестові fixture: генерувати детермінований JWT з відомого payload для використання як стабільна fixture в юніт-тестах.
• Діагностика кастомного парсера: тестувати власний JWT-парсер зі спеціально мінімальними або навмисно незвичайними токенами (відсутні claims, несподівані типи).
• Навчання: конкретно зрозуміти, як будується JWT, змінюючи payload і спостерігаючи, як змінюється підпис.

Підтримувані алгоритми: HS256, HS384, HS512

Наш інструмент підтримує три стандартні алгоритми HMAC специфікації JWT (RFC 7519):

• HS256: HMAC з SHA-256. Підпис 32 байти. Найпоширеніший на практиці, хороший компроміс між швидкістю та криптографічною надійністю. Рекомендовано за замовчуванням.
• HS384: HMAC з SHA-384. Підпис 48 байт. Підходить для контекстів, що вимагають більшого запасу безпеки.
• HS512: HMAC з SHA-512. Підпис 64 байти. Найнадійніший, за рахунок дещо більшого токена.

HMAC чи RSA?

Алгоритми HS* є симетричними: той самий ключ служить для підпису та перевірки. Це просто і швидко, але означає, що будь-який сервіс, здатний перевірити токен, також здатний його емітувати. Якщо вам потрібно розділити ці дві ролі (один емітент, кілька споживачів), зверніться до алгоритмів RS256/RS384/RS512 (RSA, асиметричних), які можна перевірити за допомогою нашого JWT verifier.

Безпека: захищайте ваш секрет

Безпека JWT, підписаного HMAC, повністю залежить від конфіденційності секрету. Кілька основних правил:

• Використовуйте довгий і випадковий секрет. RFC 7518 рекомендує мінімум розмір виводу алгоритму (32 байти для HS256, 48 для HS384, 64 для HS512). Людський пароль, як azerty123, тривіально піддається атаці перебором в офлайн-режимі.
• Ніколи не підписуйте JWT на стороні клієнта. Секрет опиниться в JavaScript-коді, розповсюдженому браузеру, і буде доступний будь-якому користувачу. Підпис завжди повинен залишатися на стороні сервера.
• Зберігайте секрет у змінній середовища (напр. JWT_SECRET), ніколи в Git-репозиторії. Розгляньте використання сховищ, як HashiCorp Vault, AWS Secrets Manager або Symfony Secrets залежно від вашого стека.
• Регулярно ротуйте секрет (key rotation), особливо після будь-якого інциденту або після звільнення особи, що мала доступ до конфігурації.
• JWT Builder призначений для тестування та навчання. Для виробництва використовуйте JWT-бібліотеку вашого фреймворка (lcobucci/jwt, firebase/php-jwt, jose-php).

Найкращі практики claims

Payload є вільним JSON-об'єктом, але RFC 7519 визначає набір registered claims, які JWT-бібліотеки вміють інтерпретувати. Включення правильних claims робить ваш токен портативним і уникає тонких помилок:

• iss (issuer): ідентифікатор емітента, наприклад "https://api.example.com".
• sub (subject): ідентифікатор особи або суті, зазвичай ID користувача.
• aud (audience): кому призначений токен, щоб запобігти повторному використанню токена в іншому API.
• exp (expiration time): Unix-timestamp, після якого токен більше не дійсний. Завжди включайте, навіть для тестового токена: токен без терміну дії є поганою звичкою, яку важко потім виправити.
• nbf (not before): Unix-timestamp, до якого токен ще не дійсний. Корисний для попередньої емісії токена, який стане активним пізніше.
• iat (issued at): Unix-timestamp емісії, корисний для журналювання та відкликання.
• jti (JWT ID): унікальний ідентифікатор токена, необхідний для ідемпотентності та реалізації списку відкликань.

Приклад типового payload

{
  "iss": "https://api.example.com",
  "sub": "user-12345",
  "aud": "mobile-app",
  "iat": 1714723200,
  "exp": 1714726800,
  "jti": "9f2d6b1e-2c4a-4f8a-9c3a-87a2b8a4b7e1",
  "scope": "read:profile write:profile"
}

Як користуватися інструментом

1. Введіть payload у вигляді валідного JSON. Це об'єкт, тому починається з { і закінчується }.
2. Вкажіть HMAC-секрет. Виберіть довгу випадкову рядок для виробничих токенів.
3. Виберіть алгоритм: HS256 за замовчуванням, HS384 або HS512 залежно від ваших потреб.
4. Натисніть створити. Підписаний JWT з'являється, готовий до вставки в заголовок Authorization: Bearer ....
5. Потім можете перевірити токен з тим самим секретом для підтвердження правильності round-trip, або декодувати його для повторного перегляду вмісту.

Часті запитання

Приклад запиту

curl -X POST https://cdrn.fr/api/v1/tools/jwt-builder/execute \
  -H "Content-Type: application/json" \
  -d '{"payload":"...","secret":"...","algorithm":"HS256"}'

Схема вхідних даних

Точки доступу

• GET https://cdrn.fr/api/v1/tools - перелічує всі доступні інструменти
• GET https://cdrn.fr/api/v1/tools/jwt-builder - отримує схему цього інструменту
• POST https://cdrn.fr/api/v1/tools/jwt-builder/execute - виконує цей інструмент з JSON-payload