ჩართეთ შესვლა 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-ის პარამეტრების გახსნა