სწრაფი დაწყება
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}/customersაბრუნებს sub-ს, დადასტურებულ 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 გასაღები. ახალი საიდუმლო გასაღები მაშინვე დააკოპირეთ, განაახლეთ სერვერის კონფიგურაცია და გააუქმეთ ძველი წვდომა.