Միացրեք մուտքը 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-ով։ Աշխատանքային գործարկման համար նախընտրելի է սերվերը կամ HttpOnly սեսիայով BFF-ը։

Ի՞նչ պահել որպես հաճախորդի ID։

Պահեք issuer և sub զույգը։ Email-ը կարող է փոխվել և կայուն նույնացուցիչ չէ։

Ինչպե՞ս փոխել գաղտնի բանալին։

Ընկերության կարգավորումներում ստեղծեք կամ փոխարինեք API բանալին։ Նոր գաղտնի բանալին անմիջապես պատճենեք, թարմացրեք սերվերի կարգավորումը և չեղարկեք հին հասանելիությունը։

Մուտք միացրեք ձեր ծառայությանը

Բացել OAuth-ի կարգավորումները