Оғози зуд
Bototeka бо ҳар китобхонаи OpenID Connect кор мекунад, ки Authorization Code ва PKCE S256-ро дастгирӣ мекунад.
Барнома созед
Номи хадамот, суроғаи бозгашт ва, агар лозим бошад, нишонаро ворид кунед. Бозгаштҳои Google, Apple ва Yandex-ро Bototeka идора мекунад.
Маълумоти дастрасиро нигоҳ доред
Client ID ва Client Secret-ро нусхабардорӣ кунед. Калиди махфӣ танҳо як бор нишон дода мешавад.
OIDC-ро танзим кунед
issuer-ро ба китобхона диҳед. Он endpoint-ҳои дигарро худкор меёбад.
Вурудро санҷед
Вурудро оғоз кунед, 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 мефиристад ва танҳо коди кӯтоҳмуддати иҷозат мегирад.
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'Маълумоти бақайдгирӣ тавассути API
Дар танзимоти ширкат калиди API созед ва муштариён ё рӯйдодҳои барномаҳои ширкати худро дархост кунед.
/applications/{applicationId}/customerssub, email-и тасдиқшуда, ном ва вақтҳои фаъолиятро бармегардонад.
/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-ро риоя кунед ва бо таъхири иловагии тасодуфӣ такрор кунед.
| Код | Чӣ рӯй дод | Чӣ бояд кард |
|---|---|---|
| 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 созед ё иваз кунед. Калиди нави махфиро фавран нусхабардорӣ кунед, танзимоти серверро нав карда, дастрасии кӯҳнаро бекор кунед.