Skip to content

Ilovalar uchun OAuth 2.0

OAuth 2.0 ilovaga foydalanuvchi nomidan Planfix’ga parol so‘ramasdan yoki saqlamasdan kirish imkonini beradi.

Planfix majburiy PKCE S256 bilan Authorization Code oqimini ishlatadi. OAuth orqali REST API yoki Planfix MCP serveriga ulanishingiz mumkin.

Agar tayyor AI mijozini ulamoqchi bo‘lsangiz, boshlash uchun Planfix MCP sahifasiga qarang. Hisobingizda kirishni boshqarayotgan bo‘lsangiz, OAuth and MCP applications in an accountga murojaat qiling. Hamkorlar va ko‘p-hisob integratsiyalari ishlab chiquvchilari uchun OAuth applications for partners foydali bo‘ladi.

Ilova ro‘yxatga olish variantlari

Variant Qachon ishlatish kerak Qayerda ishlaydi
Hisobga tegishli ilova Integratsiya bitta hisob uchun mo‘ljallangan va mijozga oldindan belgilangan client_id kerak. Faqat uning egalik qilayotgan hisobida.
Hamkorlikka tegishli ilova Bir xil ilova bir nechta mijoz hisoblariga ulanadi. Xavfsizlik siyosati yoki administrator tomonidan ruxsat berilgan hisoblarda.
MCP mijozini avtomatik ro‘yxatga olish MCP mijozida Client ID Metadata Document (CIMD) yoki Dynamic Client Registration (DCR) qo‘llab‑quvvatlanadi. Ro‘yxatga olish o‘zi hisobga kirish huquqini bermaydi. Ilova tanlangan hisobda hali ham ruxsat etilishi kerak.

CIMD va DCR faqat MCP ulanishlari uchun mavjud. REST API uchun hisobga tegishli yoki hamkorlikka tegishli ilovadan foydalaning.

OAuth tugunlari

Yangi integratsiyalar global tugunlardan foydalanishi kerak. Hisob nomi ushbu URL’larda kiritilmaydi: foydalanuvchi avtorizatsiya vaqtida hisobni tanlaydi.

Maqsad Manzil
Issuer https://auth.planfix.com
Authorization https://auth.planfix.com/oauth/authorize
Token https://auth.planfix.com/oauth/token
User information https://auth.planfix.com/oauth/userinfo
Token revocation https://auth.planfix.com/oauth/revoke
Dynamic MCP client registration https://auth.planfix.com/oauth/register

Avtorizatsiya serveri metadatalari standart tugunlarda mavjud: 

https://auth.planfix.com/.well-known/oauth-authorization-server
https://auth.planfix.com/.well-known/openid-configuration

Yo‘naltirish URI’lari

Yo‘naltirish URI ilova sozlamalarida ro‘yxatga olingan bo‘lishi kerak. Avtorizatsiya so‘rovida yuborilgan qiymat ro‘yxatga olingan URI bilan to‘liq mos kelishi zarur.

Ruxsat etilganlar:

  • https URL’lar;
  • http URL’lari faqat loopback hostlar uchun, masalan localhost yoki 127.0.0.1.

Loopback URI uchun port dinamik bo‘lishi mumkin, lekin sxema, host, path va query mos kelishi kerak. URL fragmentlari va foydalanuvchi ma’lumotlari (user info) ruxsat etilmaydi.

Kirish darajalari

Ilova faqat oldindan ruxsat etilgan kirish darajalarini, ya’ni scopes ni oladi. To‘liq ro‘yxat uchun REST API access levels ga qarang.

So‘ralgan to‘plam ilova uchun ro‘yxatga olingan scope’larning qismi bo‘lishi kerak. Ilova scope’lari foydalanuvchining Planfix’dagi huquqlarini kengaytirmaydi: ilova faqat ulangan xodimga mavjud bo‘lgan ma’lumotlarga kirishi mumkin.

Managed ilovalar shuningdek xizmat scope’larini oladi: userinfo, openid va email.

Foydalanuvchini avtorizatsiya qilish

code_verifier va uning SHA-256 ko‘rinishi bo‘lgan code_challenge ni yarating, so‘ng avtorizatsiya tugunini brauzerda oching.

REST API misoli: 

GET https://auth.planfix.com/oauth/authorize
    ?client_id=CLIENT_ID
    &redirect_uri=https%3A%2F%2Fexample.com%2Foauth%2Fcallback
    &response_type=code
    &scope=openid%20email%20task_readonly
    &state=RANDOM_STATE
    &code_challenge=CODE_CHALLENGE
    &code_challenge_method=S256

MCP uchun aniq MCP server URL’ini resource parametri bilan qo‘shing: 

resource=https%3A%2F%2Fmcp.planfix.com%2Fmcp
Parametr Tavsif
client_id Ro‘yxatga olingan ilovaning identifikatori. CIMD holatida bu mijoz metadata hujjatining URL’si.
redirect_uri Ruxsat etilgan yo‘naltirish URI’larning biri.
response_type code bo‘lishi kerak.
scope Bo‘shliq bilan ajratilgan kerakli ruxsatlar. REST API uchun bu parametr majburiy. MCP mijozlari uni tashlab yuborishi mumkin — bu holda ilovaga ruxsat berilgan scopes ishlatiladi.
state So‘rovni almashtirishdan himoya qiluvchi tasodifiy qiymat. Ilova redirect’dan so‘ng uni tekshirishi kerak.
code_challenge code_verifier ning SHA-256 hash’ining base64url (paddingsiz) ko‘rinishi.
code_challenge_method Faqat S256 qo‘llab‑quvvatlanadi.
resource MCP uchun aniq URL: https://mcp.planfix.com/mcp. REST API uchun bu parametrni yubormang.

Foydalanuvchi hisobni tanlaydi, tizimga kiradi va so‘ralgan ruxsatlarni ko‘rib chiqadi. Hisobga tegishli ilova bevosita uning egasi hisobini ochadi. Agar xavfsizlik siyosati administrator tasdig‘ini talab qilsa, Planfix tegishli bosqichni ko‘rsatadi. Administrator ilovani tasdiqlab, bir harakatda ulanishingiz mumkin.

Muvaffaqiyatli avtorizatsiyadan so‘ng Planfix brauzerni redirect_uri ga yo‘naltiradi: 

https://example.com/oauth/callback?code=AUTHORIZATION_CODE&state=RANDOM_STATE&iss=https%3A%2F%2Fauth.planfix.com

Avtorizatsiya kodi bir martalik va 10 daqiqagacha amal qiladi.

Tokenlarni olish

/oauth/token ga application/x-www-form-urlencoded bilan POST so‘rov yuboring: 

grant_type=authorization_code
&client_id=CLIENT_ID
&code=AUTHORIZATION_CODE
&redirect_uri=https%3A%2F%2Fexample.com%2Foauth%2Fcallback
&code_verifier=CODE_VERIFIER

MCP uchun avtorizatsiya so‘rovida ishlatilgan bilan bir xil resource ni takrorlang.

Public client secretsiz so‘rov yuboradi. Confidential client esa client_secret_basic bilan yoki so‘rov tanasida client_id va client_secret parametrlarini yuborib autentifikatsiya qiladi.

Javobga misol: 

{
  "access_token": "ACCESS_TOKEN",
  "token_type": "bearer",
  "expires_in": 86400,
  "refresh_token": "REFRESH_TOKEN",
  "scope": "openid email task_readonly"
}

REST API uchun javobda shuningdek account_name, account_domain va account_url ham bo‘ladi. Ushbu qiymatlarni saqlang va REST API so‘rovlari uchun tanlangan hisobning URL’idan foydalaning.

Access token 24 soatgacha amal qiladi. U foydalanuvchi, hisob, ilova, scope’lar va resource’ga bog‘langan. MCP uchun berilgan tokenni to‘g‘ridan-to‘g‘ri REST API bilan ishlatib bo‘lmaydi, va aksincha — REST API tokeni MCP uchun ishlamaydi.

REST API bilan tokenni ishlatish

Tokenni Authorization sarlavhasida yuboring: 

GET https://account.planfix.com/rest/task/123
Authorization: Bearer ACCESS_TOKEN

Avtorizatsiya kodi almashinuvida qaytarilgan hisob URL’idan foydalaning. Faqat ruxsat etilgan scopes bilan qoplangan metodlar mavjud bo‘ladi. OAuth tokenlari hisob rejasi va standart REST API limits cheklovlariga bo‘ysunadi.

Foydalanuvchi ma’lumotlari

userinfo so‘rovi uchun openid scope talab qilinadi: 

GET https://auth.planfix.com/oauth/userinfo
Authorization: Bearer ACCESS_TOKEN

Agar email scope mavjud bo‘lsa, javob misoli: 

{
  "sub": "123:user:456",
  "email": "user@example.com",
  "email_verified": true
}

Global OAuth avtorizatsiyasi hisob xodimlariga mavjud. Planfix id_token chiqarmaydi; foydalanuvchi ma’lumotlarini olish uchun userinfo so‘rovini qiling.

Tokenlarni yangilash

POST https://auth.planfix.com/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&client_id=CLIENT_ID
&refresh_token=REFRESH_TOKEN

MCP uchun yana bir bor bir xil resource ni yuboring. Confidential client o‘z sirini autentifikatsiya qilish uchun ishlatishi kerak.

Planfix yangi access token va yangi refresh token qaytaradi. Oldingi refresh token darhol yaroqsiz bo‘ladi, shuning uchun ilova saqlangan qiymatni atomik tarzda almashtirishi zarur.

Tokenni bekor qilish

Mijoz /oauth/revoke orqali refresh tokenni bekor qilishi mumkin: 

POST https://auth.planfix.com/oauth/revoke
Content-Type: application/x-www-form-urlencoded

token=REFRESH_TOKEN
&client_id=CLIENT_ID

Foydalanuvchi shuningdek o‘z foydalanuvchi kartasidagi Session management bo‘limidan ulanishni o‘chirishi mumkin. Administrator uchinchi tomon ilovasining butun hisob uchun tasdig‘ini ham bekor qilishi mumkin. Qarang OAuth and MCP applications in an account.

Mavjud integratsiyalar bilan moslik

Tenant tugunlari, masalan https://account.planfix.com/api/v2/oauth/authorize, /token va /userinfo mavjud hisobga bog‘langan eski integratsiyalar uchun ishlashda davom etadi.

Yangi integratsiyalar uchun global tugunlardan foydalaning. Ular standart metadata discovery, hisob tanlash va MCP’ni qo‘llab‑quvvatlaydi. Bitta OAuth sessiyasida global va tenant tugunlarni aralashtirmang.

Xavfsizlik bo‘yicha tavsiyalar

  • Har doim PKCE S256 dan foydalaning va state ni tekshiring.
  • Mobil, desktop va brauzer ilovalari uchun secretsiz public client dan foydalaning.
  • Secret serverda xavfsiz saqlanishi mumkin bo‘lsa — confidential client dan foydalaning.
  • Kerakli minimal scope to‘plamini so‘rang.
  • Access tokenlarni, refresh tokenlarni, avtorizatsiya kodlarini, code_verifier va client secret’larni log’larga yozmang.
  • Refresh tokenlar va client secret’larni shifrlangan saqlashda saqlang.
  • Javobdagi iss ni tekshiring va faqat kutilgan Planfix issuer’ni qabul qiling.

Mumkin xatoliklar

Xato Sababi
invalid_client Mijoz noma’lum yoki o‘chirib qo‘yilgan, client secret noto‘g‘ri yoki ilova tanlangan hisobda mavjud emas.
invalid_grant Avtorizatsiya kodi yoki refresh token noto‘g‘ri, muddati o‘tgan, allaqachon ishlatilgan yoki client, redirect URI, PKCE ma’lumotlari yoki resource bilan mos kelmaydi.
invalid_scope So‘rov ilova uchun ruxsat etilmagan scope ni o‘z ichiga oladi.
invalid_target resource qo‘llab‑quvvatlanmaydi yoki so‘rovlar orasida o‘zgargan.
access_denied Foydalanuvchi ulanmaslikni tanladi yoki hisob siyosati ilovaga ruxsat bermaydi.
HTTP 401, invalid_token Access token noma’lum, muddati o‘tgan yoki bekor qilingan.
HTTP 403, insufficient_scope Token operatsiya uchun talab qilinadigan scope ni o‘z ichiga olmaydi.

O‘tish

"http://planfix.com/uz/help/index.php?title=Ilovalar_uchun_OAuth_2.0&oldid=6684" dan olindi