OAuth2 / OIDC — қызметті Omniscol-ға қосу

Omniscol OAuth2 сервері ретінде не істейді

Сыртқы қызмет — ЖИ агенті, коннектор, бақылау тақтасы — Сіздің есептік жазбаңызда тіркелген клиентке айналады; мектеп пайдаланушысы оның қол жеткізуін келісім экраны арқылы бекітеді; содан кейін қызмет қол жеткізу токенін алады. Токен қысқа мерзімді, ал оның аясы берілген рұқсат ауқымдарымен және пайдаланушының құқықтарымен шектеледі.

Бұл тетік OIDC / SSO бетінде сипатталған пайдаланушылардың SSO-сынан өзгеше: онда Omniscol, керісінше, пайдаланушыларды қосу үшін Сіздің сәйкестендіру провайдеріңіздің клиенті болады. Мұнда Omniscol сервер жағында: оған қызметтер қосылады.

Omniscol-дың екі интеграциясы осы серверді пайдаланады:

• MCP — ЖИ агентінің стандартты аутентификациясы осы OAuth2 сервері арқылы өтеді (MCP — сыртқы ЖИ агентін қосу бетін қараңыз);
• OneRoster — OneRoster өндірушісі осы сервер беретін машинадан машинаға арналған OAuth2 токені арқылы аутентификациядан өтеді (OneRoster бетін қараңыз).

OAuth2 / OIDC стандартына сәйкес кез келген басқа қызмет оған дәл осылай қосыла алады.

Хаттаманың табу және қол жеткізу нүктелері

Omniscol табу метадеректерін Сіздің есептік жазбаңыздың домені түбірінде (мысалы, https://your-school.omniscol.com) стандартты .well-known мекенжайларында ұсынады. Стандартқа сәйкес клиент барлық қол жеткізу нүктелерін қолмен бапталмай-ақ өзі табады:

• /.well-known/oauth-authorization-server — авторизация серверінің метадеректері (RFC 8414);
• /.well-known/openid-configuration — OpenID Connect метадеректері (мазмұны алдыңғысымен бірдей);
• /.well-known/jwks.json — тексеруге арналған ашық кілттер (JWKS), id_token қолтаңбасын тексеруге мүмкіндік береді;
• /.well-known/oauth-protected-resource — қорғалған ресурс метадеректері (RFC 9728).

Бұл метадеректер хаттаманың қол жеткізу нүктелерін хабарлайды:

• /oauth/authorize — авторизация сұрауы (кіру, содан кейін келісім экраны);
• /oauth/token — кодты токенге айырбастау және жаңарту;
• /oauth/register — клиенттерді динамикалық тіркеу (RFC 7591);
• /oidc/userinfo — жүйеге кірген пайдаланушы туралы ақпарат (OIDC);
• /oauth/revoke — токенді кері қайтарып алу (RFC 7009).

Хаттаманың бұл қол жеткізу нүктелері ашық: олар Premium есептік жазбаларына арналмаған және оларды қолмен ашудың қажеті жоқ. Тек төменде сипатталған клиенттерді басқару экраны ғана Premium-ға жатады.

Авторизация ағындары

Omniscol OAuth2-нің үш ағынын қолдайды:

• PKCE бар авторизация коды — пайдаланушы атынан әрекет ететін қызмет үшін әдепкі ағын. Қызмет пайдаланушыны /oauth/authorize мекенжайына бағыттайды; кіру мен келісімнен кейін Omniscol авторизация кодын (5 минут жарамды) қайтарады, ал қызмет оны /oauth/token арқылы айырбастайды. Таңдалған PKCE әдісі — S256, ал қабылданатын жалғыз response_type — code.
• Жаңарту (refresh_token) — келісімнен қайта өтпей, берілген қол жеткізу мерзімін ұзарту үшін.
• Client credentials — пайдаланушысыз машинадан машинаға арналған ағын, әсіресе OneRoster тұтынушыларында қолданылады. Клиент тікелей аутентификациядан өтіп, қол жеткізу токенін алады.

Айырбастау кезінде сервер қол жеткізу токенін (Bearer, 1 сағат жарамды) және пайдаланушы ағындары үшін жаңарту токенін (30 күн жарамды) береді. openid рұқсат ауқымы сұралғанда, қолтаңбаланған OIDC id_token да беріледі; оның қолтаңбасы /.well-known/jwks.json арқылы тексеріледі. client_credentials ағыны тек қол жеткізу токенін береді, жаңарту токені мен id_token берілмейді.

Қол жеткізу токені кейін Authorization: Bearer <токен> HTTP тақырыбында беріледі. Әр шақыру кезінде Omniscol оның қолтаңбасын тексереді, клиенттің әлі де белсенді екенін, пайдаланушының әлі бар екенін және қажетті рөлі бар екенін, сондай-ақ токеннің рұқсат ауқымдары шақырылған қол жеткізу нүктесін қамтитынын тексереді — әйтпесе шақыру қабылданбайды.

Рұқсат ауқымдары және келісім

Клиентте Сіз басқаратын рұқсат ауқымдары (scopes):

• read:basic — кестелерді, бақылау тақталарын және қарау көріністерін оқу (Басты бет, Кесте, Бақылау тақтасы, Кестені басқару модульдері);
• read:user — пайдаланушылар тізімін оқу;
• write:data — осы қарау модульдеріне жазу;
• admin — әкімшілік қол жеткізу (Әкімшілік, Қатыспауды басқару, Кестені басқару модульдері).

Сервер OIDC рұқсат ауқымдарын (openid, email, profile) және тек оқуға арналған OneRoster рұқсат ауқымдарын (imsglobal.org префиксі) да біледі. Соңғылары айрықша құқықты: клиент оларды динамикалық тіркеу арқылы өзіне бере алмайды; оларды администратор клиент карточкасында қамтамасыз етуі қажет.

Нақты берілетін рұқсат ауқымы — клиент сұрайтын нәрсе мен оған тіркелген нәрсенің қиылысуы: клиент өз карточкасында көрсетілгеннен артық ештеңе алмайды. Пайдаланушы ағыны кезінде келісім экраны (/oauth/consent) сұраушы қызметтің атауын және логотипін, сондай-ақ сұралған рұқсат ауқымдарының оқуға ыңғайлы тізімін көрсетеді; онда Қабылдау және Бас тарту батырмалары бар. Қабылдау авторизация кодын береді және пайдаланушыны қызметке қайтарады; бас тартқанда пайдаланушы access_denied қатесімен қайтарылады.

Клиенттерді динамикалық тіркеу

/oauth/register қол жеткізу нүктесі динамикалық тіркеуді (Dynamic Client Registration, RFC 7591) жүзеге асырады: стандартқа сәйкес қызмет алдын ала қолмен араласусыз-ақ клиент ретінде өзін өзі мәлімдей алады. Дәл осы MCP агентіне тек сервер URL мекенжайы арқылы өзін баптауға мүмкіндік береді.

Динамикалық тіркеу өзіне айрықша рұқсат ауқымын бере алмайды (OneRoster рұқсат ауқымдары): олар үнсіз қабылданбайды, ал жарамды рұқсат ауқымы қалмаса, әдепкі бойынша read:basic беріледі. Айрықша рұқсат ауқымдары тек администратор қамтамасыз еткенде ғана беріледі.

OAuth2 клиенттерін басқару экраны

Premium есептік жазбаларында клиенттерді Әкімшілік → Импорт/Экспорт бөліміндегі OAuth2 секциясынан, OAuth2 батырмасы арқылы басқарасыз. Қол жеткізу үшін алдымен администратор құпиясөзі сұралады — экран ашылар алдындағы қосымша растау.

Экран тіркелген клиенттерді тізімдейді және әрқайсысы үшін оның күйін (белсенді / белсенді емес), атауын, рұқсат ауқымдарын, байланыстарын және URI-ларын (сайт, логотип, бағыттау URI-лары) көрсетеді. Мынаны істеуге болады:

• Клиентті тіркеу — атауын, міндетті емес software_id, рұқсат ауқымдарын, байланыстарды, сайтты, логотипті және бағыттау URI-ларын енгізіңіз. Жасалған кезде Omniscol client_id мен client_secret мәндерін бір рет көрсетеді.
• Клиентті өзгерту — тек қауіпсіз өрістер өзгертіледі: атауы, рұқсат ауқымдары, байланыстар, сайт және логотип. Бағыттау URI-лары, software_id және құпия мән мұнда өзгертілмейді.
• Клиентті белсендіру немесе өшіру — өшірілген клиенттің токендері келесі шақыруданақ қабылданбайды.
• Клиентті жою — жою қайтарылмайды.

Клиенттің құпия мәні

client_secret тіркеу кезінде бір рет қана көрсетіледі. Omniscol құпия мәннің тек ізін (хэшін) сақтайды, ашық түрде ешқашан сақтамайды: оны кейін қайта көрсету немесе қалпына келтіру мүмкін емес. Оны бірден құпияларды басқару құралына көшіріп алыңыз.

client_id болса, детерминистік: ол есептік жазба атауынан, клиент атауынан және оның техникалық метадеректерінің ізінен шығарылады. Сондықтан екі бірдей тіркеу бірдей идентификаторға әкеледі.

Құпия мәнді жаңарту (ротация)

Құпия мәнді ротациялау мүмкін: ол жаңа құпия мән шығарады, тек жаңа ізін сақтайды және осы жаңа құпия мәнді бір рет қана қайтарады. Ол динамикалық тіркеуді басқару қол жеткізу нүктесі (/oauth/register/<client_id>/rotation) арқылы орындалады және клиентке динамикалық тіркеу кезінде берілген тіркеу токенін көрсетуді қажет етеді. Сондықтан ол жоғарыда сипатталған басқару экранынан іске қосылмайды, себебі бұл экран ол токенмен жұмыс істемейді.

OAuth2 немесе API кілті: қайсысын таңдау керек

Omniscol машиналық қол жеткізудің екі тетігін ұсынады, олардың сенім модельдері әртүрлі:

• OAuth2 (осы бет) — тіркелген үшінші тарап пайдаланушының келісімінен кейін қысқа мерзімді (1 сағат), берілген рұқсат ауқымдарымен шектелген, жаңартылатын және кері қайтарылатын (клиентті өшіру арқылы) токен алады. client_credentials ағыны пайдаланушысыз машинадан машинаға қол жеткізуді де қамтиды. Бұл — анықталған үшінші тарап қызметіне, MCP мен OneRoster-ге сай келетін тәсіл.
• API кілті (Omniscol API бетін қараңыз) — сервер қол қоятын, рұқсат етілген қол жеткізу нүктелерінің тізімін қамтитын және сыртқы жүйеге өзіңіз беретін дербес токен: тіркелген үшінші тарап жоқ, келісім экраны жоқ, жаңарту жоқ. Бұл — администратордың өз құқықтарын өзі бақылайтын жүйеге беруі.

Қысқасы: API кілті өзіңіз бақылайтын жүйеге қол жеткізуді өзіңіз бергенде қолайлы; OAuth2 анықталған үшінші тарап қызметі берілген, рұқсат ауқымдарымен шектелген және кері қайтарылатын қол жеткізуді алуы керек болғанда немесе хаттама мұны талап еткенде (MCP, OneRoster) қолайлы.