Skip to content

Қосымшалар үшін ОАұтһ 2.0

ОАұтһ 2.0 қосымшаға пайдаланушы атынан Планфіх-ке пароль сұрамай немесе сақтамай қол жеткізуге мүмкіндік береді.

Планфіх міндетті түрде ПКЦЕ С256 қолданылатын Аұтһорізатіон Цоде ағынін (флоу) пайдаланады. ОАұтһ арқылы РЕСТ АПЫ немесе Планфіх МЦП сервері-ге қосылуға болады.

Дайын АЫ клиентін қосқыңыз келсе, алдымен Планфіх МЦП парағына қараңыз. Егер кіруді өз есеп жазбаңызда басқаратын болсаңыз, ОАұтһ анд МЦП аппліцатіонс ін ан аццоұнт парағына өтіңіз. Партнерлер мен көпесептік интеграцияларды жасаушыларға ОАұтһ аппліцатіонс фор партнерс пайдалы болады.

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

Опция Қашан қолдану қажет Қай жерде жұмыс істейді
Есептік жазбаға тиесілі қосымша Интеграция бір есептік жазбаға арналған және клиентке алдын ала анықталған client_id қажет. Тек оны тіркеген есептік жазбада.
Серіктеске тиесілі қосымша Бірдей қосымша бірнеше клиенттік есептік жазбаларға қосылуы керек. Қауіпсіздік саясаты немесе әкімші рұқсат еткен есептік жазбаларда.
Автоматты МЦП клиентін тіркеу МЦП клиенті Цліент ЫД Метадата Доцұмент (ЦЫМД) немесе Дyнаміц Цліент Регістратіон (ДЦР) қолдайды. Тіркеу өзімен бірге есептік жазбаға қолжетімділік бермейді. Қосымша әлі де таңдалған есептік жазбада рұқсат етілуі тиіс.

ЦЫМД және ДЦР тек МЦП қосылымдары үшін қолжетімді. РЕСТ АПЫ үшін есептік жазбаға тиесілі немесе серіктеске тиесілі қосымшаны пайдаланыңыз.

ОАұтһ соңғы нүктелері (ендпоінтс)

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

Мақсат Адрес
Ыссұер https://auth.planfix.com
Аұтһорізатіон https://auth.planfix.com/oauth/authorize
Токен https://auth.planfix.com/oauth/token
Ұсер інформатіон https://auth.planfix.com/oauth/userinfo
Токен ревоцатіон https://auth.planfix.com/oauth/revoke
Дyнаміц МЦП цліент регістратіон https://auth.planfix.com/oauth/register

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

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

Редірецт ҰРЫ-лар

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

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

  • https ҰРЛ-дары;
  • http ҰРЛ-дары тек лоопбацк хосттар (мысалы, localhost немесе 127.0.0.1) үшін ғана.

Лоопбацк ҰРЫ-де порт динамикалық болуы мүмкін, бірақ схемасы, хосты, жолы және сұраныс (құерy) сәйкес болуы тиіс. ҰРЛ фрагменттері және ҰРЛ ішіндегі пайдаланушы туралы ақпаратқа рұқсат жоқ.

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

Қосымша алдын ала рұқсат етілген қолжетімділік деңгейлері немесе scopes ғана алады. Толық тізім үшін РЕСТ АПЫ аццесс левелс қараңыз.

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

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

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

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

РЕСТ АПЫ мысалы: 

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

МЦП үшін дәл МЦП серверінің ҰРЛ-ін көрсететін resource параметрін қосыңыз: 

resource=https%3A%2F%2Fmcp.planfix.com%2Fmcp
Параметр Сипаттамасы
client_id Тіркелген қосымшаның идентификаторы. ЦЫМД үшін бұл клиент метадеректер құжатының ҰРЛ-і.
redirect_uri Рұқсат етілген Редірецт ҰРЫ-лардың бірі.
response_type code болуы қажет.
scope Бос орнымен бөлінген қажетті рұқсаттар. Бұл параметр РЕСТ АПЫ үшін міндетті. МЦП клиенті оны жібермеуі мүмкін — ондай жағдайда қосымшаға рұқсат етілген сцопе-тар қолданылады.
state Сұрауды алмастырудан қорғау үшін кездейсоқ мән. Қайта бағытталғаннан кейін қосымша оны тексеруі тиіс.
code_challenge code_verifier-дің СҺА-256 хэшінің паддінг-сыз басе64ұрл түрі.
code_challenge_method Тек S256 қолдау көрсетіледі.
resource МЦП үшін дәл ҰРЛ https://mcp.planfix.com/mcp. РЕСТ АПЫ үшін бұл параметрді жібермеңіз.

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

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

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

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

Токен алу

/oauth/token-ке ПОСТ сұрауын 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

МЦП үшін авторизация сұрауында қолданылғанмен дәл сол resource параметрін қайталаңыз.

Паблик (пұбліц) клиент сұрауды секретсіз жібереді. Конфиденциалды (цонфідентіал) клиент 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"
}

РЕСТ АПЫ үшін жауапта қосымша account_name, account_domain, және account_url болады. Осы мәндерді сақтап, РЕСТ АПЫ сұрауларында таңдалған есептік жазбаның ҰРЛ-ін пайдаланыңыз.

Аццесс токен 24 сағатқа жарамды. Ол пайдаланушыға, есептік жазбаға, қосымшаға, сцопе-тарға және ресоұрце-қа байланысты. МЦП үшін берілген токен тікелей РЕСТ АПЫ-де қолданылмайды, және РЕСТ АПЫ үшін берілген токен МЦП-де қолданылмайды.

РЕСТ АПЫ-мен токенді пайдалану

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

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

Токен алмастыру кезінде аұтһорізатіон цоде-ты айырбастау кезінде қайтарылған есептік жазба ҰРЛ-ін қолданыңыз. Тек рұқсат етілген сцопе-тармен қамтылған әдістерге қолжетімділік бар. ОАұтһ токендері есептік жазба жоспарына және стандартты РЕСТ АПЫ лімітс шектеулеріне бағынады.

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

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

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

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

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

Ғаламдық ОАұтһ авторизациясы есептік жазбаның қызметкерлері үшін қолжетімді. Планфіх 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

МЦП үшін дәл сол resource мәнін жіберіңіз. Конфиденциалды клиент өз секретімен аутентификациялануы тиіс.

Планфіх жаңа аццесс токен және жаңа рефресһ токен қайтарады. Алдыңғы рефресһ токен дереу жарамсыз болады, сондықтан қосымша сақталған мәнді атомарлы түрде алмастыруы тиіс.

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

Клиент рефресһ токен-ды /oauth/revoke арқылы қайтарып тастай алады: 

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

token=REFRESH_TOKEN
&client_id=CLIENT_ID

Пайдаланушы өз байланысын өзінің пайдаланушы картасындағы Сессіон манагемент бөлімінен де өшіре алады. Әкімші үшінші тарап қосымшасының мақұлдауын бүкіл есептік жазба үшін қайтаруы мүмкін. ОАұтһ анд МЦП аппліцатіонс ін ан аццоұнт қараңыз.

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

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

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

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

  • Әрқашан ПКЦЕ С256 қолданыңыз және state-ті тексеріңіз.
  • Мобильді, десктоп және браузер қосымшалары үшін секретсіз (пұбліц) клиент пайдаланыңыз.
  • Секрет серверде сенімді түрде сақталатын кезде ғана конфиденциалды клиентті пайдаланыңыз.
  • Қажет минимум сцопе-тарды сұраңыз.
  • Аццесс токен-дарды, рефресһ токен-дарды, аұтһорізатіон цоде-тарды, code_verifier-ді немесе клиент секреттерін журналдарға жазбаңыз.
  • Рефресһ токен-дар мен клиент секреттерін шифрланған сақтау орнында сақтаңыз.
  • Жауаптағы iss-ті тексеріңіз және тек күтілген Планфіх іссұер-ін ғана қабылдаңыз.

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

Қате Себебі
invalid_client Клиент белгісіз немесе өшірілген, клиент секреті дұрыс емес, немесе қосымша таңдалған есептік жазбада қолжетімді емес.
invalid_grant Авторизация коды немесе рефресһ токен жарамсыз, мерзімі өткен, бұрын қолданылған, немесе клиентке, редірецт ҰРЫ-ге, ПКЦЕ деректеріне немесе ресоұрце-қа сәйкес келмейді.
invalid_scope Сұрау қосымшаға рұқсат етілмеген сцопе-ты қамтиды.
invalid_target resource қолдау көрсетілмейді немесе сұраулар арасында өзгерген.
access_denied Пайдаланушы қосылудан бас тартты немесе есептік жазба саясаты қосымшаны рұқсат етпейді.
ҺТТП 401, invalid_token Аццесс токен белгісіз, мерзімі өткен немесе қайтарылған.
ҺТТП 403, insufficient_scope Операция үшін қажет сцопе токенде жоқ.

Өту (Го То)

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