5. «QAIRU арқылы кіру»: OAuth 2.0 және OpenID Connect

«QAIRU арқылы кіру» тәсілі сыртқы платформаға ақпараттық жүйе мәліметтерін студент атынан алуға мүмкіндік береді. Студент QAIRU кіру бетінде кіріп, келісім экранында қолжетімділік беруді растайды, осыдан кейін қосымша OAuth 2.0 (міндетті PKCE бар Authorization Code ағыны) және OpenID Connect хаттамалары бойынша токендер алады.

Кіруге тек студенттердің есептік жазбаларына рұқсат етіледі. Өзге есептік жазбамен кіру кіру бетінде қабылданбайды, ал қосымша жауап алмайды.

Бөлімнің мысалдарында алдыңғы қадамдарда алынған айнымалылар пайдаланылады: code_verifier, state, nonce, access_token, refresh_token.

5.1. Өзара әрекеттесу тәртібі

1. Қосымша PKCE параметрлерін, state және nonce мәндерін қалыптастырып, оларды пайдаланушының серверлік сеансында сақтайды.
2. Қосымша пайдаланушының браузерін авторизация мекенжайына бағыттайды.
3. Студент QAIRU есептік жазбасына кіріп, келісім экранында қолжетімділікті растайды.
4. Авторизация сервері браузерді авторизация кодымен бірге қайту мекенжайына қайтарады.
5. Қосымша сервері авторизация кодын токендерге алмастырады.
6. Қосымша /os/v1/… операцияларын қолжетімділік токенімен шақырады және оны refresh_token арқылы жаңартады.

5.2. Авторизация серверінің мекенжайлары

Авторизация серверінің мекенжайлары OpenID Connect Discovery құжатында жарияланады. Мекенжайларды кодта қолмен көрсетпей, осы құжаттан алу қажет.

https://auth.bbx.kz/realms/qairu/.well-known/openid-configuration

{
  "issuer": "https://auth.bbx.kz/realms/qairu",
  "authorization_endpoint": "https://auth.bbx.kz/realms/qairu/protocol/openid-connect/auth",
  "token_endpoint": "https://auth.bbx.kz/realms/qairu/protocol/openid-connect/token",
  "userinfo_endpoint": "https://auth.bbx.kz/realms/qairu/protocol/openid-connect/userinfo",
  "end_session_endpoint": "https://auth.bbx.kz/realms/qairu/protocol/openid-connect/logout",
  "revocation_endpoint": "https://auth.bbx.kz/realms/qairu/protocol/openid-connect/revoke",
  "jwks_uri": "https://auth.bbx.kz/realms/qairu/protocol/openid-connect/certs",
  "code_challenge_methods_supported": ["plain", "S256"]
}

Жауапта құжаттың үзіндісі келтірілген. Токендер қолтаңбасын тексеруге арналған ашық кілттер jwks_uri мекенжайында жарияланады.

5.3. PKCE, state және nonce параметрлері

Әрбір кіру үшін жаңа мәндер қалыптастырылады:

• code_verifier — A–Z, a–z, 0–9, -, ., _, ~ таңбалар жиынынан тұратын ұзындығы 43-тен 128 таңбаға дейінгі кездейсоқ жол;
• code_challenge — соңындағы = таңбаларынсыз BASE64URL(SHA-256(code_verifier)) мәні;
• state — сайтаралық сұрауларды қолдан жасаудан қорғауға арналған кездейсоқ мән; қайту кезінде салыстырылады;
• nonce — id_token ішінде қайтарылатын және оны тексеру кезінде салыстырылатын кездейсоқ мән.

# code_verifier: 86 characters of the base64url alphabet
CODE_VERIFIER=$(openssl rand -base64 64 | tr -d '\n=' | tr '+/' '-_' | cut -c1-86)

# code_challenge = BASE64URL(SHA-256(code_verifier))
CODE_CHALLENGE=$(printf '%s' "$CODE_VERIFIER" \
  | openssl dgst -sha256 -binary | openssl base64 | tr -d '\n=' | tr '+/' '-_')

STATE=$(openssl rand -hex 16)
NONCE=$(openssl rand -hex 16)

5.4. Авторизация мекенжайы

Пайдаланушының браузері мынадай параметрлермен authorization_endpoint мекенжайына бағытталады:

https://auth.bbx.kz/realms/qairu/protocol/openid-connect/auth
  ?response_type=code
  &client_id=ext-campus-planner
  &redirect_uri=https%3A%2F%2Fplanner.example.com%2Foauth%2Fcallback
  &scope=openid%20qairu.academic.read%20qairu.scheduling.read
  &state=af0ifjsldkj
  &nonce=n-0S6_WzA2Mj
  &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
  &code_challenge_method=S256
  &ui_locales=ru

5.5. Келісім экраны

Кіргеннен кейін студентке қосымшаның атауы және сұратылған модульдер тізбесі көрсетілген келісім экраны ашылады. Студент қолжетімділікке рұқсат береді немесе одан бас тартады.

• келісім сақталады: сол қолжетімділік аяларымен қайта кірген кезде келісім экраны көрсетілмейді;
• жаңа қолжетімділік аялары сұратылған кезде келісім экраны қайта көрсетіледі;
• тіркеу кезінде қосымшаға рұқсат етілмеген модульдердің қолжетімділік аялары берілмейді.

Қолжетімділікке рұқсат берілгенде браузер авторизация кодымен бірге қайту мекенжайына қайтарылады:

https://planner.example.com/oauth/callback?state=af0ifjsldkj&session_state=3f0c9a52-6d1e-4b8a-9f3e-2c7b5d8e1a40&iss=https%3A%2F%2Fauth.bbx.kz%2Frealms%2Fqairu&code=7b2e1f0a-5c3d-4e8f-a1b2-c3d4e5f6a7b8.3f0c9a52-6d1e-4b8a-9f3e-2c7b5d8e1a40.ext-campus-planner

Студент бас тартқан жағдайда қайту мекенжайында access_denied қате коды болады:

https://planner.example.com/oauth/callback?error=access_denied&error_description=User+denied+consent&state=af0ifjsldkj

5.6. Кодты токендерге алмастыру

Қосымша сервері token_endpoint мекенжайына application/x-www-form-urlencoded форматында POST сұрауын жібереді. Клиент HTTP Basic сұлбасы бойынша идентификатор мен құпия арқылы аутентификацияланады; client_id және client_secret параметрлерін сұрау денесінде беруге де жол беріледі.

curl -X POST https://auth.bbx.kz/realms/qairu/protocol/openid-connect/token \
  -u "ext-campus-planner:YOUR_CLIENT_SECRET" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d grant_type=authorization_code \
  -d code=AUTHORIZATION_CODE \
  --data-urlencode redirect_uri=https://planner.example.com/oauth/callback \
  -d code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 3600,
  "refresh_expires_in": 2592000,
  "refresh_token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "id_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "not-before-policy": 0,
  "session_state": "3f0c9a52-6d1e-4b8a-9f3e-2c7b5d8e1a40",
  "scope": "openid profile email qairu-student qairu.academic.read qairu.scheduling.read"
}

Жауап өрістері:

• access_token — API шақыруға арналған қолжетімділік токені; 1 сағат бойы жарамды (expires_in);
• refresh_token — жаңарту токені; сеанс 30 күнге дейін жарамды (refresh_expires_in);
• id_token — студент туралы мәліметтері бар OpenID Connect токені;
• scope — іс жүзінде берілген қолжетімділік аялары; тізбе сұратылғанмен сәйкес келмеуі мүмкін.

5.7. API-ді студент атынан шақыру

Қолжетімділік токені Authorization: Bearer <қолжетімділік токені> тақырыбында беріледі. Операция жолдары API токенімен авторизация кезіндегідей; қолжетімділік аялары берілген модульдердің GET әдісімен орындалатын операциялары, ал ALEM модулі үшін «Alem модулі» бөлімінде аталған операциялар қолжетімді.

curl https://api.bbx.kz/os/v1/me \
  -H "Authorization: Bearer ACCESS_TOKEN"

curl https://api.bbx.kz/os/v1/academic/catalog/disciplines \
  -H "Authorization: Bearer ACCESS_TOKEN"

Ақпараттық жүйе студенттің құқықтарын қолданады: жауапта студентке кабинетте қолжетімді мәліметтер ғана болады. Қолжетімділік токенімен жіберілген GET /os/v1/me сұрауы қосымша, студент және берілген модульдер туралы мәліметтерді қайтарады:

{
  "app": {
    "clientId": "ext-campus-planner",
    "name": "Campus Planner"
  },
  "user": {
    "sub": "8b6f1c2e-3a4d-4f5e-9a7b-1c2d3e4f5a6b",
    "name": "Aigerim Nurlanova",
    "email": "a.nurlanova@qairu.edu.kz",
    "studentId": "250142"
  },
  "modules": ["ACADEMIC", "SCHEDULING"],
  "expiresAt": "2026-10-28T09:00:00Z"
}

5.8. Қолжетімділік токенін жаңарту

Қолжетімділік токенінің мерзімі өткенде API-ге сұрау 401 invalid_token кодымен қабылданбайды. Жаңа қолжетімділік токені студенттің қатысуынсыз refresh_token арқылы сұратылады:

curl -X POST https://auth.bbx.kz/realms/qairu/protocol/openid-connect/token \
  -u "ext-campus-planner:YOUR_CLIENT_SECRET" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d grant_type=refresh_token \
  -d refresh_token=REFRESH_TOKEN

Жауаптың құрамы кодты алмастыру кезіндегідей. Алынған refresh_token бұрынғысының орнына сақталады.

5.9. id_token және пайдаланушы туралы мәліметтер

id_token пайдаланылар алдында jwks_uri кілттері бойынша қолтаңба, iss беруші, aud алушы (client_id мәніне сәйкес келеді), exp мерзімі және nonce мәні тексеріледі. id_token мазмұны:

{
  "exp": 1793178000,
  "iat": 1793174400,
  "auth_time": 1793174388,
  "iss": "https://auth.bbx.kz/realms/qairu",
  "aud": "ext-campus-planner",
  "sub": "8b6f1c2e-3a4d-4f5e-9a7b-1c2d3e4f5a6b",
  "typ": "ID",
  "azp": "ext-campus-planner",
  "nonce": "n-0S6_WzA2Mj",
  "sid": "3f0c9a52-6d1e-4b8a-9f3e-2c7b5d8e1a40",
  "name": "Aigerim Nurlanova",
  "given_name": "Aigerim",
  "family_name": "Nurlanova",
  "preferred_username": "a.nurlanova",
  "email": "a.nurlanova@qairu.edu.kz",
  "email_verified": true,
  "student_id": "250142"
}

Дәл осы мәліметтерді қолжетімділік токенімен userinfo_endpoint мекенжайына жіберілген сұрау қайтарады:

curl https://auth.bbx.kz/realms/qairu/protocol/openid-connect/userinfo \
  -H "Authorization: Bearer ACCESS_TOKEN"

{
  "sub": "8b6f1c2e-3a4d-4f5e-9a7b-1c2d3e4f5a6b",
  "name": "Aigerim Nurlanova",
  "given_name": "Aigerim",
  "family_name": "Nurlanova",
  "preferred_username": "a.nurlanova",
  "email": "a.nurlanova@qairu.edu.kz",
  "email_verified": true,
  "student_id": "250142"
}

5.10. Шығу

Шығу үшін қосымша сақталған токендерді жояды және жаңарту токенін кері қайтарып алады:

curl -X POST https://auth.bbx.kz/realms/qairu/protocol/openid-connect/revoke \
  -u "ext-campus-planner:YOUR_CLIENT_SECRET" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d token=REFRESH_TOKEN \
  -d token_type_hint=refresh_token

Браузердегі QAIRU сеансын аяқтау үшін пайдаланушы end_session_endpoint мекенжайына бағытталады. post_logout_redirect_uri параметріне тек қосымшаны тіркеу кезінде көрсетілген мекенжай үшін жол беріледі.

https://auth.bbx.kz/realms/qairu/protocol/openid-connect/logout
  ?client_id=ext-campus-planner
  &id_token_hint=ID_TOKEN
  &post_logout_redirect_uri=https%3A%2F%2Fplanner.example.com%2F

5.11. Студенттің қолжетімділікті кері қайтарып алуы

Студент қосымшаны кабинетте ажыратады: «Профиль» бөлімі, «Қосылған қосымшалар» карточкасы, «Ажырату» әрекеті. Ажыратқаннан кейін:

• қосымшаға берілген қолжетімділік және жаңарту токендері дереу жарамсыз болады;
• бұрынғы қолжетімділік токенімен API-ге жіберілген сұраулар 401 token_revoked кодымен қабылданбайды;
• токенді жаңарту invalid_grant қатесімен аяқталады;
• келесі кіру кезінде студентке келісім экраны қайта көрсетіледі.

{
  "error": {
    "type": "authentication_error",
    "code": "token_revoked",
    "message": "The student has revoked access for this application.",
    "request_id": "0d8e4c1a-7f2b-4a9e-b3c5-6e1d2f8a9b70"
  }
}

Университет әкімшілігі қосымшаны толық ажырата алады. Бұл жағдайда сұраулар 403 app_disabled кодымен қабылданбайды, ал қосымша арқылы кіру мүмкін болмайды.

5.12. Жарамдылық мерзімдері

5.13. OAuth қателері

Авторизация серверінің қателері OAuth 2.0 хаттамасы бойынша қайтарылады: авторизация кезінде — қайту мекенжайының error және error_description параметрлерімен, токендер беру кезінде — жауап денесімен:

{
  "error": "invalid_grant",
  "error_description": "Code not valid"
}

Студенттің қолжетімділік токеніне байланысты API қате кодтары «Қате кодтары» бөлімінде келтірілген.

5.14. Қолжетімділік аялары

Әдепкі қолжетімділік аялары қосымшаға әрбір кіру кезінде беріледі. Модульдердің қолжетімділік аялары scope параметрінде көрсетіледі және тіркеу кезінде қосымшаға рұқсат етілген модульдер үшін ғана беріледі.