Падключыце ўваход праз Bototeka

Выкарыстоўвайце OpenID Connect з PKCE. Абменьвайце код на токены і атрымлівайце профіль праз UserInfo.

openid-configuration
{
  "issuer": "https://bototeka.com/api",
  "authorization_endpoint": "https://bototeka.com/api/oauth/authorize",
  "token_endpoint": "https://bototeka.com/api/oauth/token",
  "userinfo_endpoint": "https://bototeka.com/api/oauth/userinfo",
  "scopes_supported": ["openid", "email", "profile", "offline_access"]
}

Хуткі старт

Bototeka працуе з любой бібліятэкай OpenID Connect, якая падтрымлівае Authorization Code і PKCE S256.

  1. Стварыце праграму

    Укажыце назву сэрвісу, адрас вяртання і, калі трэба, лагатып. Звароты ад Google, Apple і Yandex апрацоўвае Bototeka.

  2. Захавайце ўліковыя даныя

    Скапіруйце Client ID і Client Secret. Сакрэт паказваецца толькі адзін раз.

  3. Наладзьце OIDC

    Перадайце бібліятэцы issuer. Астатнія endpoint яна знойдзе аўтаматычна.

  4. Праверце ўваход

    Пачніце ўваход, праверце state і nonce, абмяняйце код і стварыце лакальную сесію.

Issuer
https://bototeka.com/api
Discovery URL
https://bototeka.com/api/.well-known/openid-configuration
Service API
https://api.bototeka.com/api/identity/v1
Прыклад Redirect URI
https://service.example/auth/callback

Праверка падключэння

Даступна ўладальніку і адміністратару без балансу

Гэты тэст правярае налады Bototeka і даступнасць endpoint правайдара. Інтэрактыўны ўваход карыстальніка правяраецца асобна.

Адкрыць налады OAuth

Уваход і токены

Ваш сервер стварае PKCE, state і nonce, накіроўвае карыстальніка ў Bototeka і атрымлівае толькі кароткачасовы код аўтарызацыі.

Стварыць URL аўтарызацыі
import { createHash, randomBytes } from "node:crypto";

const clientId = process.env.BOTOTEKA_CLIENT_ID;
if (!clientId) throw new Error("BOTOTEKA_CLIENT_ID is required");

const verifier = randomBytes(32).toString("base64url");
const challenge = createHash("sha256").update(verifier).digest("base64url");
const state = randomBytes(24).toString("base64url");
const nonce = randomBytes(24).toString("base64url");

const authorize = new URL("https://bototeka.com/api/oauth/authorize");
authorize.search = new URLSearchParams({
  client_id: clientId,
  redirect_uri: "https://service.example/auth/callback",
  response_type: "code",
  scope: "openid email profile",
  code_challenge: challenge,
  code_challenge_method: "S256",
  state,
  nonce,
}).toString();

// Save verifier, state and nonce in the user's server-side session.
console.log(authorize.toString());
Абмяняць код на токены
curl --request POST 'https://bototeka.com/api/oauth/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=authorization_code' \
  --data-urlencode 'client_id=YOUR_CLIENT_ID' \
  --data-urlencode 'client_secret=YOUR_CLIENT_SECRET' \
  --data-urlencode 'code=CODE_FROM_CALLBACK' \
  --data-urlencode 'redirect_uri=https://service.example/auth/callback' \
  --data-urlencode 'code_verifier=SAVED_PKCE_VERIFIER'
Атрымаць профіль
curl 'https://bototeka.com/api/oauth/userinfo' \
  --header 'Authorization: Bearer ACCESS_TOKEN'
Пасля вяртання: параўнайце state, абмяняйце код адзін раз, праверце подпіс ID Token праз JWKS, затым issuer, audience, тэрмін дзеяння і nonce. Захоўвайце карыстальніка па пары iss + sub, а не па email.

Даныя рэгістрацыі праз API

Стварыце API-ключ у наладах кампаніі і запытвайце кліентаў або падзеі яе праграм.

GET/applications/{applicationId}/customers

Вяртае sub, пацверджаны email, імя і час актыўнасці.

GET/applications/{applicationId}/events

Вяртае рэгістрацыю або ўваход, суму, валюту, статус і час падзеі.

Атрымаць кліентаў праграмы
curl 'https://api.bototeka.com/api/identity/v1/applications/APPLICATION_ID/customers?limit=50' \
  --header 'Authorization: Bearer btk_v1_YOUR_API_KEY'
Атрымаць падзеі рэгістрацыі і ўваходу
curl 'https://api.bototeka.com/api/identity/v1/applications/APPLICATION_ID/events?limit=50' \
  --header 'Authorization: Bearer btk_v1_YOUR_API_KEY'

Для чытання патрэбны identity:read. Перадавайце ключ як Bearer-токен і захоўвайце на серверы.

Вэбхукі

Падпішыцеся на падзеі ў наладах кампаніі. Адрас павінен выкарыстоўваць HTTPS. Сакрэт подпісу паказваецца адзін раз.

identity.registration.completed.v1

Рэгістрацыя завершана і запісана ў журнале выкарыстання.

identity.login.completed.v1

Паўторны ўваход завершаны і запісаны ў журнале выкарыстання.

Дастаўка адбываецца прынамсі адзін раз. Адсейвайце паўторы па event ID, прымайце падзеі ў любым парадку і вяртайце 2xx толькі пасля захавання.

Праверыць подпіс вэбхука
import { createHmac, timingSafeEqual } from "node:crypto";

export function verifyBototekaWebhook(rawBody, headers, secret) {
  const timestamp = headers["x-bototeka-webhook-timestamp"];
  const received = headers["x-bototeka-webhook-signature"];
  if (!timestamp || !received) return false;
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;

  const expected = "v1=" + createHmac("sha256", secret)
    .update(timestamp + "." + rawBody)
    .digest("hex");
  const left = Buffer.from(expected);
  const right = Buffer.from(received);
  return left.length === right.length && timingSafeEqual(left, right);
}

Праверкі перад запускам

  • Выкарыстоўвайце дакладны HTTPS Redirect URI і не прымайце вяртанне на адвольны адрас.
  • Для кожнай спробы стварайце новыя state, nonce і PKCE verifier і захоўвайце іх у сервернай сесіі.
  • Не захоўвайце Client Secret, API-ключы, access token і refresh token у браўзеры або мабільнай аналітыцы.
  • Запытвайце offline_access, толькі калі серверу сапраўды патрэбная працяглая сесія.
  • Правярайце подпіс вэбхука па неапрацаваным целе запыту і бяспечна апрацоўвайце паўторную дастаўку.

Памылкі і аднаўленне

invalid_request

Што адбылося

Абавязковы параметр адсутнічае або няправільны.

Што рабіць

Праверце Redirect URI, PKCE, state, nonce і Content-Type.

invalid_grant

Што адбылося

Тэрмін кода скончыўся, ён ужо выкарыстаны або не адпавядае verifier.

Што рабіць

Пачніце новы ўваход. Не паўтарайце абмен таго ж кода.

temporarily_unavailable

Што адбылося

На балансе праграмы недастаткова сродкаў.

Што рабіць

Папоўніце баланс OAuth і пачніце новы ўваход.

429

Што адбылося

Перавышаны ліміт запытаў або спроб пацверджання.

Што рабіць

Выконвайце Retry-After і паўтарайце з выпадковай дадатковай затрымкай.

Пытанні і адказы

Калі спісваецца аплата?

Пасля паспяховай выдачы токена. Першая сесія лічыцца рэгістрацыяй, наступныя — уваходамі. Няўдалыя і скасаваныя спробы, refresh, UserInfo і logout бясплатныя.

Ці можна выкарыстоўваць толькі email?

Так. Bototeka падтрымлівае рэгістрацыю па email, аднаразовыя коды, пацверджанне адраса і аднаўленне пароля без сацыяльных правайдараў.

Ці можна падключыць SPA?

Так, як public client з PKCE і кароткачасовым access token у памяці. Для рабочага запуску лепш сервер або BFF з HttpOnly-сесіяй.

Што захоўваць як ID кліента?

Захоўвайце пару issuer і sub. Email можа змяніцца і не з'яўляецца пастаянным ідэнтыфікатарам.

Як змяніць сакрэт?

Стварыце або абнавіце API-ключ у наладах кампаніі. Адразу скапіруйце новы сакрэт, абнавіце налады сервера і адклічце стары доступ.

Падключыце ўваход да свайго сэрвісу

Адкрыць налады OAuth