JSON web token
A JSON Web Token ( JWT , suggested pronunciation : [ dʒɒt ]) is a JSON- based access token standardized according to RFC 7519 . The JWT enables the exchange of verifiable claims . It is typically used to exchange the identity of a user between an identity provider and a service provider in a system with a third party provider. Furthermore, JWT is suitable for implementing a stateless session, because since all information required for authentication is transferred in the token, the session does not have to be saved on the server.
construction
A JWT consists of three parts: the header, payload and the signature.
Header
The header is a JSON element that describes what type of token it is and which encryption method is used.
field | Surname | meaning |
---|---|---|
Type | Type | Describes the IANA media type of the token. This value is always to describe JWT, the media type application/jwt .
|
cty | Content Type | This field is required if the JWT contains another JWT as a payload. In this case it is JWT set to. Otherwise this field should be omitted.
|
alg | Algorithm | Describes which signature method is used. The signature method usually used is HMAC with SHA-256 ( HS256 ) or RSA with SHA-256 ( RS256 ). It is possible not to use a signature ( none ), but this is not recommended. The possible values are standardized by the JSON Web Encryption (JWE) according to RFC 7516 .
|
For example, the header looks like this:
{
"alg": "HS256",
"typ": "JWT"
}
Payload
The payload is a JSON element that describes the claims.
{
"sub": "1234567890",
"name": "John Doe",
"admin": true
}
Some claims are reserved:
field | Surname | meaning |
---|---|---|
eat | Issuer | The issuer of the token |
sub | Subject | Defines for which subject the claims apply. The sub field defines for whom or what the claims are made.
|
aud | Audience | The target domain for which the token was issued. |
exp | Expiration Time | The expiration date of the token in Unix time , i.e. the number of seconds since 1970-01-01T00:00:00Z .
|
nbf | Not before | The Unix time from which the token is valid. |
iat | Issued At | The Unix time at which the token was issued. |
jti | JWT ID | A unique case-sensitive string that uniquely identifies the token. This can prevent the token from being replicated. This can be a counted number, a GUID or a hash value . If the token recipient receives a token from several issuers, the JWT ID may not be unique. The combination of the issuer (iss) and the JWT ID (jti) can make this unique again. |
Public claims are also defined by the IANA. In addition, the issuer of the JWT can also use a URI defined as a private claim , which is not standardized, however. For example, an ontology such as Dublin Core or FOAF can be used here .
signature
The structure of the signature is defined by JSON Web Signature ( JWS ), a standard standardized in accordance with RFC 7515 .
The signature is generated by hashing the header and the payload in Base64-encoded format separated by a point using the specified hash method:
var encodedString = base64UrlEncode(header) + "." + base64UrlEncode(payload);
var hash = HMACSHA256(encodedString, secret);
Coding
Header, payload and signature are each encoded with Base64-Url and separated from each other by a period. A JWT token can look like this:
jwt = base64_url (header) + "." + base64_url (payload) + "." + base64_url (hash)
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzY290Y2guaW8iLCJleHAiOjEzMDA4MTkzODAsIm5hbWUiOiJDaHJpcyBTZXZpbGxlamEiLCJhZG1pbiI6dHJ1ZX0.03f329983b86f7d9a9f5fef85305880101d5e302afafa20154d094b229f75773
Transfer with HTTP
The JWT can be transmitted in the URL or in the HTTP header.
http://example.com/path?jwt_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
There are two options for the transmission in the HTTP header: The authorization field or the cookie field.
- in the authorization field as a bearer token:
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
- in the cookie field:
Cookie: token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
The two methods have different advantages and disadvantages:
Bearer token | Cookie | |
---|---|---|
Header |
Authorization: Bearer <JWT>
|
Cookie: token=<JWT>
|
CORS | Works with CORS, but implementation in JavaScript is required. | The browser only transmits the cookie for the current domain. CORS is not possible. |
storage | All storage methods that can be addressed by JavaScript, such as WebStorage and the Cookie Store, are possible. | The cookie is stored in the cookie store. |
Protection against MITM | The presence of TLS must be checked in JavaScript. | If the flag is set secure on the cookie, TLS is enforced.
|
Protection against XSS | Must be implemented in JavaScript. | Implicit if the flag is set HttpOnly on the cookie to prevent access using JavaScript .
|
Protection against CSRF | Not possible. Other measures are necessary here. | Must be implemented in JavaScript. |
Implementations
Implementations for JWT are available for a variety of platforms. A current list can be found on the JWT.io page, for example.
Security event token
A Security Event Token ( SET ) extends the JWT standard with the events
claim, which records a list of security-relevant events. These tokens have a time stamp and are valid indefinitely. A SET payload can look like this:
{
"iss": "https://server.example.com",
"sub": "248289761001",
"aud": "s6BhdRkqt3",
"iat": 1471566154,
"jti": "bWJq",
"sid": "08a5019c-17e1-4977-8f42-65a12843ea02",
"events": {
"http://schemas.openid.net/event/backchannel-logout": {}
}
}
SETs are used in auditing . SETs are specified in RFC 8417 .
See also
- Security Assertion Markup Language (SAML)
- OAuth and OpenID
Web links
- Bernd Schönbach: User authentication in microservice environments. In: Heise Developer. Verlag Heinz Heise , June 9, 2017, accessed June 11, 2017 .
swell
- ↑ Prabath Siriwardena : Advanced API Security: OAuth 2.0 and Beyond . Apress, New York 2020, ISBN 978-1-4842-2049-8 , pp. 163 .
- ↑ JSON Web Token Claims. February 23, 2017, Retrieved May 14, 2017 (List of JWT Public Claims).
- ↑ JWT. Auth0 , accessed on May 14, 2017 .
- ↑ Security Event Token (SET) Specification and IETF Security Events Working Group. Retrieved May 14, 2017 (English).