upID sənədləşdirməsi

Giriş necə işləyir

upID istifadəçinin şəxsiyyətini OpenID Connect vasitəsilə təsdiqləyir. İstifadəçilərinizin, sessiyalarınızın, rollarınızın və biznes icazələrinizin idarə edilməsi sizin sisteminizdə qalır. upID-də təsdiqlənmiş giriş istifadəçiyə avtomatik rol təyin etmir və təşkilatınızın məlumatlarına giriş vermir.

1. Serveriniz birdəfəlik giriş cəhdi yaradır və brauzeri upID-yə yönləndirir.
2. upID QR-kod və ya telefon nömrəsi ilə girişi göstərir. İstifadəçi sorğunu əlaqələndirilmiş cihazdakı upID tətbiqində təsdiqləyir.
3. Brauzer birdəfəlik code və state ilə callback ünvanınıza qayıdır. Müştəri sirri və verifier brauzer vasitəsilə ötürülmür.
4. Serveriniz code-u tokenlərlə mübadilə edir, ID Token-i və razılaşdırılmış giriş icazəsi siyasətini yoxlayır. Sonra şəxsiyyəti lokal istifadəçi ilə əlaqələndirir və tətbiq sessiyasını yaradır.

İnteqrator girişin başlanmasını, callback-i və öz sessiyasını reallaşdırır. QR, cihaz təsdiqi, telefon nömrəsi və hesabın bərpası upID tərəfindən idarə edilir. Daxili mobil API-ləri layihənizə köçürmək lazım deyil.

Qoşulmadan əvvəl

Mövcud profil client_secret-i brauzerdən kənarda saxlaya bilən server tərəfli veb tətbiq üçün nəzərdə tutulub. Platformanızın OIDC kitabxanasından istifadə edin; JWT-ni əl ilə dekodlaşdırmaq şəxsiyyətin yoxlanmasını əvəz etmir.

Yeni tətbiq üçün server tərəfdə ayrıca icazə addımı lazımdır: müştəri, callback və sessiya siyasəti razılaşdırılmalıdır. Müştərilərin özünəxidmət qeydiyyatı hələ yoxdur. İstənilən client_id qeydinin mövcudluğu özlüyündə cari pilotun məhdudiyyətlərini aradan qaldırmır.

upID operatorundan əldə edin

• Razılaşdırılmış mühit üçün dəqiq HTTPS issuer. Onu server konfiqurasiyasında saxlayın; callback məlumatlarına və ya Host başlığına əsasən seçməyin.
• Tətbiq və mühit üçün ayrıca client_id və client_secret. Sirr serverin məxfi məlumatlar anbarında saxlanılır; HTML-ə, frontend bundle-a, mobil tətbiqə və ya Git-ə daxil edilmir.
• Maskalar və ixtiyari qayıdış ünvanları olmayan, qeydiyyatdan keçirilmiş HTTPS callback. Giriş sorğusunda və code mübadiləsində eyni dəqiq redirect_uri sətrindən istifadə olunur.
• Mövcud scopes, müştərinin autentifikasiya üsulu, imza alqoritmi, giriş icazəsinin aktuallığının yoxlanması və çıxış tələblərinin təsdiqi.

Server müştərisinin profili

issuer = OPERATOR_CONFIRMED_HTTPS_ISSUER
client_id = REGISTERED_CLIENT_ID
client_secret = SERVER_SECRET_STORE
redirect_uri = https://app.example.com/auth/upid/callback
response_type = code
scope = openid profile
code_challenge_method = S256
token_endpoint_auth_method = client_secret_basic
id_token_signed_response_alg = RS256

Bu, şərti dəyərlərlə verilmiş sxemdir; hazır giriş məlumatları və ya real iş mühitinə sorğu deyil. Həqiqi ünvanları və parametrləri OIDC kitabxananız formalaşdırır. HTTP nümunələrində sətir keçidləri oxunaqlılıq üçün əlavə edilib.

Mühit və endpoint-lər

Razılaşdırılmış issuer-ə nəzərən /.well-known/openid-configuration sənədini yükləyin. issuer sahəsinin konfiqurasiyanızla dəqiq uyğunluğunu yoxlayın. authorization_endpoint, token_endpoint və jwks_uri ünvanlarını yoxlanmış metadatadan götürün və razılaşdırılmış mühitlə tutuşdurun; istifadəçinin daxil etdiyi ünvanları yerləşdirməyin.

Server sorğuları sertifikatın və server adının yoxlanması ilə HTTPS üzərindən göndərilir. Lokal mühitin sertifikatı ayrıca konfiqurasiya edilir; qoşulmaq üçün TLS yoxlamasını söndürmək olmaz.

OpenID Connect Discovery 1.0: provayder konfiqurasiyasının yoxlanması

Mövcud reallaşdırmanın vacib xüsusiyyəti: Discovery OIDC modulu tərəfindən formalaşdırılır və server marşrutlarında dərc olunandan daha çox imkan elan edə bilər. Metadatada UserInfo, logout və ya başqa sahənin olması bu imkanın upID-də qoşulduğu demək deyil.

Girişə başlayın

Hər cəhd üçün bir-birindən müstəqil, kriptoqrafik təsadüfi state, nonce və code_verifier yaradın. Cəhdi brauzerə, issuer-ə, müştəriyə, callback-ə, dilə və məhdud müddətə bağlayın. İlkin dəyərləri serverdə saxlayın; sonra brauzeri authorization_endpoint-ə yönləndirin.

PKCE confidential-müştəri üçün də məcburidir. code_challenge dəyərini padding olmadan BASE64URL(SHA256(code_verifier)) kimi hesablayın. Məsələn, verifier-i 32 təsadüfi baytdan base64url formatında yarada bilərsiniz; sabit dəyərdən istifadə etməyin və cəhdi təkrar işlətməyin.

RFC 7636: PKCE və S256 çevrilməsi

GET AUTHORIZATION_ENDPOINT_FROM_DISCOVERY?
  response_type=code&
  client_id=YOUR_CLIENT_ID&
  redirect_uri=URL_ENCODED_REGISTERED_CALLBACK&
  scope=openid%20profile&
  state=ONE_TIME_RANDOM_STATE&
  nonce=ONE_TIME_RANDOM_NONCE&
  code_challenge=BASE64URL_SHA256_VERIFIER&
  code_challenge_method=S256&
  ui_locales=az

Bu, şərti dəyərlərlə verilmiş sxemdir; hazır giriş məlumatları və ya real iş mühitinə sorğu deyil. Həqiqi ünvanları və parametrləri OIDC kitabxananız formalaşdırır. HTTP nümunələrində sətir keçidləri oxunaqlılıq üçün əlavə edilib.

İctimai authorization sorğusunda yalnız sadalanmış parametrlərə icazə verilir; təkrarlar və massivlər qəbul edilmir, query 4096 baytla məhdudlaşır. prompt, max_age, claims və request objects bu profilə daxil deyil. OIDC kitabxanası response_mode, prompt və ya təsvir olunmayan başqa parametrləri avtomatik əlavə etməməlidir: icazəli parametrlər siyahısı onları rədd edir. upID adi brauzer yönləndirilməsi ilə açılır; iframe və frontend-də code mübadiləsi bu profilə daxil deyil.

Callback-i emal edin

Token endpoint-ə müraciətdən əvvəl state-i bu brauzerin vaxtı bitməmiş cəhdi ilə tutuşdurun. Cəhdi birdəfəlik və atomar qaydada istifadə edilmiş sayın. Başqasına aid, olmayan və ya təkrar state code mübadiləsinə və sessiyanın yaradılmasına səbəb olmamalıdır.

error cavabını yalnız uyğunlaşdırılmış cəhdin kontekstində emal edin. Rədd və ya ləğv giriş yaratmır. Callback query-dən access_token, id_token, refresh_token və ya code_verifier qəbul etməyin; bu profil code və state, yaxud provayder xətası gözləyir.

code-u server tərəfdə token_endpoint-ə POST göndərərək mübadilə edin. İlkin code_verifier-i və eyni redirect_uri-ni ötürün. Autentifikasiya üçün kitabxana vasitəsilə client_secret_basic istifadə edin; mövcud profil sorğunun gövdəsində client_secret və client_assertion qəbul etmir.

POST TOKEN_ENDPOINT_FROM_DISCOVERY
Authorization: Basic ENCODED_CLIENT_CREDENTIALS
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&
code=CODE_FROM_CALLBACK&
redirect_uri=URL_ENCODED_REGISTERED_CALLBACK&
code_verifier=ORIGINAL_VERIFIER

Bu, şərti dəyərlərlə verilmiş sxemdir; hazır giriş məlumatları və ya real iş mühitinə sorğu deyil. Həqiqi ünvanları və parametrləri OIDC kitabxananız formalaşdırır. HTTP nümunələrində sətir keçidləri oxunaqlılıq üçün əlavə edilib.

Yalnız uğurlu HTTP cavabına və ya access_token-in mövcudluğuna əsasən lokal giriş yaratmayın: əvvəlcə ID Token-i yoxlayın. Emaldan sonra təmiz daxili URL-ə yönləndirərək görünən ünvandan code və state-i çıxarın. Bu URL ixtiyari return_to-dan deyil, serverdəki icazəli keçidlər siyahısından seçilir.

ID Token-i yoxlayın

OIDC kitabxananızın tam verifier-indən istifadə edin. Mövcud müştəri profili RS256 və yoxlanmış jwks_uri-dən alınmış açarlarla təsdiqlənən imza gözləyir. JWT payload-unu sadəcə oxumaq və ya sub-un mövcudluğu şəxsiyyəti təsdiqləmir.

• İmzanı və icazə verilmiş alqoritmi yoxlayın. Təkcə yoxlanmamış tokendəki alg dəyərinə və ya açar ünvanına etibar etməyin.
• iss konfiqurasiya edilmiş issuer ilə dəqiq uyğun gəlməlidir; aud sizin client_id-ni ehtiva etməlidir. Bir neçə aud olduqda müştərinizin azp-si tələb olunur; azp varsa, o da yoxlanılır.
• exp və iat dəyərlərini kitabxananın siyasətinə və razılaşdırılmış saat fərqi toleransına əsasən yoxlayın. Məcburi claim yoxdursa, vaxtı bitibsə və ya yanlışdırsa, sorğu rədd edilməlidir.
• nonce mütləq olmalı və serverdəki ilkin cəhdlə uyğun gəlməlidir; sub boş olmayan sətir olmalıdır. issuer + sub cütü lokal istifadəçi ilə əlaqənin açarıdır.

OpenID Connect Core 1.0: Authorization Code və ID Token yoxlaması

Hesabları telefon, email və ya görünən ada əsasən avtomatik əlaqələndirməyin. Yalnız profile scope-una əsasən istifadəçiyə profil məlumatları vəd etməyin. ID Token məhsulunuzun API-si üçün universal access token deyil.

Mövcud pilot həmçinin imzalanmış upid_correlation claim-indən istifadə edir. Bu, girişlə giriş icazəsini əlaqələndirən özəl upID genişlənməsidir; standart OIDC claim-i və ya müstəqil bearer credential deyil. upHome siyasətini tətbiq edərkən onu nəzərə almamaq və ya istənilən kənar müştəri üçün hazır kontrakt saymaq olmaz.

Sessiya, aktuallıq və çıxış

Şəxsiyyəti və razılaşdırılmış giriş icazəsi şərtlərini tam yoxladıqdan sonra yeni identifikatorla öz server sessiyanızı yaradın. Cookie, CSRF, müddətlər, rollar və resurslarınıza giriş tətbiqin məsuliyyətində qalır. Lazımsız tokenləri brauzerdə və ya localStorage-da saxlamayın.

Lokal upHome-da giriş icazəsinin aktuallığı ayrıca upID server API-si ilə yoxlanılır: hesabın, cihazın və konkret giriş kontekstinin vəziyyəti. Bu mexanizm standart OAuth introspection deyil və hələ istənilən müştəri üçün açıq deyil. JWT-nin qüvvədə olma müddəti özlüyündə girişə hələ icazə verildiyini sübut etmir.

/api/v1/rp-sessions/status və /close yolları giriş icazəsi kontekstini yoxlayır və bağlayır; /confirm və /end isə məhsul sessiyası barədə məlumat verir. Bu özəl API-lər ayrıca icazə verilmiş müştəri tələb edir. confirmed siqnalı giriş icazəsini əvəz etmir; unconfirmed çıxışı sübut etmir. Kənar müştərinin kontraktı qoşulmadan əvvəl razılaşdırılmalıdır.

Lokal upHome müsbət giriş icazəsini server sorğusunun başlanmasından ən çox 30 saniyə keşdə saxlayır. Bundan sonra upID əlçatan olmadıqda qorunan əməliyyatlara giriş bağlanır, lokal sessiya isə əvvəlki müddətləri daxilində saxlanılır. Bu, mövcud məhsulun siyasətidir; bütün açıq səhifələrin dərhal bağlanacağına vəd deyil.

Tətbiqinizdən çıxış onun lokal sessiyasını qorunan əməliyyatla, məsələn, CSRF-li POST ilə bitirir. Bu, bütün məhsullardan çıxış, cihazın icazəsinin ləğvi və ya provayder sessiyasının bitməsi demək deyil. RP-initiated və back-channel logout upID-nin mövcud profilinə daxil deyil.

Xətalar və girişin yenidən başlanması

Şəxsiyyət və giriş icazəsi təsdiqlənmədən istifadəçini «daxil olub» vəziyyətinə keçirməyin. Aydın mesaj və yeni cəhdə başlamaq imkanı göstərin. Diaqnostika üçün xəta kateqoriyası və öz məxfi olmayan sorğu identifikatorunuz kifayətdir.

client_secret, code, verifier, tokenlər, Cookie və tam callback URL-i access logs-a, analitikaya, xəta hesabatlarına və ya Git-ə yazmayın. Provayderin xam cavabları və texniki istisnalar istifadəçiyə göstərilmir.

Hələ əlçatan olmayan imkanlar

• Kənar müştərilərin müstəqil qoşulması, Dynamic Client Registration, ümumi SDK və SPA və ya native public client üçün hazır profil.
• Refresh grant, offline_access, implicit, password və client_credentials aktiv deyil. Mövcud profil yalnız Authorization Code istifadə edir və tokenlərin yenilənməsi ssenarisini təqdim etmir.
• UserInfo və end-session: modul onları Discovery-də elan edə bilər, lakin mövcud upID marşrutları onları dərc etmir. Onlardan girişin və ya çıxışın məcburi addımı kimi istifadə etməyin.
• Silent SSO, prompt=none, max_age, request objects və ixtiyari claims. Mövcud giriş əlaqələndirilmiş cihazda yeni açıq təsdiq tələb edir.
• Qlobal logout və universal OAuth introspection/revocation API-ləri dərc olunmuş profilə daxil deyil. Production mühitinin əlçatanlığı, istismar şərtləri və dəstək ayrıca razılaşdırılır.

İnteqrasiyanı istifadəyə verməzdən əvvəl

• Operator mühitinizi, müştərinin qoşulma icazəsini, callback-i və sessiya siyasətini təsdiqləyib. Nümunələr həqiqi konfiqurasiya ilə əvəz edilib, sirlər serverdə qalır.
• Cihaz təsdiqi ilə giriş, öz sessiyanızın yaradılması, lokal çıxış və təkrar giriş əl ilə sınaqdan keçirilib.
• İstifadəçinin rəddi, səhv və ya təkrar state, təkrar code, səhv verifier, callback və imza yeni giriş vermədən rədd ilə nəticələnir. Bu yoxlamalar sizin razılaşdırılmış mühitinizdə aparılmalıdır; burada onların keçildiyi elan edilmir.
• Discovery/JWKS/token endpoint əlçatan olmadıqda və müddətlər bitdikdə tətbiq yoxlanmamış şəxsiyyəti qəbul etmir; çıxışdan sonra gecikmiş callback köhnə girişi bərpa etmir.
• Mesajlar, mövcud sessiyanın saxlanması, callback-dən sonrakı təmiz ünvan, loglarda sirlərin olmaması və lazımi dillərdə girişin əlçatanlığı yoxlanılıb.

Standartlar

Protokol OIDC kitabxanası vasitəsilə reallaşdırılır. Mübadilə və yoxlamanın normativ qaydaları ilkin spesifikasiyalarda təsvir olunub; konkret upID-nin imkanları yuxarıdakı profillə məhdudlaşır.

• OpenID Connect Core 1.0: Authorization Code və ID Token yoxlaması
• OpenID Connect Discovery 1.0: provayder konfiqurasiyasının yoxlanması
• RFC 7636: PKCE və S256 çevrilməsi
• RFC 9700: OAuth 2.0 müdafiəsi üzrə aktual tövsiyələr