Вурудро тавассути 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