JSON Web Token

JSON Web Token (JWT, hääldatakse /dʒɒt/, või "džot"^[1]) on väljapakutud internetistandard andmete loomiseks koos digitaalallkirja ja/või krüpteerimisega, mis sisaldab JSON-i, mis omakorda seab ette teatud hulga väiteid. Tõendid allkirjastatakse avaliku ja salajase võtmega.

Näiteks võib server luua tõendi, millel on väide "sisse logitud administraatorina" ning anda selle kliendile. Klient saab seejärel tõendit kasutada tõestamaks, et on sisse logitud administraatorina. Tõendeid saab allkirjastada ühe osapoole salajase võtmega (tavaliselt serveri omaga) nii, et sama osapool saab hiljem kontrollida tõendi õigsust. Kui teisel osapoolel on sobival ja usaldusväärsel viisil olemas vastav avalik võti, on ka teine osapool võimeline kontrollima tõendi õigsust. Tõendid on loodud kompaktselt^[2], URL-i jaoks turvaliselt^[3] ning kasutamiseks eelkõige veebibrauseri ühekordse sisselogimise (single sign-on, SSO) kontekstis.^[4][5]

JWT tugineb teistele JSON-il põhinevatele standarditele: JSON Web Signature ja JSON Web Encryption.^[1][6][7]

JWT tõendid on Eestis kasutusel riigi autentimisteenuses (TARA), millega on võimalik e-teenusestes autentida kasutades ID-kaarti, mobiil-ID-d või smart-ID-d.^[8][9]

Struktuur

Päis	{ "alg": "HS256", "typ": "JWT" }	Tuvastab algoritmi, mille alusel allkiri luuakse HS256 tähendab, et tõend on allkirjastatud algoritmiga HMAC-SHA256. Tavalised algoritmid mida kasutatakse on HMAC pluss SHA-256 (HS256) ja RSA allkiri pluss SHA-256 (RS256). JWA (JSON Web Algorithms) RFC 7518 tutvustab veel teisigi kasutatavaid algoritme.[10]
Sisu	{ "loggedInAs": "admin", "iat": 1422779638 }	Sisaldab väiteid. JWT spetsifikatsioonis on kirjeldatud seitset erinevat nime väidetele, mis on standardväljad ja leiduvad tõendites tihti. Samuti leidub lisavälju, mis tulenevad tõendi eesmärgist. Selles näites on standardväli Issued At Time (väljastatud ajal, iat) ja lisaväli (logitud sisse kui, loggedInAs).
Allkiri	HMAC_SHA256( secret, base64urlEncoding(header) + '.' + base64urlEncoding(payload) )	Valideerib tõendi turvaliselt. Allkiri luuakse šifreerides nii päis kui sisu kasutades Base64url kodeeringut (RFC 4648) ja ühendades need kasutades eraldajana punkti. Tulemus läbib seejärel päises kirjeldatud algoritmi, näites HMAC-SHA256.

Kõik kolm osa kodeeritakse seejärel uuesti kasutades Base64url kodeeringut, ning ühendatakse kokku kasutades eraldajana punkte JWT tõendi loomiseks:

const token = base64urlEncoding(header) + '.' + base64urlEncoding(payload) + '.' + base64urlEncoding(signature)

Saadud JWT tõend ja "secretkey" ehk salajane võti loovad tõendi:

pre

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJsb2dnZWRJbkFzIjoiYWRtaW4iLCJpYXQiOjE0MjI3Nzk2Mzh9.gzSraSYS8EXBxLN_oWnFSRgCzcmJmMjLiuyu5CSpyHI

Saadud tõendi saab hõlpsasti HTML-i ja HTTP-sse edasi anda.^[3]

Kasutamine

Kui kasutaja logib edukalt sisse luuakse ja tagastatakse JWT tõend, mis seejärel salvestatakse lokaalselt (tavaliselt lokaalsesse- või sessioonimällu, kuid kasutada saab ka küpsiseid). Võrdluseks luuakse traditsiooniselt sessioon serveris ning kasutajale tagastatakse vaid küpsis, millega kasutajat hiljem ära tunda. Kui tegemist on ilma kasutajata protsessiga võib klient autentida ka otse luues ja ise allkirjastades JWT tõend koos salajase võtmega ja anda see edasi OAuth-i toetavale teenusele:

POST /oauth2/token?
Content-type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion=eyJhb...

Kui klient annab edasi kehtiva JWT tõendi, loob server uue ligipääsutõendi access_token, millega saab sooritada kutseid teenusele ja neid kliendile tagasi saata.

{
 "access_token": "eyJhb...",
 "token_type": "Bearer",
 "expires_in": 3600
}

Kui klient soovib juurdepääsu kaitstud marsruudile või ressursile, peaks ta saatma JWT tõendi Authorization päisesse, kasutades Bearer skeemi.

Authorization: Bearer eyJhbGci ... < jne > ... yu5CSpyHI

See on olekuta autentimismehhanism, kuna kasutaja olekut ei salvestata kunagi serveri mällu. Serveris kaitstud marsruudid otsivad päises kehtivat JWT tõendit ning kui see on olemas, antakse kliendile ligipääs kaitstud ressurssidele. Kuna JWT tõendid on iseseisvad, on kõik vajalikud andmed olemas ning andmebaasi ei pea tegema mitmeid päringuid.

Standardväljad

Kood	Nimi	Kirjeldus
Tavalised väited
iss	Väljaandja	Tuvastab JWT väljastanud printsipaali.
sub	Teema	Tuvastab JWT teema.
aud	Sihtrühm	Määrab adressaadid, kellele JWT on mõeldud. Iga JWT töötlemiseks mõeldud printsipaal peab tuvastama end sihtrühma väites oleva väärtusega. JWT tuleb vastasel juhul tagasi lükata.
exp	Aegumisaeg	Määrab aegumisaja, mille möödumisel ei tohi JWT-d töötlemiseks vastu võtta. Väärtus peab olema NumericDate, täis- või komakohaga arv, mis väljendab sekundeid peale 1. jaanuarit 1970 00:00:00 UTC.
nbf	Mitte varem kui	Määrab aja, millal hakatakse JWT-d töötlemiseks vastu võtma. Väärtus peab olema NumericDate.
iat	Väljaandmise aeg	Tuvastab aja, millal JWT väljastati. Väärtus peab olema NumericDate.
jti	JWT ID	Tõstutundlik unikaalne identifikaator tõendi tuvastamiseks, hoolimata väljastajast.
Tavaliselt kasutatavad päiseväljad
typ	Tõendi tüüp	Kui see on defineeritud, peab selle väärtus vastama registreeritud IANA meediumitüübile .
cty	Sisu tüüp	Kui kasutatakse pesastatud allkirjastamist või krüpteerimist, on soovitatav määrata selle väärtuseks JWT ; muul juhul tuleks seda välja mitte kasutada.[1]
alg	Algoritm	Väljaandja võib enda valikul seada algoritmi, millega tõendil olevat allkirja ära tunda. Mõned algoritmid on ebaturvalised ning neid tuleks vältida.[11]
kid	Võtme ID	Vihje, mis näitab, millist võtit klient tõendi allkirja loomiseks kasutas. Server sobitab selle väärtuse failis oleva võtmega, et kontrollida allkirja kehtivust ja tõendi õigsust.
x5c	x.509 sertifikaadiahel	Sertifikaat RFC4945-vormingus, mis vastab salajasele võtmele, mida kasutatakse tõendi allkirja genereerimiseks. Server kasutab seda teavet allkirja kehtivuse ja tõendi õigsuse kontrollimiseks.
x5u	x.509 sertifikaadiahela URL	Internetiaadress, kust server saab hankida sertifikaadiahela, mis vastab tõendi allkirja genereerimiseks kasutatud salajasele võtmele. Server hangib selle teabe ja kasutab seda allkirja õigsuse kontrollimiseks.
crit	Kriitiline	Päiste loend, millest server peab aru saama, et tõend kehtivaks tunnistada.
Kood	Nimi	Kirjeldus

Haavatavused

JWT tõendid võivad sisaldada sessiooni olekut, kuid kui projekti nõuded lubavad sessiooni kehtetuks tunnistamist enne JWT aegumist, ei saa teenused enam usaldada tõendi seatud väiteid tõendit kasutades. Sessiooni valideerimiseks peab seetõttu tõendi väiteid kontrollima andmebaasi abil. See tähendab aga, et tõend ei ole enam olekuta, mistõttu ei ole JWT kasutamisel enam eelist.^[12]

Turvakonsultant Tim McLean leidis mõnes JWT teegis haavatavused, mis kasutasid alg välja ebakorrektselt tõendite õigsuse kontrollimisel, tüüpiliselt tehes seda lubades alg=none tõendit. Kuigi nimetatud teekides on need haavatavused tänaseks prandatud, soovitab McLean alg väljast täielikult loobuda, et vältida tulevikus sarnaseid probleeme.^[11] Uusi alg=none haavatavusi leitakse aga siiamaani.^[13]