Արագ մեկնարկ
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-ով։ Աշխատանքային գործարկման համար նախընտրելի է սերվերը կամ HttpOnly սեսիայով BFF-ը։
Ի՞նչ պահել որպես հաճախորդի ID։
Պահեք issuer և sub զույգը։ Email-ը կարող է փոխվել և կայուն նույնացուցիչ չէ։
Ինչպե՞ս փոխել գաղտնի բանալին։
Ընկերության կարգավորումներում ստեղծեք կամ փոխարինեք API բանալին։ Նոր գաղտնի բանալին անմիջապես պատճենեք, թարմացրեք սերվերի կարգավորումը և չեղարկեք հին հասանելիությունը։