КБП арқылы кіру.
Жобаңызды қосу

1. КБП мен қолданбаның міндеттері

https://lk.kbp.kz мекенжайындағы КБП — тіркелгі мен құпиясөздің жалғыз көзі. OpenID Connect (OIDC), PKCE S256 бар Authorization Code Flow қолданылады. Орталық компонент — oidc-provider 9.12.2; қолданба үлгісі — openid-client 6.8.8 және jose 6.2.10. Протоколды өзіңіз қайта жазбаңыз: өз тіліңіздің қолдау көрсетілетін OIDC кітапханасын қолданыңыз.

Ойын жеке тұлғаның расталуын алып, өз профилін, прогресін, құқықтарын және сессиясын жасайды. Құпиясөз тек КБП сайтында енгізіледі. Қолданба КБП әкімшілік құқықтарын, жарнама балансын, құжаттарын, БСН-ын, телефонын не туған күнін алмайды. SSO токені кабинет пен әкімшілік панельдің әдеттегі API шақыруларына жарамайды.

Орталық пен дайын үлгінің болуы ойыныңыздың қосылғанын білдірмейді. Жұмыс істейтін қосылым үшін нақты мекенжайлар, ашық кілттер, тізілім баптауы және ойын серверінде тексерілген қолжетімділікті қайтарып алу тетігі қажет.

2. Қосылымды қалай алуға болады

1. HTTPS-та серверлік қолданба дайындаңыз. SPA немесе мобильді интерфейс өзінің backend/BFF серверін қолданады; жабық кілт пен токендер браузер JavaScript-інде, localStorage-та, мобильді бинарлық файлда немесе Tilda-да орналастырылмайды.
2. Жеке RSA кілт жұбын жасаңыз: 3072 бит (2048–4096 рұқсат етіледі), RS256 алгоритмі, бірегей kid. Үлгіде: node keys.mjs. private/client-key.json файлы қолданба серверінде, 0600 режимінде қалады. private/session-key файлы да жабық.
3. КБП бас әкімшісіне тек client-public-jwks.json, жоба атауын, сұратылатын scopes және төмендегі кестедегі нақты URL-дарды беріңіз. Ашық JWKS құпия емес. Берілетін кілтте d, p, q, dp, dq, qi өрістері болмауы тиіс.
4. Қолданыстағы 2FA растауы бар бас әкімші https://admin.kbp.kz/sso-admin → «Единый вход → Проекты» бөлімін ашып, қосылым жасайды және client_id береді. client_id — құпиясөз емес, жария идентификатор.
5. Қолданба серверін баптап, 13-бөлімдегі тексерулерді орындаңыз. Тексеруден кейін әкімші жобаны қосады.

Ортақ client_secret орнына private_key_jwt қолданылады: қолданба сервері өзінің жабық кілтімен қысқа мерзімді бір реттік мәлімдемеге қол қояды. КБП оны тіркелген ашық JWKS арқылы тексереді. Бұл әдісте КБП қолданба құпиясын бермейді және сақтамайды; интеграцияға КБП тіркелгісінің құпиясөзі қажет емес. Кілттері бар экран суреттері мен жабық файлдардың мазмұнын ешкімге жібермеңіз.

Барлық URL толық тіркеледі. Басқа жол, query, жол регистрі немесе соңғы қиғаш сызық — басқа мекенжай. Production-да wildcard, префикстер, фрагменттер, ішкі IP, localhost және динамикалық қайта бағыттауларға тыйым салынған. Шығу мекенжайлары тіркелген кіру мекенжайларының origin-іне тиесілі болады. КБП серверлік қайтарып алу мекенжайының жария DNS-ын тексеріп, тексерілген IP-ді сұрау уақытына бекітеді.

3. Орталық мекенжайлары

Issuer: `https://lk.kbp.kz/api/sso/oidc` — соңында / болмай, дәл салыстырылады.

Discovery: https://lk.kbp.kz/api/sso/oidc/.well-known/openid-configuration

Metadata-ны Discovery-ден кітапханамен жүктеңіз; соңғы мекенжайларды болжап құрастырмаңыз. Осы нұсқа үшін:

OAuth клиенттерін жария дербес тіркеу, implicit/password/client_credentials grant және plain PKCE қолдау таппайды. Жобаны тіркеу/өңдеу API-ы 2FA бар КБП әкімшілік сессиясын талап етеді; ойын токені оған жарамайды.

4. Қадамдық кіру

1. «КБП арқылы кіру» түймесі өз серверіңіздің /login мекенжайына апарады.
2. Сервер криптографиялық кездейсоқ state, nonce, code_verifier жасайды (кездейсоқтығы кемінде 32 байт). S256 challenge жасайды. Мәндерді браузердің HttpOnly cookie-іне байланған бір реттік контексте, тек серверде, ең көбі 15 минут сақтайды.
3. Сервер браузерді authorization_endpoint мекенжайына client_id, нақты redirect_uri, response_type=code, scope, state, nonce, code_challenge, code_challenge_method=S256 параметрлерімен бағыттайды. offline_access үшін prompt=consent міндетті. Тіл үшін: ui_locales=ru немесе kk. Кіру iframe және бөгде cookie қолданбай, әдеттегі қойындыда өтеді.
4. Қолданыстағы КБП сессиясы болса, құпиясөзді қайта енгізу қажет емес. Әйтпесе пайдаланушы әдеттегі тәсілмен кіреді. Жаңа пайдаланушы тіркеліп, email растайды. Растағаннан кейін сол браузерде жобаға кіруді жалғастыра алады; мерзімі өткен немесе басқа құрылғыда ашылған контекст қолданбадан кіруді қайта бастауды талап етеді. Email-ы расталмаған ескі тіркелгі де расталғанға дейін SSO қолжетімділігін алмайды.
5. КБП жоба атауы мен сұратылатын деректерді көрсетеді. Пайдаланушы жалғастырады немесе бас тартады.
6. Қолданба callback-ы өз серверлік контекстін бір рет алып, жояды, state салыстырып, бастапқы verifier мен private_key_jwt беріп, кодты серверде алмастырады. Сәйкессіздік, қате/бас тарту немесе cookie жоқ болса, сессия жасамайды.
7. OIDC кітапханасы ID Token қолтаңбасын JWKS бойынша, iss, өз client_id-інің aud мәнін, exp, iat, nonce, күтілетін code flow мен жауапты тексереді. Тікелей HTTPS алмасуда да ID Token қолтаңбасын тексеруді қосыңыз; үлгіде бұл — enableNonRepudiationChecks.
8. Қажет болса сервер UserInfo сұратып, оның sub мәні ID Token-ге сәйкес келетінін тексереді. Email сұрайтын үлгіде қосымша email_verified === true тексеріледі.
9. Транзакцияда (issuer,sub) бойынша өз профилі жасалады/табылады және жаңа кездейсоқ жергілікті сессия жасалады. Cookie: host-only, HttpOnly, Secure, SameSite=Lax, Domain=.kbp.kz жоқ. Әдеттегі callback кез келген сайтқа апаратын пайдаланушылық returnTo қабылдамайды.
10. Өз әдеттегі бетіңізге қайта бағыттап, кодты мекенжай жолағынан дереу алып тастаңыз. Кодты, токенді немесе толық callback жолын access/error/analytics журналдарына сақтамаңыз.

Node.js-та кіруді бастаудың шағын мысалы (толық жұмыс істейтін код архивте):

import * as oidc from 'openid-client';
import { importJWK } from 'jose';
const key = await importJWK(privateJwk, 'RS256'); // сервердегі жабық файл
const config = await oidc.discovery(
  new URL('https://lk.kbp.kz/api/sso/oidc'), clientId,
  { token_endpoint_auth_method: 'private_key_jwt', id_token_signed_response_alg: 'RS256' },
  oidc.PrivateKeyJwt({ key, kid: privateJwk.kid }),
  { execute: [oidc.enableNonRepudiationChecks], timeout: 5 }
);
const verifier = oidc.randomPKCECodeVerifier();
const state = oidc.randomState(), nonce = oidc.randomNonce();
// verifier/state/nonce мәндерін серверде сақтап, бір реттік cookie-мен байланыстыру.
const url = oidc.buildAuthorizationUrl(config, {
  redirect_uri: registeredCallback,
  response_type: 'code', scope: 'openid profile email offline_access', prompt: 'consent',
  state, nonce, code_challenge: await oidc.calculatePKCECodeChallenge(verifier),
  code_challenge_method: 'S256', ui_locales: 'ru'
});
// Өз серверінің жауабы: url.href мекенжайына redirect 303.

Кітапханамен жауапты өңдеу:

const tokens = await oidc.authorizationCodeGrant(config, callbackUrl, {
  pkceCodeVerifier: saved.verifier, expectedState: saved.state,
  expectedNonce: saved.nonce, idTokenExpected: true
});
const identity = tokens.claims();
const info = await oidc.fetchUserInfo(config, tokens.access_token, identity.sub);
// Тексерулер профиль мен сессияның INSERT операциясына ДЕЙІН аяқталуы тиіс.

Қолтаңба тексеруін JWT-ді жай JSON.parse жасаумен алмастырмаңыз. ID Token — кіру растауы; тіркелгіні шексіз белсенді деп санаудың тәсілі емес.

5. Деректер және scopes

Клиент өз карточкасында рұқсат етілген scopes мәндерін ғана сұрай алады. Артық scope қабылданбайды. OIDC техникалық өрістері (iss, aud, iat, exp, nonce, sid) тексеруді қамтамасыз етеді, пайдаланушы құқықтары болып саналмайды. sid орталық сессияны шығу хабарламасымен байланыстырады; оны жергілікті сессияда сақтаңыз.

Ең аз сәйкестендіруге openid жеткілікті; есім мен email-ды қажет болғанда сұраңыз. Ұсынылған үлгі төрт scope-тың бәрін қолданады, сондықтан әкімші оларды дәл осы үлгіге рұқсат етуі тиіс. Жергілікті қолданбадағы email және name — жаңартылатын атрибуттар, жеке тұлға кілті емес. Email сәйкес келді деп әртүрлі (issuer,sub) мәндерін автоматты түрде біріктіруге болмайды.

CREATE UNIQUE INDEX game_profiles_identity ON game_profiles(issuer,subject);
-- Атомарлы INSERT ... ON CONFLICT(issuer,subject) ... RETURNING id.

Email өзгеруі екінші профиль жасамайды және прогресті көшірмейді. sub өзгермейді. КБП ойын құпиясөздерін қабылдамайды және ойын базасын басқармайды.

6. Мерзімдер және сақтау

КБП кабинетінің әдеттегі сессиясы бұрынғы күйінде қалады: бұл — бөлек cookie және бұрынғы кіру, 2FA мен шығу ережелері. Жергілікті сессия мерзімі өтсе, жаңа кіру қажет; refresh қайтарылып алынған жергілікті сессияны қалпына келтірмеуі тиіс.

Қолданба серверінде токендерді шифрлап, база/репозиторийден тыс бөлек кілтпен сақтаңыз. Үлгіде әр жазбаға бөлек кездейсоқ nonce және AAD тексеруі бар AES-256-GCM қолданылады. Cookie-де тек кездейсоқ идентификатор; базада оның hash-ы бар. Токендерді URL, HTML, хаттар, Telegram, журналдар, талдау жүйелері немесе localStorage ішіне салмаңыз.

7. Өзектілікті тексеру — міндетті бөлік

Ойын әрекеттерін орындауға ID Token қолтаңбасы жеткіліксіз. Әр қорғалған сұрау алдында қолданба өзінің қайтарылып алынбаған сессиясын және introspection нәтижесін тексереді. Сәтті жауапты сұрау басталған уақыттан есептеп, ең көбі 30 секунд кэштеуге болады. active === true, client_id === clientId, sub === session.subject шарттарын тексеріңіз.

const status = await oidc.tokenIntrospection(config, accessToken);
if (status.active !== true || status.client_id !== clientId || status.sub !== session.subject) {
  // Жергілікті сессияны қайтарып алу, қорғалған әрекетке тыйым салу, жаңа кіруді ұсыну.
}

Тіркелгі бұғатталса, жойылса, құпиясөз қалпына келтірілсе/өзгерсе, email растауы жоғалса, жалпы шығу орындалса немесе жоба өшірілсе, орталық тексеру бұрынғы қолжетімділікті дереу растауды тоқтатады. Бұғаттауды алу ескі токендер мен сессияларды қайта жандандырмайды.

КБП қолжетімсіз болса, желі таймауты болса немесе жауап тексерілмесе, рұқсат етілген кэш мерзімі аяқталғаннан кейін әрекетке тыйым салынады. Қате кезінде кэшті ұзартуға немесе тек ID Token бойынша ойынды жалғастыруға болмайды. Үлгіде мұндай қате сессияны аяқтайды; жоба оның орнына деректерді сақтай отырып, қорғалған әрекеттерді уақытша жаба алады, бірақ өзекті тексерусіз рұқсат бермеуі тиіс.

Осы шекті өз API-ы, WebSocket хабарламалары және фондық пайдаланушы әрекеттері үшін қолданбаның өзі қамтамасыз етеді. Ұзақ WebSocket-та қолжетімділікті кемінде әр 30 секунд сайын және қорғалған деректерді өзгертер алдында тексеріңіз. Орталық қайтарып алуды елемейтін ойынның кез келген сессиясын жаба алмайды.

8. Серверлік Back-Channel Logout

Қолданбаның тіркелген HTTPS endpoint-ы POST application/x-www-form-urlencoded қабылдайды, өрісі — logout_token. Мұнда браузер cookie-і мен Origin қажет емес: бұл — қол қойылған серверлік хабарлама. Origin ерекшелігін бүкіл API-ға емес, тек осы endpoint-қа шектеңіз.

JWT кітапханасын қолданыңыз. RS256, КБП JWKS бойынша қолтаңба, нақты issuer, өз клиентінің audience мәні, міндетті iat, jti, events, http://schemas.openid.net/event/backchannel-logout оқиғасы, nonce жоқтығы, sid және/немесе sub болуы тексеріледі. Үлгі жасы 120 секундқа дейінгі токенді, сағат айырмасына 5 секунд рұқсатпен қабылдайды. Сервер сағаттары синхрондалуы тиіс.

Бір транзакцияда бірегей (issuer,jti) тіркеп, issuer + sid бойынша сәйкес жергілікті сессияларды қайтарып алыңыз; sub бар болса, оны да тексеріңіз. Sid жоқ болса, осы sub-тың жергілікті сессияларын аяқтаңыз. Бір токен қайта жеткізілсе, сәтті 200/204 қайтарып, профиль/прогресті жоймауы тиіс. Жарамсыз қолтаңба немесе бөтен audience — өзгеріссіз 400/401.

КБП кезек пен жеткізу тарихын сақтайды. Алғашқы әрекет әдетте 5 секунд ішінде; желі таймауты 5 секунд; 5,10,20,40,80,160, одан кейін 300 секунд аралықтарымен 12 әрекетке дейін. Әр әрекет жаңа қол қойылған токен алады. Тарих бас әкімшіге жоба карточкасында қолжетімді; аяқталған техникалық жеткізу жазбалары 90 күн, жалпы қауіпсіз аудит КБП саясатына сай сақталады. Кезек introspection-ды алмастырмайды: барлық хабарлама жоғалса да, өзектілік тексеруі арқылы қайтарып алу шегі сақталады.

9. Шығудың үш бөлек әрекеті

• Ойындағы «Шығу»: тек ағымдағы жергілікті ойын сессиясын аяқтау (Origin + CSRF бар POST), өз cookie-ін тазалау. Басқа жобалар мен кабинет жұмысын жалғастырады. Әр жергілікті шығуда орталық жалпы шығуды шақырмаңыз және ортақ grant-ты қайтарып алмаңыз.
• RP-Initiated Logout: Discovery-дегі стандартты end_session_endpoint, тексерілген id_token_hint, тіркелген post_logout_redirect_uri және қайтқанда қолданба тексеретін state арқылы. КБП растау сұрайды. Ағымдағы орталық OIDC сессиясы мен байланысты рұқсаттар аяқталады; бұл «барлық құрылғы» командасы емес. Кабинеттің әдеттегі cookie-ін бұл протокол өзгертпейді.
• КБП профиліндегі «Барлық құрылғыларда барлық сервистерден шығу»: бөлек, анық расталатын команда; барлық құрылғылардағы кабинет сессиялары мен пайдаланушының орталық рұқсаттарын қайтарып алып, жобаларға хабарламаларды кезекке қояды. Ойын оларды өңдеуі және/немесе introspection бойынша қолжетімділікті жабуы тиіс. Деректер сақталады.

КБП кабинетінен әдеттегі шығу түймесі бұрынғы мағынасын сақтайды және жасырын жалпы шығуға айналмайды.

10. Refresh, қайтарып алу және қателер

offline_access серверге refresh шынымен қажет болғанда ғана керек. Access token-ді oidc.refreshTokenGrant(config, refreshToken) арқылы жаңартуға болады. Refresh token әр алмасуда өзгереді; жаңа жұпты атомарлы сақтап, бір жергілікті сессияның жаңартуларын кезекпен орындаңыз. Үлгі 5 секунд таймаутпен шектелген алмасу кезінде жергілікті сессия жолын бұғаттап ұстайды; қолданбаның бөлек базасын және орынды бұғаттау таймауттарын қолданыңыз.

Ескі refresh token-ді қайталау ротация кезінде берілген токендерді қоса, рұқсаттың бүкіл тобын қайтарып алады. invalid_grant → жергілікті сессияны жауып, жаңа кіруді бастаңыз. Ескі код/refresh алмасуын шексіз қайталамаңыз. 30 күн әр refresh-тен емес, бастапқы берілген кезден есептеледі.

Қолданба қолжетімділігін бөлек анық өшіру үшін кітапханамен token_revocation_endpoint қолданыңыз (oidc.tokenRevocation), содан кейін жергілікті сессияны аяқтаңыз. Бұл әдеттегі жергілікті шығудан бөлек.

11. Кілттерді ауыстыру

Қолданба кілттері: қолданба жасайды және сақтайды. Жаңа ашық JWKS-ты әкімші жоба карточкасында сақтайды. Қосылымды (соның ішінде кілттерді/мекенжайларды/scopes) өзгерту тек осы жобаның ескі қолжетімділігін қайтарып алады; пайдаланушылар қайта кіреді. Жабық кілт берілмейді. Жобаны өшіру пайдаланушыны және басқа қолданбаларды бұғаттамайды.

Орталық қолтаңба кілттері: kid өзгеруі мүмкін. Discovery/JWKS және белгісіз kid болғандағы стандартты кілт жаңартуын қолданыңыз. Әдеттегі ротация екі кезеңді: жаңа кілт алдымен JWKS-та пайда болады, бұрынғысы қол қоюды жалғастырады; кемінде 6 минуттан кейін (JWKS кэшін жаңарту терезесі 5 минутқа дейін) жаңасы белсенді болады. Қолданба JWKS кэшін кемінде әр 5 минут сайын жаңартуы тиіс. Орталық бұрынғы ашық кілтті кемінде 24 сағат сақтайды; ескі жабық кілт жаңа токендерге қолданылмайды. Қолданыстағы токендер 5 минут бойы тексеріле береді, refresh топтарының өзі ұзартылмайды. Бір кілтті мәңгі бекітпеңіз және kid ауысқанда қолтаңба тексеруін өшірмеңіз.

Кілт бұзылса, төтенше рәсім қолданылады: зардап шеккен қолжетімділікті қайтарып алу және бұзылған кілтті алып тастау, ескі токендердің үйлесімділігіне кепілсіз. Бұл — қосылған ойынның автоматты әрекеті емес, бөлек әкімшілік операция. Сақтау шифрлау кілті мен cookie қолтаңба кілтін басқа ортаның файлымен алмастырмаңыз.

12. Жұмыс үлгісін іске қосу

Архив: https://lk.kbp.kz/docs/kbp-sso-client.zip Осы нұсқаулықтың Markdown файлы: https://lk.kbp.kz/docs/kbp-sso-integration.kk.md

Құрамы: app.mjs, server.mjs, keys.mjs, schema.sql, .env.example, package.json, lockfile және README. Үлгіде ойын, төлемдер немесе дайын қолданыстағы кілттер жоқ. Бұл — бөлек PostgreSQL профильдері мен сессиялары бар серверлік қолданба.

1. Node.js 22.23+; қолданбаның өз базасы үшін PostgreSQL. Тәуелділіктерді pnpm install --frozen-lockfile арқылы орнатыңыз (не өз тексерілген менеджеріңізбен).
2. schema.sql файлын КБП тіркелгілері базасында емес, өз базаңызда орындаңыз.
3. node keys.mjs; жабық .env файлын .env.example бойынша баптаңыз; құпия файлдарға 0600, private каталогына 0700 беріңіз.
4. Ашық JWKS пен нақты URL-дарды әкімшіге беріп, өз client_id және рұқсат етілген scopes алыңыз.
5. Өз доменіңіздің HTTPS reverse proxy артында pnpm start іске қосыңыз. Private/.env/callback журналдарын жарияламаңыз. Cookie тек өз host-ына тиесілі.
6. /login ашып, кіріңіз; /me бөлек профильді көрсетеді. Жергілікті шығу басқа сервистерді аяқтамайды.
7. Жасанды тест тіркелгісінде, келісілген ортада бұғаттауды/хабарламаның жоғалуын/қайтарып алуды/қайталануларды тексеріңіз. Production-да жалған ойын төлемдерін немесе жаппай тіркелгілер жасамаңыз.

Жергілікті HTTP тек анық SSO_LOCAL_TEST=true, NODE_ENV != production, екі origin де http://127.0.0.1:<port> болғанда және бөлек кілттері/базасы бар жеке жергілікті орталықпен рұқсат етіледі. КБП жұмыс орталығы localhost тіркемейді. Production-issuer немесе нақты тіркелгілер үшін insecure режимін қоспаңыз.

Үлгі — дайын ойын платформасы емес, интеграция негізі: өз ойын ережелеріңізді, құқықтарды, API-ды, жиілік шектеулерін, инфрақұрылым қателерін өңдеуді, резервтеуді және мерзімі өткен жергілікті контекстерді/сессияларды/jti тазалауды қосыңыз. Әдеттегі шығу не бұғаттау кезінде профильдер мен прогресті жоймаңыз.

13. Қолданбаны әзірлеушінің қабылдауы

Қосар алдында мыналар тексерілуі тиіс: расталған кіру; екінші профильсіз қайта кіру; тіркелу/email және қайтумен қалпына келтіру; расталмаған/бұғатталған тіркелгіге тыйым; нақты redirect; қате state/nonce/PKCE; мерзімі өткен және қайталанған код; бөтен client_id/audience; профильді жоғалтпай email өзгерту; refresh rotation/replay; logout қолтаңбасы мен қайталанулары; ашық қолданбаның ≤60 секундта бұғатталуы; back-channel жоғалғанда да сол шек; 30 секундтық кэштен кейін орталықтың қолжетімсіздігі; басқа жобалардан шықпай, жергілікті шығу; прогресті жоймай жалпы шығу; бір клиентті өшіру; JWKS ротациясы; мобильді интерфейс пен тіл.

Орталық пен эталон клиентті тексеру болашақ ойынды қабылдауды алмастырмайды. Ойын әзірлеушісі барлық қорғалған әрекеттерді өзекті тексерумен қамтуға, өз рөлдеріне, профиліне, прогресіне, сатып алуларға, резервтік көшірмелерге, журналдарға және өз серверінің қауіпсіздігіне жауап береді.

14. Стандарттар көздері

• OIDC Core: https://openid.net/specs/openid-connect-core-1_0.html
• Discovery: https://openid.net/specs/openid-connect-discovery-1_0.html
• OAuth Security BCP: https://www.rfc-editor.org/rfc/rfc9700.html
• Introspection: https://www.rfc-editor.org/rfc/rfc7662.html
• Revocation: https://www.rfc-editor.org/rfc/rfc7009.html
• Back-Channel Logout: https://openid.net/specs/openid-connect-backchannel-1_0.html
• RP-Initiated Logout: https://openid.net/specs/openid-connect-rpinitiated-1_0.html
• Кітапханалар: https://github.com/panva/node-oidc-provider және https://github.com/panva/openid-client