Вхід через OAuth2

Надсилайте людей до Hivesigner, щоб вони ввійшли до вашого застосунку. Там вони переглядають ваш запит і схвалюють його. Далі Hivesigner повертає їх на вашу адресу зворотного виклику з токеном (потік з токеном) або з кодом, який ваш сервер обмінює на токени (потік з кодом). Ця сторінка охоплює обидва потоки, кожен параметр і рівні доступу.

Перш ніж почати

• Зареєструйте застосунок: обліковий запис Hive для нього з переліченими адресами зворотного виклику. Див. Зареєструйте застосунок.
• Щоб надсилати транзакції через API, обліковий запис вашого застосунку також має надати @hivesigner повноваження публікації.
• Для потоку з кодом задайте секрет клієнта.

Адреса авторизації

Надішліть користувача на цю адресу:

https://hivesigner.com/oauth2/authorize?client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&scope=SCOPE&state=STATE

Кодуйте кожне значення для URL. URLSearchParams робить це за вас:

import { randomBytes } from 'node:crypto';

const state = randomBytes(16).toString('hex');
// Store `state` in the user's session before you redirect (see "Protect the request with state").

const params = new URLSearchParams({
  client_id: 'myapp',
  redirect_uri: 'https://myapp.example/auth/callback',
  scope: 'posting',
  state,
});
const authorizeUrl = `https://hivesigner.com/oauth2/authorize?${params}`;

Параметри

Користувач усе одно може перемкнутися на інший обліковий запис на екрані згоди. Завжди беріть обліковий запис із токена або з обміну коду, ніколи з того, що ви просили.

Рівні доступу

У Hive одні повноваження публікації. Тому Hivesigner має два рівні доступу, лише вхід і публікацію, і нічого дрібнішого між ними.

У потоці з кодом адреса зворотного виклику спершу отримує код (токен із type code), який ваш сервер обмінює на токен доступу.

• Відсутній рівень доступу означає posting.
• Значення, що містить offline будь-де, означає offline, наприклад старе offline,vote,comment.
• Будь-яке інше значення означає posting. Сюди належать і старі назви операцій, як-от vote, comment, vote,comment, comment_options чи custom_json. Вони не обмежують токен: кожен токен публікації дозволяє ті самі операції. Див. Що приймає broadcast.

Просіть login, коли вашому застосунку потрібно лише знати, хто цей користувач. Див. Вхід без доступу до публікації.

Потік з токеном

Браузер користувача отримує токен доступу напряму. Вашому застосунку не потрібен жоден секрет.

1. Надішліть користувача на адресу авторизації:

   https://hivesigner.com/oauth2/authorize?client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&scope=posting&state=STATE
   

2. Користувач схвалює. Hivesigner перенаправляє на вашу адресу зворотного виклику:

   REDIRECT_URI?state=STATE&access_token=ACCESS_TOKEN&expires_in=604800&username=USERNAME
   

   Hivesigner додає свої параметри через ?, коли ваша адреса не має рядка запиту, і через &, коли має. state є лише тоді, коли ви надіслали непорожнє значення.

3. На своїй адресі зворотного виклику спершу звірте state. Потім перевірте токен на своєму сервері. Обліковий запис, якому належить токен, є в самому токені: не покладайтеся лише на параметр username, бо будь-хто може змінити URL-адресу.

4. Тримайте токен на своєму сервері або в куки httpOnly. Перенаправте на чисту адресу, щоб токен зник з адресного рядка.

5. Користуйтеся токеном з API, доки він не спливе через expires_in секунд (7 днів). Тоді надішліть користувача на адресу авторизації знову. Користувач, який уже надав доступ до публікації, бачить «Вхід до APP» і «Ви вже авторизували @myapp. Нові права не надаються.»

Потік з кодом

Ваш сервер отримує код і обмінює його на токен доступу й токен оновлення. Далі він може поновлювати їх без користувача. Користуйтеся цим, коли ваш сервер діє за користувачів тривалий час.

1. Надішліть користувача на адресу авторизації з scope=offline:

   https://hivesigner.com/oauth2/authorize?client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&scope=offline&state=STATE
   

   scope=posting&response_type=code робить те саме.

2. Користувач схвалює доступ до публікації. Hivesigner перенаправляє на вашу адресу зворотного виклику:

   REDIRECT_URI?code=CODE&state=STATE&username=USERNAME
   

3. Звірте state. Потім одразу обміняйте код зі свого сервера.

Обміняйте код

Надішліть код і свій секрет клієнта на /api/oauth2/token у тілі запиту POST:

curl -X POST https://hivesigner.com/api/oauth2/token \
  -H 'Content-Type: application/json' \
  -d '{"code": "CODE", "client_secret": "CLIENT_SECRET"}'

Відповідь:

{
  "access_token": "ACCESS_TOKEN",
  "refresh_token": "REFRESH_TOKEN",
  "expires_in": 604800,
  "username": "alice"
}

Той самий виклик у Node.js 18 або новішому:

const TOKEN_URL = 'https://hivesigner.com/api/oauth2/token';

export async function hivesignerTokens(grant) {
  const res = await fetch(TOKEN_URL, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      ...grant,
      client_secret: process.env.HIVESIGNER_CLIENT_SECRET,
    }),
  });
  const data = await res.json();
  if (!res.ok || data.error) {
    throw new Error(`${data.error}: ${data.error_description}`);
  }
  return data; // { access_token, refresh_token, expires_in, username }
}

// On your callback, after checking state:
const tokens = await hivesignerTokens({ code: req.query.code });

• Кладіть код і секрет у тіло запиту, ніколи в URL-адресу.
• Не надсилайте із цим запитом заголовок Authorization.
• Використовуйте username із цієї відповіді. Воно походить із коду, який підписав користувач.
• Тримайте токен доступу й токен оновлення на своєму сервері.

Оновлення

Коли токен доступу спливає, надішліть токен оновлення зі своїм секретом клієнта на ту саму кінцеву точку:

curl -X POST https://hivesigner.com/api/oauth2/token \
  -H 'Content-Type: application/json' \
  -d '{"refresh_token": "REFRESH_TOKEN", "client_secret": "CLIENT_SECRET"}'

const renewed = await hivesignerTokens({ refresh_token: stored.refresh_token });

Відповідь має ту саму форму, з новим токеном доступу й новим токеном оновлення. Збережіть обидва замість старих.

Захистіть запит через state

Без state інший сайт міг би надіслати вашого користувача на вашу адресу зворотного виклику з токеном або кодом на власний вибір. Тоді ваш застосунок виконав би вхід до чужого облікового запису. state прив’язує кожне повернення до браузера, який почав вхід.

1. Генеруйте випадкове значення для кожного входу, щонайменше 16 випадкових байтів. Шістнадцятковий запис не містить символів, які потребують кодування.
2. Зберігайте його там, звідки його може подати лише цей браузер: у сесії вашого сервера або в короткочасній куки httpOnly і Secure з SameSite=Lax.
3. Надсилайте його як state в адресі авторизації.
4. На своїй адресі зворотного виклику звірте параметр state зі збереженим значенням. Якщо його немає або воно інше, зупиніться: не використовуйте ні токен, ні код.
5. Видаліть збережене значення, щоб кожне працювало один раз.

app.get('/auth/callback', async (req, res) => {
  const expected = req.session.hivesignerState;
  delete req.session.hivesignerState;
  if (!expected || req.query.state !== expected) {
    return res.status(400).send('This sign-in has expired. Please try again.');
  }
  // Token flow: req.query.access_token. Code flow: req.query.code.
});

Hivesigner повертає те саме значення state, яке отримав. Порожнє він пропускає.

Що бачить користувач

Екран згоди показує зображення й назву вашого застосунку, «Обліковий запис Hive @myapp» і «Перенаправить вас на HOST», де HOST узято з вашої адреси зворотного виклику. Далі:

• Перший запит на публікацію. Заголовок читається як «APP запитує доступ до вашого облікового запису.» Картка Рівень доступу перелічує те, що зможе робити ваш застосунок. У повідомленні написано «Перша авторизація: обліковий запис @myapp буде додано до ваших повноважень публікації в блокчейні, і для цього один раз потрібен ваш активний ключ. Цей обліковий запис зможе публікувати від вашого імені, доки ви не відкличете доступ.» На кнопці написано Авторизувати. Коли на пристрої користувача немає активного ключа для цього облікового запису, екран просить його тут-таки.
• Вхід. Для scope=login або для доступу до публікації, який користувач надав раніше, заголовок читається як «Вхід до APP», а на кнопці написано Увійти.
• Обліковий запис. «Авторизація від імені» або «Вхід від імені», а далі вибраний обліковий запис. Користувач може перемкнути обліковий запис тут.
• Заблокований обліковий запис. Над кнопкою є поле коду доступу. Один клік розблоковує обліковий запис і веде далі.
• Немає облікового запису на пристрої. На кнопці написано Продовжити. Вона відкриває форму додавання облікового запису й повертає до запиту.

Після першого запиту на публікацію Hivesigner чекає, доки новий дозвіл стане видимим у блокчейні, і лише тоді перенаправляє. Це може зайняти кілька секунд. Щоб побачити весь екран з боку користувача, див. Вхід до застосунків.

Скасування та відхилені запити

• Скасування. Користувач переходить до свого списку облікових записів у Hivesigner. На вашу адресу зворотного виклику нічого не надсилається: параметра помилки теж немає. Тримайте кнопку входу доступною, щоб користувач міг почати знову. Не чекайте на повернення.
• Відхилені запити. Незареєстрована адреса зворотного виклику, невідомий client_id або відсутній redirect_uri показують у Hivesigner помилку з кнопкою Повідомити про цю проблему. На вашу адресу зворотного виклику нічого не надсилається. Див. Що бачать користувачі, коли щось не так.

Стара адреса запиту на вхід

Hivesigner досі приймає старішу адресу входу, збережену для давніх інтеграцій. Для нових використовуйте /oauth2/authorize.

https://hivesigner.com/login-request/CLIENT_ID?redirect_uri=REDIRECT_URI&scope=posting&state=STATE

Вона відкриває той самий екран згоди, з тими самими перевірками адреси зворотного виклику й тим самим перенаправленням. Свої параметри вона читає інакше:

• scope це login або posting. Будь-яке інше значення або його відсутність означає login.
• offline не читається. Для потоку з кодом додайте response_type=code.
• account не читається.

https://hivesigner.com/login?client_id=CLIENT_ID&redirect_uri=REDIRECT_URI дотримується тих самих правил.