RS-ID orqali kirish (OAuth2)

1. RS-ID orqali kirish nima

RS-ID orqali kirish foydalanuvchilarga saytingizga parol o'rniga RS-ID mobil ilovasi orqali kirish imkonini beradi. Integratsiya standart OAuth 2.0 Authorization Code protokoli asosida qurilgan.

Saytingiz foydalanuvchini RS-ID avtorizatsiya sahifasiga yo'naltiradi. Sahifada QR-kod ko'rsatiladi; foydalanuvchi uni RS-ID mobil ilovasida skanerlaydi va shaxsini yuz orqali tasdiqlaydi. Shundan so'ng RS-ID foydalanuvchini bir martalik avtorizatsiya kodi bilan saytingizga qaytaradi, backendingiz esa bu kodni foydalanuvchining tasdiqlangan profiliga almashtiradi.

Siz parollar, pasport ma'lumotlarini kiritish yoki yuzni tekshirish bilan ishlamaysiz — buni RS-ID bajaradi, backendingiz esa tasdiqlangan shaxsni oladi.

Foydalanish holatlari

Holat	Misol
Parolsiz kirish	Foydalanuvchilar RS-ID ilovasida QR-kodni skanerlab, veb-portalingizga kiradi.
Tasdiqlangan ro'yxatdan o'tish	Yangi foydalanuvchi bir qadamda ro'yxatdan o'tadi; akkaunt tasdiqlangan F.I.Sh., JSHSHIR va hujjat ma'lumotlari bilan yaratiladi.
Muhim xizmatlarga kirish	Har bir kirishda haqiqiy, tasdiqlangan shaxs talab qilinadigan bank, sug'urta, davlat yoki tibbiyot portallari.
Bir nechta xizmat uchun yagona shaxs	Bir xil RS-ID shaxsi bir nechta mahsulotlaringizga kirish uchun ishlatiladi.

2. Atamalar

Atama	Kim / nima
Mijoz (Client)	RS-ID'ni integratsiya qilayotgan kompaniya (siz). RS-ID'da AUTH turidagi loyiha sifatida ro'yxatdan o'tgan va `client_id` / `client_secret` hamda ro'yxatdan o'tkazilgan `redirect_uri` olgan. Mijoz frontendi (saytingiz) va mijoz backendini o'z ichiga oladi.
Foydalanuvchi	Tizimga kirayotgan inson — RS-ID mobil ilovasi o'rnatilgan mijozingiz.
RS-ID avtorizatsiya sahifasi	Foydalanuvchi QR-kodni skanerlaydigan RS-ID veb-sahifasi.
RS-ID mobil ilovasi	Foydalanuvchi telefonidagi RS-ID ilovasi; u orqali QR-kod skanerlanadi va shaxs tasdiqlanadi.
Server	Avtorizatsiya kodlarini beradigan va foydalanuvchi profilini qaytaradigan RS-ID serveri.
Avtorizatsiya kodi (`code`)	Foydalanuvchi kirgandan so'ng RS-ID sizning `redirect_uri` manzilingizga yuboradigan bir martalik kod. 5 daqiqa amal qiladi, bir marta ishlatiladi.
`redirect_uri`	RS-ID foydalanuvchini `code` bilan qaytaradigan saytingizdagi URL. RS-ID'da ro'yxatdan o'tkazilgan bo'lishi kerak.
`state`	Saytingiz har bir kirish uchun yaratadigan va qaytishda tekshiradigan tasodifiy qiymat — CSRF hujumlaridan himoya.
JSHSHIR (PINFL)	Jismoniy shaxsning shaxsiy identifikatsiya raqami — 14 ta raqam.

3. Qanday ishlaydi

Foydalanuvchi saytingizda RS-ID orqali kirish tugmasini bosadi.

Saytingiz foydalanuvchini client_id, redirect_uri, response_type=code va state parametrlari bilan RS-ID avtorizatsiya sahifasiga yo'naltiradi (7.1).

Avtorizatsiya sahifasi har 30 soniyada yangilanadigan QR-kodni ko'rsatadi (7.2).

Foydalanuvchi QR-kodni RS-ID mobil ilovasida skanerlaydi va shaxsini tasdiqlaydi.

Avtorizatsiya sahifasi foydalanuvchini code va state bilan sizning redirect_uri manzilingizga yo'naltiradi (7.3).

Backendingiz state ni tekshiradi va POST /v1/user/by-code orqali code ni foydalanuvchi profiliga almashtiradi (7.4).

Siz foydalanuvchini o'z tizimingizga kiritasiz.

4. Integratsiya sxemasi

5. Muhitlar

Muhit	RS-ID avtorizatsiya sahifasi	API bazaviy URL
Stage (test)	`https://auth.stage.rsid.uz`	`https://sdk.stage.rsid.uz/web/api`
Production	`https://auth.rsid.uz`	`https://sdk.rsid.uz/web/api`

Stage va production uchun turli client_id / client_secret ishlatiladi. redirect_uri har bir muhit uchun alohida ro'yxatdan o'tkaziladi.

6. Umumiy qoidalar

Javob formati

Barcha API javoblari bir xil tuzilishga ega:

{ "data": { }, "code": 0, "message": "Success" }

Maydon	Turi	Tavsif
`code`	integer	`0` — muvaffaqiyat. Boshqa har qanday qiymat — xato (xatolar jadvaliga qarang). Faqat HTTP-statusni emas, har doim `code` ni tekshiring.
`message`	string	So'rov tilidagi matn (uz / ru / en). Uni dasturiy tahlil qilmang.
`data`	any	Javob ma'lumotlari. Xato bo'lganda yo'q.

Xavfsizlik

client_secret faqat backendingizda saqlanadi. Uni hech qachon brauzer yoki mobil ilovaga bermang. code ni faqat backenddan almashtiring.

Har doim state dan foydalaning va uni tekshiring. Har bir kirish uchun yangi tasodifiy state yarating, uni foydalanuvchi sessiyasida saqlang va qiymat mos kelmasa, qaytishni rad eting.

Kod bir martalik va qisqa muddatli. Uni darhol almashtiring — u 5 daqiqa amal qiladi va faqat bir marta ishlatiladi.

redirect_uri uchun HTTPS dan foydalaning.

7. API tavsifi

7.1 Foydalanuvchini RS-ID avtorizatsiya sahifasiga yo'naltirish

Saytingiz foydalanuvchi brauzerini RS-ID avtorizatsiya sahifasiga yo'naltiradi.

Metod - GET (brauzer yo'naltirishi)
URL - {auth_page_url}/

Query-parametrlar

Maydon	Turi	Majburiy	Uzunlik / format	Tavsif
`client_id`	string	Ha	—	RS-ID bergan `client_id` qiymatingiz.
`redirect_uri`	string	Ha	URL, URL-kodlangan	RS-ID foydalanuvchini qaytaradigan manzil. RS-ID'da ro'yxatdan o'tkazilgan `redirect_uri` bilan aynan mos kelishi kerak.
`response_type`	string	Ha	`code`	Har doim `code` (authorization code flow).
`state`	string	Tavsiya etiladi	Tasodifiy satr	Saytingiz ushbu kirish uchun yaratgan tasodifiy qiymat. Kod bilan birga o'zgarishsiz qaytariladi.

Misol

https://auth.rsid.uz/?client_id=shop-example-auth&redirect_uri=https%3A%2F%2Fshop.example.uz%2Fauth%2Frsid%2Fcallback&response_type=code&state=Zx81kQ2mP0

7.2 RS-ID avtorizatsiya sahifasida foydalanuvchi harakatlari

Avtorizatsiya sahifasi QR-kod ko'rsatadi. Xavfsizlik uchun QR-kod har 30 soniyada qayta yaratiladi — eski QR-koddan foydalanib bo'lmaydi.

Foydalanuvchi RS-ID mobil ilovasini ochadi va QR-kodni skanerlaydi.

Foydalanuvchi ilovada shaxsini tasdiqlaydi (yuz orqali tekshiruv).

Identifikatsiya muvaffaqiyatli bo'lgach, avtorizatsiya sahifasi foydalanuvchini saytingizga qaytaradi (7.3).

Agar foydalanuvchi sahifani yopsa yoki kodni o'z vaqtida skanerlamasa, saytingizga hech narsa yuborilmaydi; foydalanuvchi 7.1 dan qaytadan boshlashi mumkin.

7.3 Saytingizga kod bilan qaytish

Muvaffaqiyatli kirishdan so'ng RS-ID avtorizatsiya sahifasi foydalanuvchi brauzerini sizning redirect_uri manzilingizga yo'naltiradi:

https://shop.example.uz/auth/rsid/callback?code=Zx81kQ2mP0aB7cD9eF1gH3&state=Zx81kQ2mP0

Parametr	Tavsif
`code`	Bir martalik avtorizatsiya kodi. 5 daqiqa amal qiladi, bir marta ishlatiladi.
`state`	7.1 da yuborgan qiymatingiz. Uni foydalanuvchi sessiyasida saqlangan qiymat bilan solishtiring; mos kelmasa — kirishni to'xtating.

Callback sahifangiz code (va state) ni backendingizga uzatadi, backend esa 7.4 ni chaqiradi.

7.4 Kod bo'yicha foydalanuvchi ma'lumotlarini olish

Mijoz backendi avtorizatsiya kodini foydalanuvchining tasdiqlangan profiliga almashtiradi.

Metod - POST
Endpoint - {base_url}/v1/user/by-code — Authorization sarlavhasisiz
Content-Type (sarlavha) - application/json

So'rov tanasi

Maydon	Turi	Majburiy	Uzunlik / format	Tavsif
`client_id`	string	Ha	Bo'sh emas	`client_id` qiymatingiz (AUTH loyihasi).
`client_secret`	string	Ha	Bo'sh emas	`client_secret` qiymatingiz.
`code`	string	Ha	Bo'sh emas	7.3 dagi `code`.
`grant_type`	string	Ha	`authorization_code`	Har doim `authorization_code`.

{
  "client_id": "shop-example-auth",
  "client_secret": "s3cr3t-value",
  "code": "Zx81kQ2mP0aB7cD9eF1gH3",
  "grant_type": "authorization_code"
}

Javob

Maydon	Turi	Tavsif
`data.user_info.first_name`	string	Ism.
`data.user_info.last_name`	string	Familiya.
`data.user_info.middle_name`	string	Otasining ismi. Bo'lmasa `-`.
`data.user_info.pinfl`	string	JSHSHIR, 14 ta raqam. Uni foydalanuvchining doimiy identifikatori sifatida ishlating.
`data.user_info.gender`	string	Jinsi.
`data.user_info.birth_date`	string	`yyyy-MM-dd`.
`data.user_info.birth_place`	string	Tug'ilgan joyi.
`data.document_info.document`	string	Hujjat seriyasi va raqami.
`data.document_info.type`	string	Hujjat turi.
`data.document_info.issued_by`	string	Kim tomonidan berilgan.
`data.document_info.issued_at`	string	Berilgan sana, `yyyy-MM-dd`.
`data.document_info.expiry_at`	string	Amal qilish muddati, `yyyy-MM-dd`.
`data.contact_info.phone`	string	RS-ID akkauntidagi telefon raqami.
`data.contact_info.email`	string	RS-ID akkauntidagi email, agar kiritilgan bo'lsa.
`data.permanent_address`	object	Ushbu oqimda qaytarilmaydi (`null`).
`data.temporary_address`	object	Ushbu oqimda qaytarilmaydi (`null`).
`code`	integer	Muvaffaqiyatda `0`.
`message`	string	Natija matni.

{
  "data": {
    "user_info": {
      "first_name": "ALISHER",
      "last_name": "KARIMOV",
      "middle_name": "BAXTIYOROVICH",
      "pinfl": "12345678901234",
      "gender": "MALE",
      "birth_date": "1990-01-01",
      "birth_place": "TOSHKENT",
      "birth_country": null,
      "nationality": null,
      "citizenship": null
    },
    "document_info": {
      "document": "AA1234567",
      "type": "PASSPORT",
      "issued_by": "IIV 26283",
      "issued_at": "2018-05-10",
      "expiry_at": "2028-05-09"
    },
    "contact_info": {
      "phone": "998901234567",
      "email": "alisher.karimov@example.uz"
    },
    "permanent_address": null,
    "temporary_address": null
  },
  "code": 0,
  "message": "Success"
}

Xatolar

Kod	Sabab
`-1083`	`client_id` topilmadi.
`-1002`	Mijoz AUTH loyihasi emas.
`-1089`	`grant_type` qiymati `authorization_code` emas.
`-1018`	`code` yaroqsiz, muddati o'tgan (5 daqiqadan eski) yoki allaqachon ishlatilgan, yoxud `client_secret` noto'g'ri. Kirishni 7.1 dan qaytadan boshlang.
`-1035`	`code` kirish bilan bog'lanmagan. Kirishni 7.1 dan qaytadan boshlang.
`400`	Majburiy maydon to'ldirilmagan.

8. Xato kodlari

Kod	Nomi	Ma'nosi
`0`	SUCCESS	Muvaffaqiyat.
`-9`	SYSTEM_ERROR	Kutilmagan server xatosi.
`-1002`	CLIENT_NOT_PERMITTED	Mijoz AUTH loyihasi emas.
`-1018`	USER_NOT_FOUND	Kod yaroqsiz, muddati o'tgan yoki ishlatilgan, yoxud hisob ma'lumotlari noto'g'ri.
`-1035`	INVALID_QR_TOKEN	Kod kirish bilan bog'lanmagan.
`-1083`	CLIENT_PROJECT_NOT_FOUND	`client_id` topilmadi.
`-1089`	INVALID_GRAND_TYPE	`grant_type` qiymati `authorization_code` emas.

RS-ID orqali kirish (OAuth2)

1. RS-ID orqali kirish nima#

Foydalanish holatlari#

2. Atamalar#

3. Qanday ishlaydi#

4. Integratsiya sxemasi#

5. Muhitlar#

6. Umumiy qoidalar#

Javob formati#

Xavfsizlik#

7. API tavsifi#

7.1 Foydalanuvchini RS-ID avtorizatsiya sahifasiga yo'naltirish#

7.2 RS-ID avtorizatsiya sahifasida foydalanuvchi harakatlari#

7.3 Saytingizga kod bilan qaytish#

7.4 Kod bo'yicha foydalanuvchi ma'lumotlarini olish#

8. Xato kodlari#