Ыкчам баштоо
Bototeka Authorization Code жана PKCE S256 колдогон каалаган OpenID Connect китепканасы менен иштейт.
Колдонмо түзүңүз
Кызматтын атын, кайтуу дарегин жана керек болсо логотибин көрсөтүңүз. 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 туташтырса болобу?
Ооба, PKCE жана эс тутумдагы кыска мөөнөттүү access token колдонгон public client катары. Чыныгы иш үчүн сервер же HttpOnly сессиясы бар BFF сунушталат.
Кардар ID-си катары эмнени сактоо керек?
issuer менен sub жубун сактаңыз. Email өзгөрүшү мүмкүн жана туруктуу идентификатор эмес.
Жашыруун ачкычты кантип алмаштырам?
Компания жөндөөлөрүндө API ачкычын түзүңүз же алмаштырыңыз. Жаңы жашыруун ачкычты дароо көчүрүп, сервер жөндөөлөрүн жаңыртыңыз жана эски уруксатты жокко чыгарыңыз.