View source for JSON Web Token

{{short description|JSON-based standard for passing claims between parties in web application environments}}
{{Infobox technology standard
| status          = [[Internet Standard#Proposed Standard|Proposed Standard]]
| first_published = {{Start date|2010|12|28}}
| version         = {{IETF RFC|7519}}
| version_date    = May 2015
| organization    = [[Organization:Internet Engineering Task Force|IETF]]
| abbreviation    = JWT
| native_name       = <!-- Name in local language. If more than one, separate using {{plain list}} -->
| native_name_lang  = <!-- ISO 639-2 code e.g. "fr" for French. If more than one, use {{lang}} inside native_name items instead -->
| year_started      = <!-- {{Start date|YYYY|MM|DD|df=y}} -->
| preview           = 
| preview_date      = 
| committee         = [[Organization:Internet Engineering Task Force#Internet Engineering Steering Group|IEGS]]
| series            = 
| editors           = 
| authors           = {{Plainlist|
* Michael B. Jones
* [[Company:Microsoft|Microsoft]]
* John Bradley
* [[Company:Ping Identity|Ping Identity]]
* Nat Sakimura
* [[Organization:Nomura Research Institute|NRI]]
}}
| base_standards    = {{Plainlist|
* [[JSON]]
* [[JSON Web Encryption]] (JWE)
* [[JSON Web Signature]] (JWS)
}}
| related_standards = 
| domain            = [[Data exchange]]
| license           = 
| copyright         = 
| website           = {{URL|https://datatracker.ietf.org/doc/html/rfc7519}}
}}
'''JSON Web Token''' ('''JWT''', suggested pronunciation {{IPAc-en|dʒ|ɒ|t}}, same as the word "jot"<ref name="rfc7519">{{Cite IETF|title=JSON Web Token (JWT)|rfc=7519|last1=Jones|first1=Michael B.|last2=Bradley|first2=Bradley|last3=Sakimura|first3=Sakimura|date=May 2015|publisher=[[Organization:Internet Engineering Task Force|IETF]]|doi=10.17487/RFC7519|issn=2070-1721}}</ref>) is a [[Internet Standard#Proposed Standard|proposed Internet standard]] for creating data with optional signature and/or optional [[Encryption|encryption]] whose [[Payload (computing)|payload]] holds [[JSON]] that asserts some number of [[Claims-based identity|claims]]. The tokens are signed either using a [[Social:Shared secret|private secret]] or a [[Public-key cryptography|public/private key]].

For example, a server could generate a token that has the claim "logged in as administrator" and provide that to a client. The client could then use that token to prove that it is logged in as admin. The tokens can be signed by one party's private key (usually the server's) so that any party can subsequently verify whether the token is legitimate. If the other party, by some suitable and trustworthy means, is in possession of the corresponding public key, they too are able to verify the token's legitimacy. The tokens are designed to be compact,<ref>{{cite book |last1=Nickel |first1=Jochen |title=Mastering Identity and Access Management with Microsoft Azure |date=2016 |isbn=9781785887888 |page=84 |url=https://books.google.com/books?id=Q4dcDgAAQBAJ&pg=PA84 |accessdate=20 July 2018}}</ref> [[URL]]-safe,<ref name="jwtintro" /> and usable, especially in a [[Software:Web browser|web-browser]] [[Single sign-on|single-sign-on]] (SSO) context. JWT claims can typically be used to pass identity of authenticated users between an [[Identity provider|identity provider]] and a [[Finance:Service provider|service provider]], or any other type of claims as required by business processes.<ref>{{Cite web|title = The Anatomy of a JSON Web Token|url = https://scotch.io/tutorials/the-anatomy-of-a-json-web-token|accessdate = 2015-05-08|first = Chris|last = Sevilleja}}</ref><ref>{{Cite web|title = Atlassian Connect Documentation|url = https://developer.atlassian.com/static/connect/docs/latest/concepts/understanding-jwt.html|website = developer.atlassian.com|accessdate = 2015-05-08|archive-date = May 18, 2015|archive-url = https://web.archive.org/web/20150518082002/https://developer.atlassian.com/static/connect/docs/latest/concepts/understanding-jwt.html|url-status = dead}}</ref>

JWT relies on other JSON-based standards: [[JSON Web Signature]] and [[JSON Web Encryption]].<ref name="rfc7519" /><ref name=":1">{{Cite journal|title = draft-ietf-jose-json-web-signature-41 - JSON Web Signature (JWS)|url = https://tools.ietf.org/html/draft-ietf-jose-json-web-signature-41|website = tools.ietf.org| date=May 2015 |accessdate = 2015-05-08 | last1=Jones | first1=Michael B. | last2=Bradley | first2=John | last3=Sakimura | first3=Nat }}</ref><ref name=":2">{{Cite journal|title = draft-ietf-jose-json-web-encryption-40 - JSON Web Encryption (JWE)|url = https://tools.ietf.org/html/draft-ietf-jose-json-web-encryption-40|website = tools.ietf.org| date=May 2015 |accessdate = 2015-05-08 | last1=Jones | first1=Michael B. | last2=Hildebrand | first2=Joe }}</ref>

==Structure==
;Header
:Identifies which algorithm is used to generate the signature. In the below example, <code>HS256</code> indicates that this token is signed using HMAC-SHA256.

:Typical cryptographic algorithms used are [[HMAC]] with SHA-256 (HS256) and [[Digital signature|RSA signature]] with SHA-256 (RS256). JWA (JSON Web Algorithms) RFC 7518 introduces many more for both authentication and encryption.<ref>{{Cite journal|title = draft-ietf-jose-json-web-algorithms-40 - JSON Web Algorithms (JWA)|url = https://tools.ietf.org/html/draft-ietf-jose-json-web-algorithms-40|website = tools.ietf.org| date=May 2015 |accessdate = 2015-05-08 | last1=Jones | first1=Michael B. }}</ref>
:<source lang="json">{
  "alg": "HS256",
  "typ": "JWT"
}
</source>
;Payload
:Contains a set of claims. The JWT specification defines seven Registered Claim Names, which are the standard fields commonly included in tokens.<ref name="rfc7519" /> Custom claims are usually also included, depending on the purpose of the token.
:This example has the standard Issued At Time claim (<code>iat</code>) and a custom claim (<code>loggedInAs</code>).
:<source lang="json">{
  "loggedInAs": "admin",
  "iat": 1422779638
}
</source>
;Signature
:Securely validates the token. The signature is calculated by encoding the header and payload using [[Base64#URL applications|Base64url Encoding]] {{IETF RFC|4648}} and concatenating the two together with a period separator. That string is then run through the cryptographic algorithm specified in the header. This example uses HMAC-SHA256 with a shared secret (public key algorithms are also defined). The ''Base64url Encoding'' is similar to [[Base64|base64]], but uses different non-alphanumeric characters and omits padding.
:<source lang="javascript">
HMAC_SHA256(
  secret,
  base64urlEncoding(header) + '.' +
  base64urlEncoding(payload)
)
</source>

The three parts are encoded separately using [[Base64#URL applications|Base64url Encoding]] {{IETF RFC|4648}}, and concatenated using periods to produce the JWT:
<source lang="javascript">
const token = base64urlEncoding(header) + '.' + base64urlEncoding(payload) + '.' + base64urlEncoding(signature)
</source>

The above data and the secret of "secretkey" creates the token:
{{Pre|eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJsb2dnZWRJbkFzIjoiYWRtaW4iLCJpYXQiOjE0MjI3Nzk2Mzh9.gzSraSYS8EXBxLN_oWnFSRgCzcmJmMjLiuyu5CSpyHI}}

This resulting token can be easily passed into [[HTML]] and [[HTTP]].<ref name="jwtintro">{{cite web |title=JWT.IO - JSON Web Tokens Introduction |url=https://jwt.io/introduction/ |website=jwt.io |accessdate=20 July 2018}}</ref>

== Use ==
In authentication, when the user successfully logs in using their credentials, a JSON Web Token will be returned and must be saved locally (typically in [[Web storage|local or session storage]], but [[HTTP cookie|cookies]] can also be used), instead of the traditional approach of creating a session in the server and returning a cookie. For unattended processes, the client may also authenticate directly by generating and signing its own JWT with a pre-shared secret and pass it to a [[OAuth]] compliant service like so:<source lang="mime">
POST /oauth2/token
Content-type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion=eyJhb...
</source>If the client passes a valid JWT assertion the server will generate an access_token valid for making calls to the application and pass it back to the client:<source lang="json">
{
  "access_token": "eyJhb...",
  "token_type": "Bearer",
  "expires_in": 3600
}
</source>When the client wants to access a protected route or resource, the user agent should send the JWT, typically in the <code>Authorization</code> HTTP header using the <code>Bearer</code> schema. The content of the header might look like the following:
 Authorization: Bearer eyJhbGci''...&lt;snip&gt;...''yu5CSpyHI
This is a stateless authentication mechanism as the user state is never saved in server memory. The server's protected routes will check for a valid JWT in the Authorization header, and if it is present, the user will be allowed to access protected resources. As JWTs are self-contained, all the necessary information is there, reducing the need to query the database multiple times.

== Standard fields ==
{| class="wikitable"
! Code
! Name
! Description
|-
! colspan="2" {{rh}} | Standard claim fields
| The internet drafts define the following standard fields ("claims") that can be used inside a JWT claim set.
|-
|<code>iss</code>
|Issuer
|Identifies principal that issued the JWT.
|-
|<code>sub</code>
|Subject
|Identifies the subject of the JWT.
|-
|<code>aud</code>
|Audience
|Identifies the recipients that the JWT is intended for. Each principal intended to process the JWT '''must''' identify itself with a value in the audience claim. If the principal processing the claim does not identify itself with a value in the <code>aud</code> claim when this claim is present, then the JWT '''must''' be rejected.
|-
|<code>exp</code>
|Expiration Time
|Identifies the expiration time on and after which the JWT '''must not''' be accepted for processing. The value must be a NumericDate:<ref name="rfc-7519-section-4.1.4">{{Cite IETF|title=JSON Web Token (JWT)|rfc=7519|sectionname="exp" (Expiration Time) Claim|section=4.1.4|last1=Jones|first1=Michael B.|last2=Bradley|first2=Bradley|last3=Sakimura|first3=Sakimura|date=May 2015|publisher=[[Organization:Internet Engineering Task Force|IETF]]|doi=10.17487/RFC7519|issn=2070-1721}}</ref> either an integer or decimal, representing seconds past [[Unix time|1970-01-01 00:00:00Z]].
|-
|<code>nbf</code>
|Not Before
|Identifies the time on which the JWT will start to be accepted for processing. The value must be a NumericDate.
|-
|<code>iat</code>
|Issued at
|Identifies the time at which the JWT was issued. The value must be a NumericDate.
|-
|<code>jti</code>
|JWT ID
|Case-sensitive unique identifier of the token even among different issuers.
|-
! colspan="2" {{rh}} | Commonly-used header fields
|The following fields are commonly used in the header of a JWT
|-
|<code>typ</code>
|Token type
|If present, it must be set to a registered [https://www.iana.org/assignments/media-types/media-types.xhtml IANA Media Type].
|-
|<code>cty</code>
|Content type
|If nested signing or encryption is employed, it is recommended to set this to <code>JWT</code>; otherwise, omit this field.<ref name="rfc7519" />
|-
|<code>alg</code>
|Message authentication code algorithm
|The issuer can freely set an algorithm to verify the signature on the token. However, some supported algorithms are insecure.<ref name="auth0" />
|-
|<code>kid</code>
|Key ID
|A hint indicating which key the client used to generate the token signature. The server will match this value to a key on file in order to verify that the signature is valid and the token is authentic.
|-
|<code>x5c</code>
|x.509 Certificate Chain
|A certificate chain in RFC4945 format corresponding to the private key used to generate the token signature. The server will use this information to verify that the signature is valid and the token is authentic.
|-
|<code>x5u</code>
|x.509 Certificate Chain URL
|A URL where the server can retrieve a certificate chain corresponding to the private key used to generate the token signature. The server will retrieve and use this information to verify that the signature is authentic.
|-
|<code>crit</code>
|Critical
|A list of headers that must be understood by the server in order to accept the token as valid
|-
! Code
! Name
! Description
|}

== Implementations ==
JWT implementations exist for many languages and frameworks, including but not limited to:
{{colbegin|colwidth=20em}}
*.NET (C# VB.Net etc.)<ref>[https://github.com/jwt-dotnet/jwt jwt-dotnet] on github.com</ref>
*[[C (programming language)|C]]<ref>[https://github.com/benmcollins/libjwt libjwt] on github.com</ref>
*[[Clojure]]<ref>{{Cite web|url=https://github.com/liquidz/clj-jwt|title=liquidz/clj-jwt|website=GitHub|language=en|access-date=2018-05-07}}</ref>
*[[Common Lisp]]<ref>[https://github.com/gschjetne/cljwt cljwt] on github.com</ref>
* [[Dart (programming language)|Dart]]<ref>[https://github.com/deftomat/JustJWT JustJWT] on github.com</ref>
*[[Elixir (programming language)|Elixir]]<ref>{{Cite web|url=https://github.com/bryanjos/joken|title=bryanjos/joken|website=GitHub|language=en|access-date=2018-05-07}}</ref>
* [[Erlang (programming language)|Erlang]]
*[[Go (programming language)|Go]]<ref>{{Cite web|url=https://github.com/golang-jwt/jwt|title=golang-jwt/jwt|website=GitHub|language=en|access-date=2018-01-08}}</ref>
*[[Haskell (programming language)|Haskell]]<ref>{{Cite web|url=https://hackage.haskell.org/package/jose|title=jose: JSON Object Signing and Encryption (JOSE) and JSON Web Token (JWT) library|website=Hackage|access-date=2022-12-25}}</ref>
*[[Java (programming language)|Java]]<ref>[https://github.com/auth0/java-jwt auth0/java-jwt] on github.com</ref>
*[[JavaScript]]<ref>{{Cite web|url=https://github.com/kjur/jsrsasign|title=kjur/jsrsasign|website=GitHub|language=en|access-date=2018-05-07}}</ref>
*[[Lua (programming language)|Lua]]<ref>{{Cite web|url=https://github.com/SkyLothar/lua-resty-jwt|title=SkyLothar/lua-resty-jwt|website=GitHub|language=en|access-date=2018-05-07}}</ref>
* [[Software:Node.js|Node.js]]<ref>{{Cite web|url=https://www.npmjs.com/package/jsonwebtoken|title=jsonwebtoken|website=npm|access-date=2018-05-07}}</ref>
*[[OCaml]]<ref>[https://github.com/besport/ocaml-jwt ocaml-jwt] on github.com</ref>
*[[Perl]]<ref>[https://metacpan.org/pod/Crypt::JWT Crypt::JWT] on cpan.org</ref>
*[[Organization:PHP|PHP]]<ref>[https://github.com/lcobucci/jwt lcobucci/jwt] on github.com</ref>
*PL/SQL<ref>{{Citation|last=Egan|first=Morten|title=GitHub - morten-egan/jwt_ninja: PLSQL Implementation of JSON Web Tokens.|date=2019-02-07|url=https://github.com/morten-egan/jwt_ninja|access-date=2019-03-14}}</ref>
*[[PowerShell]]<ref>{{Cite web|url=https://github.com/SP3269/posh-jwt|title=SP3269/posh-jwt|website=GitHub|access-date=2018-08-01}}</ref>
*[[Python (programming language)|Python]]<ref>{{Cite web|url=https://github.com/jpadilla/pyjwt|title=jpadilla/pyjwt|website=GitHub|language=en|access-date=2017-03-21}}</ref>
*[[Racket (programming language)|Racket]]<ref>[https://pkgs.racket-lang.org/package/net-jwt net-jwt] on pkgs.racket-lang.org</ref>
*[[Raku (programming language)|Raku]]<ref>[https://github.com/jamesalbert/JSON-WebToken JSON-WebToken] on github.com</ref>
*[[Ruby (programming language)|Ruby]]<ref>[https://github.com/jwt/ruby-jwt ruby-jwt] on github.com</ref>
*[[Rust (programming language)|Rust]]<ref>[https://github.com/Keats/jsonwebtoken jsonwebtoken] on github.com</ref><ref>[https://github.com/mikkyang/rust-jwt rust-jwt] on github.com</ref>
*[[Scala (programming language)|Scala]]<ref>[https://github.com/pauldijou/jwt-scala jwt-scala] on github.com</ref>
*[[Swift (programming language)|Swift]]<ref>[https://github.com/kylef/JSONWebToken.swift] on github.com</ref>
{{colend}}

==Vulnerabilities==
JSON web tokens may contain session state. But if project requirements allow session invalidation before JWT expiration, services can no longer trust token assertions by the token alone. To validate that the session stored in the token is not revoked, token assertions must be checked against a [[Data store|data store]]. This renders the tokens no longer stateless, undermining the primary advantage of JWTs.<ref>{{cite web |last1=Slootweg |first1=Sven |title=Stop using JWT for sessions |url=http://cryto.net/~joepie91/blog/2016/06/13/stop-using-jwt-for-sessions/ |website=joepie91 Ramblings |accessdate=1 August 2018}}</ref>

Security consultant Tim McLean reported vulnerabilities in some JWT libraries that used the <code>alg</code> field to incorrectly validate tokens, most commonly by accepting a <code>alg=none</code> token. While these vulnerabilities were patched, McLean suggested deprecating the <code>alg</code> field altogether to prevent similar implementation confusion.<ref name=auth0>{{Cite web|first=Tim |last=McLean | date=March 31, 2015 | title = Critical vulnerabilities in JSON Web Token libraries|url = https://www.chosenplaintext.ca/2015/03/31/jwt-algorithm-confusion.html|publisher=Auth0|accessdate = 2016-03-29}}</ref> Still, new <code>alg=none</code> vulnerabilities are still being found in the wild, with four [[Common Vulnerabilities and Exposures|CVEs]] filed in the 2018-2021 period having this cause.<ref>{{cite web |title=CVE - Search Results |url=https://cve.mitre.org/cgi-bin/cvekey.cgi?keyword=jwt+none |website=cve.mitre.org}}</ref>{{Better reference needed|date=January 2024}}

With proper design, developers can address algorithm vulnerabilities by taking precautions:<ref name=vuln>{{Cite web|url=https://connect2id.com/products/nimbus-jose-jwt/vulnerabilities|language=en|access-date=2018-05-14|title=Common JWT security vulnerabilities and how to avoid them}}</ref><ref>{{cite web |last1=Andreas |first1=Happe |title=JWT: Signature vs MAC attacks |url=https://snikt.net/blog/2019/05/16/jwt-signature-vs-mac-attacks/ |website=snikt.net |accessdate=27 May 2019}}</ref>

# Never let the JWT header alone drive verification
# Know the algorithms (avoid depending on the {{code|alg}} field alone)
# Use an appropriate key size
Several JWT libraries were found to be vulnerable to an [[Elliptic-curve cryptography#Invalid curve attack|invalid Elliptic-curve attack]] in 2017.<ref>{{Cite web |title=Critical Vulnerability in JSON Web Encryption |url=https://auth0.com/blog/critical-vulnerability-in-json-web-encryption/ |access-date=2023-10-14 |website=Auth0 - Blog |language=en}}</ref>

Some have argued that JSON web tokens are difficult to use securely due to the many different encryption algorithms and options available in the standard, and that alternate standards should be used instead for both web frontends<ref>{{Cite web |title=No Way, JOSE! Javascript Object Signing and Encryption is a Bad Standard That Everyone Should Avoid - Paragon Initiative Enterprises Blog |url=https://paragonie.com/blog/2017/03/jwt-json-web-tokens-is-bad-standard-that-everyone-should-avoid |access-date=2023-10-13 |website=paragonie.com}}</ref> and backends.<ref>{{Cite web |title=Pitfalls of JWT Authorization | url=https://authzed.com/blog/pitfalls-of-jwt-authorization | access-date=2023-11-16 | website=authzed.com}}</ref>

==See also==
* [[API key]]
* Access token
* [[Basic access authentication]]
* [[Digest access authentication]]
* [[Claims-based identity]]
* HTTP header
* Concise Binary Object Representation ([[CBOR]])

==References==
{{Reflist|30em}}

* {{IETF RFC|7519}}
* [https://jwt.io/ jwt.io] – specialized website about JWT with tools and documentation, maintained by Auth0
<!-- Self-published by a blog? * [https://sekurak.pl/jwt-security-ebook.pdf JWT Security] – JWT Security e-Book PDF (Polish language) -->

{{Data exchange}}

[[Category:Computer access control]]
[[Category:Identity management]]
[[Category:Federated identity]]
[[Category:Identity management systems]]
[[Category:Metadata standards]]
[[Category:JSON]]

{{Sourceattribution|JSON Web Token}}