JWT (JSON Web Token): What is it?

What is JWT (JSON Web Token)?

JSON Web Token, abbreviated JWT (pronounced "jot"), is an open standard defined by RFC 7519 that enables the creation of compact, secure access tokens. A JWT is a Base64URL-encoded string composed of three parts separated by dots: the header, the payload, and the signature. The header specifies the signing algorithm (HS256, RS256), the payload contains claims such as the user's identity and permissions, and the signature guarantees the token's integrity.

Unlike classic session-based authentication where the server stores the connection state, a JWT is self-contained: all the information necessary for verification is contained within the token itself. The server only needs to verify the signature's validity with its secret key, without querying a session database. This property makes JWT particularly suited to distributed architectures, microservices, and REST APIs consumed by mobile applications or JavaScript clients.

JWT has established itself as the de facto standard for modern API authentication. In the Django ecosystem, the djangorestframework-simplejwt library provides full integration with Django REST Framework, offering JWT token generation, refresh, and verification.

Why JWT matters

JWT adoption transforms how modern applications handle authentication and authorisation. Its unique characteristics address the challenges of contemporary architectures.

• Stateless architecture: JWT eliminates the need to store sessions on the server, simplifying horizontal scaling. Each application instance can verify a token independently.
• Cross-domain interoperability: unlike session cookies limited to a single domain, JWT can be transmitted between different services and domains via the Authorization header, facilitating microservices architectures.
• Native mobile support: mobile applications and API clients do not have access to browser cookies. JWT offers a universal authentication mechanism that works identically across all platforms.
• Performance: verifying a JWT requires only a local cryptographic operation (signature verification), with no round-trip to the database or a centralised session service.
• Custom claims: the JWT payload can contain business information (role, permissions, organisation) directly accessible by the application without additional queries.

How it works

The JWT authentication flow unfolds in several steps. The user first authenticates with their credentials (email and password) against a login endpoint. The server verifies the credentials, then generates a pair of tokens: an access token (short-lived, typically 15 to 60 minutes) and a refresh token (long-lived, typically 7 to 30 days). The client stores these tokens (localStorage, HttpOnly cookie, or memory) and includes the access token in the Authorization header of each API request: Authorization: Bearer eyJhbGciOiJIUzI1....

When the access token expires, the client uses the refresh token to obtain a new one without re-entering credentials. The server verifies the refresh token, and if valid, issues a new access token. This mechanism offers a trade-off between security (short-lived tokens) and user experience (no frequent re-authentication).

JWT security relies on cryptographic signatures. With the symmetric HS256 algorithm, the server uses a single secret key to sign and verify tokens. With the asymmetric RS256 algorithm, a private key signs tokens and a public key verifies them, which is ideal in distributed architectures where verification services do not need access to the signing key.

Concrete example

At KERN-IT, we use JWT in our applications that expose REST APIs consumed by multiple clients. For an IoT platform, data collected by Raspberry Pi devices is transmitted via MQTT to our Python backend (Flask or Django depending on the project), while web dashboards and mobile applications access data via a JWT-authenticated REST API. Each Raspberry Pi has a long-lived service token, while human users obtain short-lived access tokens via the standard login flow.

We configured djangorestframework-simplejwt with 30-minute access tokens and 14-day refresh tokens. Custom claims include the user's role and identifiers of projects they can access, enabling fine-grained access control directly from the token without additional database queries. The refresh token is stored in an HttpOnly cookie to prevent access by malicious JavaScript (XSS protection).

Implementation

1. Install djangorestframework-simplejwt: add the library to your Django project and configure it in REST_FRAMEWORK with DEFAULT_AUTHENTICATION_CLASSES.
2. Configure token lifetimes: set appropriate durations for the access token (15-60 min) and refresh token (7-30 days) according to your required security level.
3. Add custom claims: extend the token serializer to include useful business information (role, permissions, tenant) in the JWT payload.
4. Secure client-side storage: store the refresh token in an HttpOnly/Secure/SameSite cookie and the access token in memory (JavaScript variable) to minimise the XSS attack surface.
5. Implement refresh token rotation: enable ROTATE_REFRESH_TOKENS = True and BLACKLIST_AFTER_ROTATION = True so that a refresh token can only be used once.
6. Set up revocation: configure a token blacklist (via simplejwt.token_blacklist) to be able to invalidate tokens upon logout or compromise.

Associated technologies and tools

• djangorestframework-simplejwt: reference library for JWT integration with Django REST Framework, supporting access/refresh tokens and blacklisting.
• Django REST Framework: REST API building toolkit for Django, with native JWT authentication support.
• PyJWT: low-level Python library for encoding and decoding JWT tokens.
• OAuth 2.0: authorisation protocol that often uses JWT as the access token format.
• jwt.io: online tool for decoding, verifying, and debugging JWT tokens during development.
• Keycloak / Auth0: identity servers that issue and manage JWTs for centralised authentication (SSO).

Conclusion

JWT has established itself as the authentication standard for modern REST APIs thanks to its stateless nature, compactness, and interoperability. Combined with Django REST Framework via djangorestframework-simplejwt, it offers a robust and performant authentication solution for distributed applications. At KERN-IT, we use JWT in our IoT platforms and business applications to secure communications between Raspberry Pi sensors, Django backends, and web interfaces, applying best practices for token rotation and secure storage in line with OWASP recommendations.