Kitobchi ID — umumiy
Kitobchi akkaunti bilan boshqa ilovalarga kirish: OAuth 2.1 + OpenID Connect, oqim, endpointlar, scope va claim‘lar, ilovani ulash.
Kitobchi ID nima?
Kitobchi ID — foydalanuvchilarga Kitobchi akkaunti bilan boshqa sayt va ilovalarga bir tugma orqali kirish imkonini beruvchi yagona identifikatsiya tizimi. U ochiq standartlarga asoslangan: OAuth 2.1 (authorization code + PKCE) va OpenID Connect 1.0. Shu sababli istalgan standart OIDC kutubxonasi (AppAuth, openid-client, league/oauth2-client, Spring Security, NextAuth/Auth.js va boshqalar) bilan qo'shimcha kodsiz ishlaydi.
Foydalanuvchi uchun: parol yo'q — telefon raqamiga keladigan SMS kod bilan kiradi, qaysi ma'lumotlar ulashilishini o'zi ko'radi va tasdiqlaydi. Siz uchun: tasdiqlangan telefon raqami, ism va profil rasmi, SMS va akkaunt tiklash bilan shug'ullanmasdan.
Barcha endpointlarni qo'lda yozmang — ularni discovery hujjatidan oling: https://kitobchi.com/api/id/.well-known/openid-configuration
Kirish oqimi
Ilova foydalanuvchini Kitobchi ID'ga yuboradi
/authorize ga state, nonce va PKCE code_challenge bilan yo'naltirasiz. Mobil ilovada — tizim brauzeri (Custom Tabs / ASWebAuthenticationSession), WebView emas.
Foydalanuvchi kiradi va rozilik beradi
Telefon raqam → tasdiqlash kodi: foydalanuvchida Kitobchi ilovasi bo'lsa — ilovadagi «Kitobchi» chatiga, bo'lmasa SMS (har ikkisida ilovangiz nomi ko'rsatiladi). Birinchi marta ulanishda so'ralgan ma'lumotlar ro'yxati va ilovangiz domeni ko'rsatiladi. Keyingi kirishlarda — bir bosishda.
Ilova bir martalik kod oladi
redirect_uri?code=…&state=…&iss=… — state va iss ni albatta tekshirasiz. Kod 5 daqiqa amal qiladi va faqat bir marta ishlatiladi.
Server kodni tokenlarga almashtiradi
/token ga code + code_verifier yuborib access token (10 daqiqa), ID token (1 soat) va kerak bo'lsa refresh token olasiz. ID token imzosini JWKS orqali tekshirib, foydalanuvchini sub bo'yicha tanib olasiz.
Endpointlar
| Endpoint | Usul | Vazifasi |
|---|---|---|
| /.well-known/openid-configuration | GET | Discovery — barcha manzillar va imkoniyatlar (1 soat keshlang) |
| /authorize | GET (brauzer) | Kirish va rozilik sahifasi, kod qaytaradi |
| /token | POST (form) | Kodni yoki refresh tokenni tokenlarga almashtirish |
| /userinfo | GET/POST + Bearer | Joriy foydalanuvchi ma'lumotlari (scope bo'yicha) |
| /jwks | GET | ID va access tokenlarni tekshirish uchun ochiq kalitlar (RS256, kid) |
| /revoke | POST (form) | Token bekor qilish (RFC 7009) — chiqishda chaqiring |
| /logout | GET (brauzer) | Kitobchi ID sessiyasini yopish (RP-initiated logout) |
Barcha manzillar issuer'ga nisbatan: https://kitobchi.com/api/id/token va hokazo.
Scope va claim'lar
Faqat haqiqatan kerakli ma'lumotni so'rang — har bir qo'shimcha scope rozilik oynasida alohida qator bo'lib chiqadi va konversiyani pasaytiradi. Ilovangizga ruxsat berilgan scope'lar ro'yxatdan o'tishda belgilanadi.
| Scope | Claim'lar | Izoh |
|---|---|---|
| openid | sub | majburiy Foydalanuvchining doimiy identifikatori |
| profile | name, given_name, family_name, preferred_username, picture, locale, updated_at | Bo'sh maydonlar javobda bo'lmaydi |
| phone | phone_number (E.164, +998…), phone_number_verified | Kitobchi ID orqali kirgan raqam doim SMS bilan tasdiqlangan |
| email, email_verified | Ixtiyoriy, ko'pincha tasdiqlanmagan — identifikator sifatida ishlatmang | |
| offline_access | — | Refresh token beriladi (foydalanuvchi ilovada bo'lmaganda ham sessiyani yangilash) |
sub — foydalanuvchi identifikatori
Foydalanuvchini faqat sub bo'yicha bog'lang (bazada issuer + sub juftligini saqlang). Telefon raqam yoki email'ni kalit qilmang — raqamlar almashadi va qayta beriladi.
-
Hamkor ilovalar uchun pairwise sub — bitta foydalanuvchi har bir hamkor (domen) uchun boshqa sub oladi (43 belgili satr). Ikki hamkor o'z bazalarini birlashtirib foydalanuvchini kuzata olmaydi.
-
Barqaror — sub foydalanuvchi ismi, raqami yoki rasmi o'zgarganda o'zgarmaydi.
Ilovani ulash
Hozircha ilovalar Kitobchi jamoasi tomonidan qo'lda ro'yxatdan o'tkaziladi. Quyidagilarni yuboring:
| Ma'lumot | Misol | Talab |
|---|---|---|
| Ilova nomi va logotipi (https, kvadrat) | «Hamkor do'kon» | majburiy |
| Sayt manzili | https://hamkor.uz | majburiy |
| Redirect URI'lar (aniq, to'liq) | https://hamkor.uz/auth/kitobchi/callback | majburiy |
| Ilova turi | server (confidential) yoki SPA/mobil (public) | majburiy |
| Kerakli scope'lar va sababi | openid profile phone | majburiy |
| Chiqishdan keyingi URI | https://hamkor.uz/ | ixtiyoriy |
| Texnik aloqa e-pochtasi | dev@hamkor.uz | majburiy |
Javoban client_id (kid_…) va server ilovalar uchun client_secret (kid_cs_…) beriladi. Secret faqat bir marta ko'rsatiladi; bizda faqat uning hash'i saqlanadi — yo'qolsa, yangisi chiqariladi.
Redirect URI qoidalari
- Faqat https. Istisno: lokal ishlab chiqish uchun http://127.0.0.1:PORT/… va http://localhost/….
- Aniq moslik — wildcard (*), prefiks va fragment (#) yo'q. Har bir qaytish manzili alohida ro'yxatdan o'tadi.
- Mobil ilovalar — imkon qadar App Links / Universal Links (https). Custom scheme faqat reverse-DNS ko'rinishida (uz.hamkor.app:/oauth) va faqat public client uchun.