OAuth 2.x և OpenID Connect

01Գաղափարը՝ valet բանալի, ոչ թե ձեր տան բանալին

Որոշ մեքենաներ գալիս են valet բանալիով․ այն միացնում է շարժիչը, բայց չի կարող բացել բեռնախցիկը։ OAuth-ը հավելվածներին տալիս է valet բանալիներ։ Ներգրավված են չորս դեր։ Resource owner-ը օգտատերն է։ Client-ը հավելվածն է, որն ուզում է հասանելիություն։ Authorization server-ը authenticate է անում օգտատիրոջը և թողարկում token-ներ։ Resource server-ը API-ն է, որն ընդունում է token-ները։ Օգտատերը մուտք է գործում միայն authorization server-ում և հաստատում կոնկրետ scope-ներ՝ «կարդալ ձեր օրացույցը», և client-ը ստանում է access token՝ վավեր այդ scope-ների և սահմանափակ ժամանակի համար։ Client-ը երբեք չի տեսնում գաղտնաբառը։ Կարևոր տարբերակում՝ OAuth 2.0-ը authorization-ի մասին է (ինչ կարող է անել հավելվածը), ոչ թե authentication-ի (ով է օգտատերը)։ Պարզ OAuth access token-ը որպես ինքնության ապացույց օգտագործելը դասական սխալ է, և հենց այդ բացն է լրացնում OpenID Connect-ը։

• Resource owner՝ օգտատերը
• Client՝ վեբ, մոբայլ կամ սերվերային հավելված
• Authorization server՝ մուտք է գործացնում օգտատիրոջը, թողարկում token-ներ
• Resource server՝ ձեր API-ն, ստուգում է token-ները

02Authorization code flow PKCE-ով՝ քայլ առ քայլ

Սա առաջարկվող flow-ն է վեբ հավելվածների, SPA-ների և մոբայլ հավելվածների համար։ Client-ը ստեղծում է պատահական code_verifier և authorization հարցման մեջ ուղարկում դրա SHA-256 hash-ը (code_challenge)։ Օգտատերը մուտք է գործում և համաձայնություն տալիս, և server-ը redirect է անում հետ՝ միանգամյա authorization code-ով։ Client-ը back channel-ով code-ը գումարած սկզբնական verifier-ը փոխանակում է token-ների հետ։ PKCE-ն (Proof Key for Code Exchange, RFC 7636) նշանակում է, որ գողացված code-ն անօգուտ է առանց verifier-ի, որը երբեք չի լքել հավելվածը։ State պարամետրը պաշտպանում է redirect-ի ժամանակ CSRF-ից, իսկ OIDC-ի դեպքում nonce-ը ID token-ը կապում է այս մուտքի հետ։ Redirect URI-ները պետք է գրանցված լինեն և ճշգրիտ համընկնեն։ OAuth 2.1-ը, որը 2026-ի վերջին դեռ IETF draft է, բայց արդեն արտացոլված է RFC 9700-ում (OAuth 2.0 Security Best Current Practice), պահանջում է PKCE բոլոր client-ների համար և հանում implicit և password grant-երը։

1# 1) Browser is redirected to the authorisation server
2GET https://auth.example.com/authorize?response_type=code
3  &client_id=web-app
4  &redirect_uri=https://app.example.com/callback
5  &scope=openid%20profile%20email%20orders:read
6  &state=af0ifjsldkj&nonce=n-0S6_WzA2Mj
7  &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
8  &code_challenge_method=S256
9 
10# 2) Back channel: exchange the code for tokens
11POST https://auth.example.com/token
12Content-Type: application/x-www-form-urlencoded
13 
14grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA
15&redirect_uri=https://app.example.com/callback
16&client_id=web-app&code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk

03Token-ներ՝ access, refresh և ID token-ներ

Access token-ը այն է, ինչ client-ն ուղարկում է API-ին, սովորաբար որպես «Authorization: Bearer ...»։ Այն պետք է լինի կարճաժամկետ՝ րոպեներ, ոչ թե ամիսներ, որովհետև bearer token ունեցող ցանկացած մեկը կարող է օգտագործել այն։ Այն կարող է լինել opaque (API-ն այն ստուգում է authorization server-ի հետ introspection-ով) կամ JWT (API-ն ստորագրությունը ստուգում է լոկալ)։ Refresh token-ը թույլ է տալիս client-ին նոր access token-ներ ստանալ՝ առանց օգտատիրոջ նորից մուտք գործելու․ այն երկարաժամկետ է և հզոր, ուստի պահեք զգույշ, rotate արեք յուրաքանչյուր օգտագործման ժամանակ և revoke արեք logout-ի ժամանակ։ ID token-ը՝ OpenID Connect-ից, ստորագրված JWT է, որը client-ին ասում է, թե ով է մուտք գործել՝ issuer (iss), subject id (sub), audience (aud), expiry (exp), nonce և ըստ ցանկության email կամ անուն։ ID token-ը client-ի կարդալու համար է․ այն նախատեսված չէ ձեր API-ներին որպես access token ուղարկելու համար։

• Access token՝ API-ի համար, կարճաժամկետ, scope-ներով
• Refresh token՝ client-ի համար՝ հասանելիությունը թարմացնելու, rotate և revoke արեք
• ID token՝ client-ի համար, ապացուցում է, թե ով է մուտք գործել

04OpenID Connect՝ «Sign in with Google / Apple»

OpenID Connect-ը (OIDC) բարակ ինքնության շերտ է OAuth 2.0-ի վրա։ Ավելացնում եք «openid» scope-ը, և authorization server-ը access token-ի կողքին վերադարձնում է ID token։ Provider-ները /.well-known/openid-configuration հասցեում հրապարակում են discovery փաստաթուղթ, որտեղ թվարկված են իրենց endpoint-ները և JWKS URL-ը՝ ստորագրման բանալիներով։ Օգտատիրոջն անվտանգ մուտք գործացնելու համար ձեր բեքենդը պետք է ստուգի ID token-ը՝ ստորագրությունը provider-ի ընթացիկ բանալիով, iss-ը հավասար է provider-ին, aud-ը հավասար է ձեր client id-ին, exp-ը չի անցել, և nonce-ը համընկնում է ձեր ուղարկածին։ Հետո հաշիվը կապեք provider-ի կայուն sub-ով, ոչ թե email-ով, որովհետև email-ները փոխվում են և միշտ չէ, որ ստուգված են։ Մոբայլում native SDK-ները (Google Sign-In, Sign in with Apple) վերադարձնում են ID token կամ authorization code, որը հավելվածն ուղարկում է ձեր բեքենդին նույն ստուգման համար՝ նախքան ձեր սեփական session-ը կամ API token-ները թողարկելը։

1use Laravel\Socialite\Facades\Socialite;
2 
3// Redirect the user to Google
4Route::get('/auth/google', fn () => Socialite::driver('google')->redirect());
5 
6// Callback: Socialite exchanges the code and fetches the profile
7Route::get('/auth/google/callback', function () {
8    $g = Socialite::driver('google')->user();
9 
10    $user = User::firstOrCreate(
11        ['google_id' => $g->getId()],          // stable provider "sub"
12        ['name' => $g->getName(), 'email' => $g->getEmail()],
13    );
14    Auth::login($user);
15    return redirect('/account');
16});

05Այլ grant-եր և API key-եր

Ոչ բոլոր client-ներն ունեն օգտատեր բրաուզերում։ Client credentials՝ բեքենդ ծառայությունը authenticate է անում ինքն իրեն (client id և secret, կամ ավելի լավ՝ ստորագրված assertion կամ mutual TLS)՝ մեկ այլ ծառայություն կանչելու համար՝ machine-to-machine։ Device authorization (RFC 8628)՝ smart TV-ները և CLI-ները ցույց են տալիս կոդ, որը օգտատերը մուտքագրում է իր հեռախոսում։ Token exchange (RFC 8693)՝ ծառայությունը մի token-ը փոխանակում է մեկ այլի հետ՝ ավելի նեղ scope-ով կամ այլ audience-ով։ Refresh token grant՝ թարմացնել հասանելիությունը։ Հնացած՝ implicit grant-ը (token-ները URL fragment-ում) և resource owner password grant-ը (հավելվածը հավաքում է օգտատիրոջ գաղտնաբառը), երկուսն էլ հանված են OAuth 2.1-ում։ Պարզ API key-երը դեռ տարածված են server-to-server ինտեգրացիաների համար․ եթե օգտագործում եք դրանք, դարձրեք scope-ներով, միջավայրով prefix-ված (live/test), պահոցում hash արված, rate-limit արված և rotate արվող՝ առանց downtime-ի։

06Laravel Passport-ը գործնականում

Laravel Passport-ը լիարժեք OAuth2 server է Laravel API-ների համար՝ կառուցված League OAuth2 server-ի վրա։ Ընթացիկ տարբերակներն աջակցում են authorization code grant-ը (PKCE-ով public client-ների համար), client credentials, device authorization, refresh token-ներ և personal access token-ներ․ password և implicit grant-երն անջատված են, եթե բացահայտ չեք միացնում։ Scope-ները սահմանում եք Passport::tokensCan-ով, route-երը պաշտպանում auth:api guard-ով գումարած scope middleware, իսկ token-ների կյանքի տևողությունը դնում service provider-ում․ default-ով access token-ները ապրում են մեկ տարի, ինչը հավելվածների մեծ մասի համար չափազանց երկար է, ուստի կրճատեք։ Նույն դոմենի վրա first-party SPA-ների համար Laravel Sanctum-ի cookie-ի վրա հիմնված session-ները հաճախ ավելի պարզ են, քան OAuth-ը․ Passport-ը փայլում է, երբ ձեզ պետք են իրական OAuth client-ներ, երրորդ կողմի հասանելիություն կամ token-ի վրա հիմնված մոբայլ հավելվածներ։

1// AppServiceProvider::boot()
2use Carbon\CarbonInterval;
3use Laravel\Passport\Passport;
4 
5Passport::tokensCan([
6    'orders:read'   => 'View your orders',
7    'orders:create' => 'Place orders',
8]);
9Passport::tokensExpireIn(CarbonInterval::minutes(30));
10Passport::refreshTokensExpireIn(CarbonInterval::days(30));
11 
12// routes/api.php
13use Laravel\Passport\Http\Middleware\CheckToken;
14 
15Route::get('/orders', [OrderController::class, 'index'])
16    ->middleware(['auth:api', CheckToken::using('orders:read')]);

07JWT-ների ճիշտ ստուգում (և դասական հարձակումները)

JWT-ն header.payload.signature է՝ base64url-encoded։ Ստուգումը պետք է լինի խիստ։ Սպասվող ալգորիթմը pin արեք ձեր կոդում (օրինակ՝ RS256 կամ ES256) և մերժեք ամեն այլ բան․ պատմական խոցելիությունները գալիս էին գրադարաններից, որոնք վստահում էին header-ի alg-ին՝ թույլ տալով «none» կամ HS256-ի և public key-ի շփոթություն։ Ստորագրման բանալիները ստացեք issuer-ի JWKS endpoint-ից, քեշավորեք, ընտրեք ըստ kid-ի և թարմացրեք անհայտ kid-ի դեպքում՝ key rotation-ն աջակցելու համար։ Ստուգեք iss-ը և aud-ը ճշգրիտ, exp-ը և nbf-ը՝ ժամացույցի փոքր շեղման թույլտվությամբ, իսկ ID token-ների համար՝ nonce-ը։ Զգայուն տվյալներ մի դրեք payload-ում․ այն ստորագրված է, ոչ թե գաղտնագրված։ RFC 8725-ը (JWT Best Current Practices) հղումային փաստաթուղթն է։ Նախընտրեք ասիմետրիկ ստորագրում, որպեսզի resource server-ները պահեն միայն public key-եր, և միայն authorization server-ը կարողանա token-ներ ստեղծել։

1import { createRemoteJWKSet, jwtVerify } from "jose";
2 
3const JWKS = createRemoteJWKSet(new URL("https://auth.example.com/.well-known/jwks.json"));
4 
5export async function verifyAccessToken(token: string) {
6  const { payload } = await jwtVerify(token, JWKS, {
7    issuer: "https://auth.example.com",
8    audience: "https://api.example.com",
9    algorithms: ["RS256"],      // never trust the header's alg
10    clockTolerance: 30,         // seconds
11  });
12  if (await denylist.has(payload.jti as string)) throw new Error("revoked");
13  return payload; // sub, scope, exp, ...
14}

08Refresh token rotation և reuse detection

Refresh token-ները թագի գոհարներն են՝ երկարաժամկետ և ունակ access token-ներ ստեղծելու։ Rotation-ը նշանակում է, որ յուրաքանչյուր refresh վերադարձնում է նոր refresh token և անվավեր դարձնում հինը։ Reuse detection-ը ավելացնում է անվտանգության հիմնական հատկությունը․ եթե հին, արդեն օգտագործված refresh token-ը նորից է ներկայացվում, կամ օրինական client-ը, կամ հարձակվողն ունի գողացված պատճեն, ուստի server-ը revoke է անում ամբողջ token ընտանիքը և ստիպում նորից մուտք գործել։ Իրականացրեք սա՝ յուրաքանչյուր refresh token-ի համար պահելով family id և used դրոշ։ Ավելացրեք բացարձակ կյանքի տևողություն (օրինակ՝ 30–90 օր) և idle timeout, որպեսզի լքված session-ները մահանան։ Մշակեք race-երը մոբայլ հավելվածներում, որտեղ երկու զուգահեռ հարցում միաժամանակ փորձում են refresh անել՝ client-ում refresh-ները սերիալիզացրեք կամ նախորդ token-ի համար թույլ տվեք շատ կարճ grace window։ Sender-constrained token-ներն ավելի հեռու են գնում՝ token-ները կապելով client-ի բանալու հետ, որպեսզի գողացված token-ը չկարողանա replay արվել այլ տեղում։

09Sender-constrained token-ներ՝ DPoP և mTLS

Bearer token-ները աշխատում են կանխիկի պես՝ ով պահում է, նա էլ կարող է ծախսել։ Sender-constrained token-ները աշխատում են PIN-ով քարտի պես։ DPoP-ի (RFC 9449) դեպքում client-ը գեներացնում է key pair, և յուրաքանչյուր հարցման հետ ուղարկում կարճ ստորագրված proof JWT, որը պարունակում է HTTP method-ը, URL-ը, timestamp և access token-ի hash։ Authorization server-ը token-ը կապում է client-ի public key-ի հետ (cnf claim), իսկ API-ն ստուգում է, որ յուրաքանչյուր հարցում ստորագրված է նույն բանալիով։ Log-երի կամ proxy-ի միջոցով արտահոսած token-ը դառնում է անօգուտ։ Mutual TLS-ը (RFC 8705) նույնին հասնում է՝ token-ները կապելով client certificate-ի հետ, ինչը տարածված է բանկային և open-finance պրոֆիլներում, ինչպիսին է FAPI 2.0-ը։ Pushed Authorization Requests-ը (PAR, RFC 9126) լրացնում է սա՝ authorization պարամետրերը ուղարկելով back channel-ով՝ բրաուզերի URL-ի փոխարեն, ինչը կանխում է կեղծումը։

1POST /orders HTTP/1.1
2Host: api.example.com
3Authorization: DPoP eyJhbGciOiJFUzI1NiIsImtpZCI6IjEifQ...
4DPoP: eyJ0eXAiOiJkcG9wK2p3dCIsImFsZyI6IkVTMjU2IiwiandrIjp7Li4ufX0...
5 
6# DPoP proof payload (signed with the client's private key):
7# { "htm": "POST", "htu": "https://api.example.com/orders",
8#   "iat": 1793000000, "jti": "e1j3V_bKic8-LAEB", "ath": "<sha256 of access token>" }

10Multi-tenant և B2B ինքնության դիզայն

SaaS-ում ինքնությունն ավելի բարդ է դառնում․ օգտատերերը պատկանում են կազմակերպությունների, կարող են պատկանել մի քանիսին, իսկ enterprise հաճախորդներն ուզում են իրենց սեփական SSO-ն։ Tenant-ը token-ի մեջ դրեք միտումնավոր՝ tenant կամ org claim, որն ընտրվում է մուտքի ժամանակ կամ կազմակերպության switcher-ով, և յուրաքանչյուր հարցման ժամանակ ստուգեք, որ resource-ը պատկանում է այդ tenant-ին․ երբեք tenant id-ները մի վերցրեք միայն հարցման body-ից։ Role-երը և իրավունքները պահեք ձեր հավելվածում՝ անհրաժեշտության դեպքում mapping անելով IdP խմբերից, այլ ոչ թե վստահելով արտաքին IdP-ների կամայական claim-երին։ Enterprise SSO-ի համար աջակցեք յուրաքանչյուր tenant-ի OIDC կամ SAML կապերը, գումարած SCIM օգտատերերի provisioning-ի համար, եթե հաճախորդները խնդրում են։ Պլանավորեք impersonation-ը․ support-ի անձնակազմը պետք է ստանա առանձին, ժամանակով սահմանափակված token՝ act (actor) claim-ով, պարտադիր պատճառով և ամբողջական audit logging-ով, երբեք հաճախորդի սեփական credentials-ը։