Хөгжүүлэгчийн консол

Өөрийн системээ Gerege Nexus-тэй холбох. Платформ нь өөрөө OAuth2 / OpenID Connect provider — таны апп хэрэглэгчийг энд нэвтрүүлж, дараа нь түүний өмнөөс API дуудна.

1. Client бүртгэх

Ажлын талбартаа Developer модулийг суулгаад /developer/apps руу орно. Шинэ апп дарж дараахыг өгнө:

Бүртгэсний дараа client_id буцна. client_secret зөвхөн тэр нэг хариултад ил гарна — дахин уншиж авах API байхгүй. Алдвал эсвэл гоожвол шинэ client бүртгэх шаардлагагүй: доорх §6 Client-ээ удирдах-ын «нууц шинэчлэх» үйлдлийг ашиглана.

Яагаад ингэсэн бэ: нууцыг дахин уншуулдаг API байвал тэр нь нууцыг унших хамгийн хялбар зам болно. Нэг удаа харуулж, дараа нь зөвхөн digest-ийг хадгалснаар өгөгдлийн санг уншсан хүн ч түүнийг сэргээж чадахгүй.

2. Нэвтрэлтийн урсгал

Стандарт authorization code + PKCE. Бусад grant (implicit, password) дэмжигдэхгүй.

2.1 Code verifier бэлдэх

code_verifier  = 43–128 тэмдэгтийн санамсаргүй мөр
code_challenge = BASE64URL( SHA256( code_verifier ) )

code_challenge_method нь зөвхөн S256. plain татгалзана — тэр нь PKCE-г утгагүй болгодог.

2.2 Хэрэглэгчийг илгээх

GET https://cloud.gerege.mn/openerp/oauth2/auth
  ?response_type=code
  &client_id=<таны client_id>
  &redirect_uri=<яг бүртгүүлсэн хаяг>
  &scope=openid profile email
  &state=<CSRF-ийн эсрэг санамсаргүй утга>
  &code_challenge=<дээрх>
  &code_challenge_method=S256

Платформ session-оо өөрөө уншина:

• нэвтрээгүй бол → нэвтрэх дэлгэц;
• ажлын талбар сонгоогүй бол → сонгогч;
• зөвшөөрөл дутуу бол → зөвшөөрлийн дэлгэц;
• бүгд бүрэн бол → redirect_uri?code=…&state=…

redirect_uri нь бүртгэсэнтэй яг тэнцүү байх ёстой — угтвар тааруулах, query үл тоох гэх мэт сулруулалт байхгүй. Client эсвэл redirect нь шалгагдаагүй байхад гарсан алдааг тэр хаяг руу буцаахгүй, платформ өөрийн дэлгэц дээр харуулна (нээлттэй чиглүүлэлтээс сэргийлнэ).

2.3 Токен солих

POST https://cloud.gerege.mn/openerp/oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=<буцаж ирсэн код>
&redirect_uri=<ижил хаяг>
&client_id=<client_id>
&code_verifier=<эх verifier>

Confidential client бол нэмж client_secret (form эсвэл HTTP Basic).

Хариу:

{
  "access_token": "…",
  "refresh_token": "…",
  "id_token": "…",
  "token_type": "Bearer",
  "expires_in": 3600
}

Код нэг удаагийн, 60 секунд амьдарна. Хоёр дахь удаа үзүүлбэл түүнээс гарсан бүх refresh хэлхээ устана — хуулбар нь хэн нэгний гарт байна гэсэн үг тул сэжигтэй хэлхээг бүхэлд нь хаана.

3. Токен ашиглах

GET https://cloud.gerege.mn/openerp/api/v1/contacts
Authorization: Bearer <access_token>

• id_token нь RS256-аар зурагдсан JWT. Түүнийг /.well-known/jwks.json дахь нийтийн түлхүүрээр шалгана.
• access_token нь opaque — задлах гэж бүү оролд. Хүчинтэй эсэхийг /oauth2/introspect-ээр шалгана.
• refresh_token нь эргэлддэг: шинэчлэх бүрд шинэ нь олгогдоно. Хуучныг дахин үзүүлбэл хэлхээ бүхэлдээ цуцлагдана.

Scope

Scope нь хэрэглэгчийн өөрийнх нь эрхийг өргөжүүлэхгүй. erp.write олгогдсон ч тухайн хүн нэхэмжлэх засах эрхгүй бол таны апп ч засахгүй.

4. UserInfo

GET /openerp/oauth2/userinfo
Authorization: Bearer <access_token>

Буцаах талбарууд нь олгогдсон scope-оор хязгаарлагдана. openid байхгүй бол дуудлага татгалзана.

5. Цуцлах

POST /openerp/oauth2/revoke     (client танилт шаардана)
POST /openerp/oauth2/introspect (RFC 7662, client танилт шаардана)

Хэрэглэгч өөрөө ч зөвшөөрлөө цуцалж болно — тэр үед таны аппын refresh токенууд хамт үхнэ.

6. Client-ээ удирдах

/developer/apps дээр client бүр дээрээ дөрвөн үйлдэлтэй. Бүгд зөвхөн бүртгэсэн ажлын талбарт нээлттэй — өөр талбарын client_id нэрлэвэл байхгүй client-тэй ижил хариу ирнэ.

6.1 Засах — PATCH /api/v1/developer/apps/{client_id}

Нэр, redirect_uris, scopes гурав засагдана.

redirect_uri буруу бол апп чинь хэнийг ч нэвтрүүлж чадахгүй болдог тул энэ нь хамгийн чухал нь. Шалгалт нь бүртгэхтэй яг ижил дүрэм: үнэмлэхүй хаяг, fragment (#) байхгүй, loopback-аас бусад нь HTTPS. Буруу утгыг сервер засаж залруулахгүй, татгалзана — чимээгүй өөрчилсөн redirect URI бол таны бүртгээгүй redirect URI.

grant_types ба token_endpoint_auth_method засагдахгүй. Confidential client-ийг public болгох (эсвэл эсрэгээр) нь аль хэдийн эргэлдэж буй токен бүр хэрхэн нотлогдсоныг өөрчилнө; тийм өөрчлөлтийг шинэ client бүртгээд түүн рүү шилжиж хийнэ.

6.2 Нууц шинэчлэх — POST /api/v1/developer/apps/{client_id}/secret

Шинэ нууц үүсч, хариултад нэг удаа харагдана. Хуучин нь тэр агшнаас ажиллахаа болино — бүх replica дээр, учир нь client бүрийг өгөгдлийн сангаас уншдаг.

Аль хэдийн олгогдсон access ба refresh токенууд хүчинтэй хэвээр үлдэнэ. Энэ нь зориудын шийдвэр: нууц бол token endpoint дээр client-ээ нотлох хэрэгсэл болохоос, тэдгээр токеныг үүсгэсэн түлхүүр биш. Токенууд нь мөн тэр client-д, мөн тэр хүмүүст, хэн ч буцаагаагүй зөвшөөрлийн үндсэн дээр олгогдсон. Нууц шинэчлэхэд хэрэглэгч бүр гарч унадаг байсан бол шөнө дунд гоожсон нууцаа солих хүн эргэлзэх байсан — тэр эргэлзээ нь өөрөө эмзэг байдал.

Токенууд нь ч бас эрсдэлд орсон гэж үзвэл энэ нь өөр үйлдэл: client-ээ идэвхгүй болго (доор), эсвэл нэг хүний зөвшөөрлийг цуцал.

Public client-д нууц байхгүй тул энэ үйлдэл 400 буцаана — PKCE нь түүний нотолгоо.

6.3 Идэвхгүй болгох — POST .../disable, POST .../enable

Идэвхгүй client нь /oauth2/token, /oauth2/auth, introspect, revoke хаана ч нэвтрэхээ болино, олгогдсон access ба refresh токен нь бүгд цуцлагдана.

Гэхдээ юу ч устахгүй: токен, зөвшөөрөл, authorization code-ийн мөрүүд байрандаа үлдэнэ. Иймээс аудитын мөр нь client-ээ зогсоох шийдвэрээс илүү удаан амьдарна. Зөвшөөрөл нь ч хэвээр — апп-д зөвшөөрөл өгөх эсэх нь хэрэглэгчийн шийдвэр, админых биш, тул буцааж идэвхжүүлэхэд хэн ч дахин асуугдахгүй. Цуцлагдсан токенууд сэргэхгүй; апп дараагийн нэвтрэлтэд шинийг авна.

6.4 Устгах — DELETE /api/v1/developer/apps/{client_id}

Огт ашиглагдаагүй client л устана. Токен, refresh токен, зөвшөөрөл, эсвэл authorization code-ийн аль нэг нь байсан бол сервер 409 буцаана.

Яагаад: тэдгээр хүснэгтийн гурав нь client дээр cascade хийдэг тул устгах нь client юу хийснийг тэмдэглэсэн бичлэгийг арчина; дөрөв дэх нь (oauth2_tokens) огт заадаггүй тул мөрүүд нь өнчирч, хугацаа дуустал ажилласаар байх болно. Аль нь ч credential-ыг эргүүлж авах зөв арга биш. Устгах нь буруу бөглөсөн, таван минутын настай, юу ч наалдаагүй бүртгэлд зориулагдсан.

7. Гадаад апп болгон нийтлэх

Apps сторт өөрийн аппаа гаргах бол manifest-д kind: "external" гэж зарлана. Тэр үед суулгах үйлдэл нь:

• OAuth2 client-ийг manifest-аас автоматаар үүсгэнэ (public, PKCE);
• webhook захиалгыг суулгах гүйлгээний дотор үүсгэнэ — «суулгасан» ба «захиалсан» хоёр хэзээ ч зөрөхгүй;
• хажуугийн цэсэнд аппыг чинь нээх мөр гарна.

Webhook нь HMAC гарын үсэгтэй ирнэ. Давтан суулгахад нууц эргэхгүй — эргэдэг бол таны аль хэдийн хадгалсан нууц чимээгүй хүчингүй болно.

Ийм client-ийг manifest нь удирдана: тэр нь ямар нэг ажлын талбарт харьяалагддаггүй тул /developer/apps дэлгэц дээр гарахгүй, §6-гийн үйлдлүүд ч түүнд хүрэхгүй. Redirect URI эсвэл scope-оо солих бол manifest-аа зас — дэлгэцээс хийсэн өөрчлөлт дараагийн ачаалалтад буцаж дарагдах байсан. Confidential client хэрэгтэй бол хөгжүүлэгчийн консолоор дамжуулан бүртгүүлнэ: тэнд нууцыг гардуулах хүн байгаа.

Дэлгэрэнгүйг Модуль зохиох гарын авлага-аас.

8. Алдааны хариултууд

Бүрэн жагсаалт: API лавлах.