JSON Web Token (JWT) aláírásának ellenőrzése

Miért kell ellenőrizni a JWT aláírását?

Egy JSON Web Token (JWT) három, pontokkal elválasztott részből áll: header.payload.signature. Egy JWT dekódolása egyszerűen az első két rész elolvasását jelenti (amik Base64URL formátumúak). Bárki megteheti ezt, és bárki készíthet JWT-t tetszőleges payload-dal. Ami egy JWT-t megbízhatóvá tesz, az kizárólag az aláírás: ellenőrzés nélkül egy JWT elfogadása olyan, mintha bárkit beengedne a házába, aki azt állítja, hogy ő valaki, anélkül, hogy elkérné a személyi igazolványát.

Ez az eszköz ellenőrzi a JWT aláírását egy kulcs alapján. Nem csak dekódol: újraszámítja az aláírást a fejléc, a payload és az Ön kulcsa alapján, majd összehasonlítja azt a tokenben található aláírással. Ha a kettő egyezik, a token hiteles. Ellenkező esetben hamisították, módosították, vagy más kulccsal írták alá.

Az ellenőrzés minden olyan architektúra alapköve, amely JWT-ket használ autentikációra vagy autorizációra: érvényes aláírás nélkül a payload hazudhat. Egy támadó, aki a "role":"user" részt "role":"admin"-ra módosítja, minden nehézség nélkül megtehetné ezt, ha a szerver csak a token formátumát ellenőrizné, az aláírását nem.

Gyakori algoritmusok

A JWT specifikáció (RFC 7518, JSON Web Algorithms) több algoritmuscsaládot definiál. Íme a produkciós környezetben leggyakrabban használtak:

• HMAC (HS256, HS384, HS512): szimmetrikus aláírás HMAC-SHA alapokon. Ugyanaz a titkos kulcs szolgál az aláírásra és az ellenőrzésre. Egyszerű beállítani, nagy teljesítményű, de minden fél, amely képes ellenőrizni a tokent, képes kibocsátani is. Olyan szcenáriókhoz alkalmas, ahol a kibocsátó és az ellenőrző ugyanaz a csapat vagy szolgáltatás.
• RSA (RS256, RS384, RS512): aszimmetrikus aláírás. A privát kulcs ír alá, a publikus kulcs ellenőriz. Ideális, ha a kibocsátó és az ellenőrzők különálló egységek (OAuth2, OpenID Connect, identitás-föderáció). Ez a legtöbb publikus identitásszolgáltató által preferált algoritmus.
• ECDSA (ES256, ES384): aszimmetrikus aláírás elliptikus görbékkel. Ugyanaz a logika, mint az RSA-nál (privát kulcs az aláíráshoz, publikus az ellenőrzéshez), de kompaktabb kulcsokkal és aláírásokkal azonos biztonsági szint mellett. Egyre elterjedtebb a modern architektúrákban.

Hogyan kell megadni a kulcsot

Az elvárt kulcs formátuma a JWT fejlécében deklarált algoritmustól függ:

• HS256, HS384, HS512: a kulcs egy titkos karakterlánc (string). Ez a kibocsátóval közös titok, amelyet gyakran egy környezeti változóban tárolnak, mint például a JWT_SECRET. Nincs különösebb formázás, csak a nyers érték.
• RS256, RS384, RS512: a kulcs egy PEM formátumú RSA publikus kulcs, amely a -----BEGIN PUBLIC KEY----- sorral kezdődik és a -----END PUBLIC KEY----- sorral végződik. Tartsa meg a sortöréseket, különben az OpenSSL nem tudja feldolgozni.
• ES256, ES384: a kulcs egy PEM formátumú ECDSA publikus kulcs a megfelelő görbén (P-256 az ES256-hoz, P-384 az ES384-hez).

Példa elvárt RSA publikus kulcsra

-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAxe...
...vQIDAQAB
-----END PUBLIC KEY-----

Hogyan működik az ellenőrzés?

Szerverünk pontosan ugyanazt a műveletet végzi el, mint amit a kibocsátó tett:

1. Felosztja a JWT-t fejlécre, payloadra és aláírásra.
2. Összefűzi: base64url(header) + "." + base64url(payload).
3. HMAC esetén kiszámít egy HMAC-SHA-256/384/512 értéket az Ön titkos kulcsával, majd összehasonlítja a kapott aláírással a hash_equals függvénnyel (konstans idejű összehasonlítás az időzítésen alapuló támadások elkerülése érdekében).
4. RSA esetén meghívja az openssl_verify függvényt az Ön PEM formátumú publikus kulcsával.

Felhasználási esetek

• API autentikációs hibakeresés: 401-es hibát kap, ellenőrizze, hogy a token valóban az elvárt kulccsal van-e aláírva.
• Szolgáltatótól kapott token validálása: egy partner (Auth0, Keycloak, Cognito, Okta) RS256-tal aláírt JWT-ket küld Önnek; meg akar győződni róla, hogy valóban tőle származnak-e a publikus kulcsa segítségével.
• Biztonsági audit: ellenőrizni, hogy egy harmadik fél szolgáltatása megfelelően írja-e alá a tokenjeit robusztus algoritmussal, és nem HS256-ot használ-e gyenge titokkal.
• Manuális tesztek: ellenőrizni, hogy a kódja által generált JWT átmegy-e az ellenőrzésen a megadott publikus kulccsal.
• Kapott token gyors ellenőrzése: egy SSO vagy partner API integrációja során másodpercek alatt ellenőrizheti az aláírás/kulcs párost, mielőtt egyetlen sor kódot is írna.

Hogyan kell használni az eszközt

1. Illessze be a teljes JWT-t (a három, pontokkal elválasztott részt).
2. Adja meg a fejléc algoritmusának megfelelő kulcsot:
   • HS256, HS384 vagy HS512 esetén a kulcs a kibocsátóval megosztott titkos karakterlánc. Ez egy szabadon választott karakterlánc, gyakran olyan környezeti változóban tárolva, mint a JWT_SECRET.
   • RS256, RS384 vagy RS512 esetén a kulcs a PEM formátumú publikus kulcs, amely a -----BEGIN PUBLIC KEY----- sorral kezdődik és a -----END PUBLIC KEY----- sorral végződik.
3. Indítsa el az ellenőrzést. Az eszköz megjeleníti az állapotot (érvényes vagy érvénytelen) és a dekódolt payloadot.

Gyakori elkerülendő csapdák

• "none" algoritmus: a specifikáció engedélyezi az alg: none használatát, ami azt jelenti, hogy "nincs aláírás". Egy klasszikus hiba ilyen fejléccel tokent készíteni abban a reményben, hogy a szerver elfogadja. Eszközünk szisztematikusan elutasítja az alg: none algoritmust használó tokeneket.
• HMAC vs RSA felcserélése (algorithm confusion): egy támadó az RS256 algoritmust HS256-ra módosítja, és a payloadot az RSA publikus kulccsal írja alá, HMAC titokként használva azt. Ha a szerver nem ellenőrzi az algoritmust, elfogadja a tokent. Mindig rögzítse az elvárt algoritmust szerveroldalon.
• Hardkódolt HMAC titkok: egy Git tárolóba bekerült titok semmissé teszi a tokenekbe vetett összes bizalmat. Tárolja a titkokat környezeti változókban vagy alkalmazás-széfben.
• Publikus kulcs vs privát kulcs: egy RSA-val vagy ECDSA-val aláírt JWT ellenőrzéséhez a publikus kulcsot adjuk meg, soha nem a privátot. A privát kulcs csak az aláíráshoz kell, és soha nem hagyhatja el a kibocsátót.
• Lejárat figyelmen kívül hagyása: egy lejárt token érvényes aláírását soha nem szabad elfogadni. Ne felejtse el ellenőrizni az exp és nbf claim-eket.
• Nem ellenőrzött célközönség (audience): az "A" API-hoz szánt tokent nem szabadna elfogadnia a "B" API-nak. Ellenőrizze az aud claim-et.

Időbeli állítások (claims): exp és nbf

Az aláíráson túl egy érvényes JWT-nek tiszteletben kell tartania az időbeli korlátait is:

• exp (lejárat): a token ezen időpont után már nem érvényes.
• nbf (nem előbb): a token ezen időpont előtt még nem érvényes.

Eszközünk kifejezetten jelzi, ha egy token lejárt vagy még nem érvényes, még akkor is, ha az aláírása helyes. Ez fontos: egy lejárt token érvényes aláírását soha nem szabad elfogadni produkciós környezetben.

Különbség a JWT dekódolónkhoz képest

A JWT dekódolónk csak a fejléc és a payload részeit dekódolja, hogy olvashatóvá tegye őket. Semmilyen ellenőrzést nem végez az aláíráson, és nem kér kulcsot. Használja a token tartalmának gyors megtekintéséhez. Használja a JWT ellenőrzőt (ezt az oldalt), ha bizonyítania kell, hogy egy token hiteles. Tesztelési célú aláírt JWT készítéséhez használja a JWT építőnket.

Gyakran ismételt kérdések

Kérés példa

curl -X POST https://cdrn.fr/api/v1/tools/jwt-verifier/execute \
  -H "Content-Type: application/json" \
  -d '{"token":"...","key":"..."}'

Bemeneti séma

Végpontok

• GET https://cdrn.fr/api/v1/tools - listázza az összes elérhető eszközt
• GET https://cdrn.fr/api/v1/tools/jwt-verifier - lekéri ezen eszköz sémáját
• POST https://cdrn.fr/api/v1/tools/jwt-verifier/execute - végrehajtja ezen eszközt JSON payloaddal