Skip to content

Қосымшалар үшін OAuth 2.0

OAuth 2.0 қосымшаға пайдаланушы атынан Planfix-ке пароль сұрамай немесе сақтамай қол жеткізуге мүмкіндік береді.

Planfix міндетті түрде PKCE S256 қолданылатын Authorization Code ағынін (flow) пайдаланады. OAuth арқылы REST API немесе Planfix MCP сервері-ге қосылуға болады.

Дайын AI клиентін қосқыңыз келсе, алдымен Planfix MCP парағына қараңыз. Егер кіруді өз есеп жазбаңызда басқаратын болсаңыз, OAuth and MCP applications in an account парағына өтіңіз. Партнерлер мен көпесептік интеграцияларды жасаушыларға OAuth applications for partners пайдалы болады.

Қосымшаны тіркеудің опциялары

Опция Қашан қолдану қажет Қай жерде жұмыс істейді
Есептік жазбаға тиесілі қосымша Интеграция бір есептік жазбаға арналған және клиентке алдын ала анықталған client_id қажет. Тек оны тіркеген есептік жазбада.
Серіктеске тиесілі қосымша Бірдей қосымша бірнеше клиенттік есептік жазбаларға қосылуы керек. Қауіпсіздік саясаты немесе әкімші рұқсат еткен есептік жазбаларда.
Автоматты MCP клиентін тіркеу MCP клиенті Client ID Metadata Document (CIMD) немесе Dynamic Client Registration (DCR) қолдайды. Тіркеу өзімен бірге есептік жазбаға қолжетімділік бермейді. Қосымша әлі де таңдалған есептік жазбада рұқсат етілуі тиіс.

CIMD және DCR тек MCP қосылымдары үшін қолжетімді. REST API үшін есептік жазбаға тиесілі немесе серіктеске тиесілі қосымшаны пайдаланыңыз.

OAuth соңғы нүктелері (endpoints)

Жаңа интеграциялар ғаламдық (global) соңғы нүктелерді пайдалануы керек. Осы URL-дерге есептік жазба атауы ендірілмейді: пайдаланушы авторизация кезінде есептік жазбаны таңдайды.

Мақсат Адрес
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

Авторизация серверінің метадеректері стандартты соңғы нүктелерде қолжетімді: 

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

Redirect URI-лар

Redirect URI қосымша параметрлерінде тіркелуі тиіс. Авторизация сұрауында жіберілген мән тіркелген URI-ға сәйкес болуы керек.

Рұқсат етілгендер:

  • https URL-дары;
  • http URL-дары тек loopback хосттар (мысалы, localhost немесе 127.0.0.1) үшін ғана.

Loopback URI-де порт динамикалық болуы мүмкін, бірақ схемасы, хосты, жолы және сұраныс (query) сәйкес болуы тиіс. URL фрагменттері және URL ішіндегі пайдаланушы туралы ақпаратқа рұқсат жоқ.

Қолжетімділік деңгейлері

Қосымша алдын ала рұқсат етілген қолжетімділік деңгейлері немесе scopes ғана алады. Толық тізім үшін REST API access levels қараңыз.

Сұралған жиынтық қосымшаға тіркелген scope-тардың көмескісі (subset) болуы тиіс. Қосымша scope-тары Planfix ішіндегі пайдаланушының рұқсаттарын кеңейтпейді: қосымша тек қосқан қызметкерге қолжетімді деректерге ғана қол жеткізе алады.

Басқарылатын қосымшаларға қосымша қызметтік scope-тар userinfo, openid, және email беріледі.

Пайдаланушы авторизациясы

code_verifier және оның SHA-256 түрлендірілуі code_challenge құрыңыз, содан кейін авторизация соңғы нүктесін браузерде ашыңыз.

REST API мысалы: 

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 үшін дәл MCP серверінің URL-ін көрсететін resource параметрін қосыңыз: 

resource=https%3A%2F%2Fmcp.planfix.com%2Fmcp
Параметр Сипаттамасы
client_id Тіркелген қосымшаның идентификаторы. CIMD үшін бұл клиент метадеректер құжатының URL-і.
redirect_uri Рұқсат етілген Redirect URI-лардың бірі.
response_type code болуы қажет.
scope Бос орнымен бөлінген қажетті рұқсаттар. Бұл параметр REST API үшін міндетті. MCP клиенті оны жібермеуі мүмкін — ондай жағдайда қосымшаға рұқсат етілген scope-тар қолданылады.
state Сұрауды алмастырудан қорғау үшін кездейсоқ мән. Қайта бағытталғаннан кейін қосымша оны тексеруі тиіс.
code_challenge code_verifier-дің SHA-256 хэшінің padding-сыз base64url түрі.
code_challenge_method Тек S256 қолдау көрсетіледі.
resource MCP үшін дәл URL https://mcp.planfix.com/mcp. REST API үшін бұл параметрді жібермеңіз.

Пайдаланушы есептік жазбаны таңдап, жүйеге кіреді және сұралған рұқсаттарды қарайды. Есептік жазбаға тиесілі қосымша тікелей өзінің иелік ететін есептік жазбасын ашады. Егер қауіпсіздік саясаты әкімші мақұлдауын талап етсе, Planfix тиісті қадамды көрсетеді. Әкімші қосымшаны мақұлдап, оны бір әрекетпен қосуы мүмкін.

Табысты авторизациядан кейін Planfix браузерді redirect_uri-ге қайта бағыттайды: 

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

Авторизация коды бір реттік және 10 минут ішінде жарамды.

Токен алу

/oauth/token-ке POST сұрауын application/x-www-form-urlencoded түрінде жіберіңіз: 

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 үшін авторизация сұрауында қолданылғанмен дәл сол resource параметрін қайталаңыз.

Паблик (public) клиент сұрауды секретсіз жібереді. Конфиденциалды (confidential) клиент client_secret_basic арқылы немесе сұрау денесінде client_id және client_secret параметрлерімен аутентификацияланады.

Мысал жауап: 

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

REST API үшін жауапта қосымша account_name, account_domain, және account_url болады. Осы мәндерді сақтап, REST API сұрауларында таңдалған есептік жазбаның URL-ін пайдаланыңыз.

Access token 24 сағатқа жарамды. Ол пайдаланушыға, есептік жазбаға, қосымшаға, scope-тарға және resource-қа байланысты. MCP үшін берілген токен тікелей REST API-де қолданылмайды, және REST API үшін берілген токен MCP-де қолданылмайды.

REST API-мен токенді пайдалану

Токенді Authorization тақырыбында жіберіңіз: 

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

Токен алмастыру кезінде authorization code-ты айырбастау кезінде қайтарылған есептік жазба URL-ін қолданыңыз. Тек рұқсат етілген scope-тармен қамтылған әдістерге қолжетімділік бар. OAuth токендері есептік жазба жоспарына және стандартты REST API limits шектеулеріне бағынады.

Пайдаланушы туралы ақпарат

userinfo сұрауы openid scope-ын талап етеді: 

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

email scope-ы бар кезде мысал жауап: 

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

Ғаламдық OAuth авторизациясы есептік жазбаның қызметкерлері үшін қолжетімді. Planfix id_token шығармайды; пайдаланушы деректерін алу үшін userinfo-ды сұраңыз.

Токендерді жаңарту

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 үшін дәл сол resource мәнін жіберіңіз. Конфиденциалды клиент өз секретімен аутентификациялануы тиіс.

Planfix жаңа access token және жаңа refresh token қайтарады. Алдыңғы refresh token дереу жарамсыз болады, сондықтан қосымша сақталған мәнді атомарлы түрде алмастыруы тиіс.

Токенді қайтару (revoke)

Клиент refresh token-ды /oauth/revoke арқылы қайтарып тастай алады: 

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

token=REFRESH_TOKEN
&client_id=CLIENT_ID

Пайдаланушы өз байланысын өзінің пайдаланушы картасындағы Session management бөлімінен де өшіре алады. Әкімші үшінші тарап қосымшасының мақұлдауын бүкіл есептік жазба үшін қайтаруы мүмкін. OAuth and MCP applications in an account қараңыз.

Бар интеграциялармен үйлесімділігі

https://account.planfix.com/api/v2/oauth/authorize, /token, және /userinfo сияқты тенант (tenant) соңғы нүктелері нақты есептік жазбаға байланған бұрыннан бар интеграциялар үшін жұмысын жалғастырады.

Жаңа интеграциялар үшін ғаламдық соңғы нүктелерді пайдаланыңыз. Олар стандартты метадеректерді табуды, есептік жазбаны таңдауды және MCP-ні қолдайды. Бір OAuth сеансына ғаламдық және тенант соңғы нүктелерін араластырып қолданбаңыз.

Қауіпсіздік бойынша ұсыныстар

  • Әрқашан PKCE S256 қолданыңыз және state-ті тексеріңіз.
  • Мобильді, десктоп және браузер қосымшалары үшін секретсіз (public) клиент пайдаланыңыз.
  • Секрет серверде сенімді түрде сақталатын кезде ғана конфиденциалды клиентті пайдаланыңыз.
  • Қажет минимум scope-тарды сұраңыз.
  • Access token-дарды, refresh token-дарды, authorization code-тарды, code_verifier-ді немесе клиент секреттерін журналдарға жазбаңыз.
  • Refresh token-дар мен клиент секреттерін шифрланған сақтау орнында сақтаңыз.
  • Жауаптағы iss-ті тексеріңіз және тек күтілген Planfix issuer-ін ғана қабылдаңыз.

Мүмкін қателер

Қате Себебі
invalid_client Клиент белгісіз немесе өшірілген, клиент секреті дұрыс емес, немесе қосымша таңдалған есептік жазбада қолжетімді емес.
invalid_grant Авторизация коды немесе refresh token жарамсыз, мерзімі өткен, бұрын қолданылған, немесе клиентке, redirect URI-ге, PKCE деректеріне немесе resource-қа сәйкес келмейді.
invalid_scope Сұрау қосымшаға рұқсат етілмеген scope-ты қамтиды.
invalid_target resource қолдау көрсетілмейді немесе сұраулар арасында өзгерген.
access_denied Пайдаланушы қосылудан бас тартты немесе есептік жазба саясаты қосымшаны рұқсат етпейді.
HTTP 401, invalid_token Access token белгісіз, мерзімі өткен немесе қайтарылған.
HTTP 403, insufficient_scope Операция үшін қажет scope токенде жоқ.

Өту (Go To)

«http://planfix.com/kk/help/index.php?title=Қосымшалар_үшін_OAuth_2.0&oldid=7898» бетінен алынған