CerberAuth
How to verify a JWT?
Understanding JWTs (JSON Web Tokens) and how to effectively validate their authenticity is important. JWT is a versatile tool for securing web applications and APIs, making it vital for developers to possess the knowledge and skills required for their proper verification.
In this blog post, we will explore the fundamentals of JWTs, their significance, and the systematic approach developers should adopt to verify them.
TL;DR
- Install an existing JWT library to benefit from well-tested and robust security solutions
- If you are using the OAuth2 protocol and you can afford it, prefer using the introspection endpoint
- Configure the library with the signing algorithm used, secret or public key location depending on the algorithm.
- If the library used does not perform those verifications, check if the token contains the expected issuer (
iss) and expected audience (aud)
Understanding JWT
JSON Web Token, or JWT, is a method for transmitting claims between various entities. These claims often take the form of JSON objects and are frequently used to facilitate user authentication and authorization in web-based environments. JWT consists of three principal components:
- Header: The header includes at least two components, specifying the token type (JWT) and the employed signing algorithm (e.g., HMAC or RSA / ECDSA).
- Payload: The payload contains the claims, which encompass statements about an entity (typically the user) and additional data.
- Signature: The signature is generated through a combination of the encoded header, encoded payload, a secret key (for HMAC-based algorithms), or a public key (for RSA/ECDSA-based algorithms), and the algorithm specified in the header.
Importance of JWT Verification
Validating JWTs is an indispensable task for developers due to the following key reasons:
- Authentication: JWTs serve as a mechanism to confirm the identity of users, thereby preventing unauthorized access.
- Authorization: JWTs can encapsulate application authorization scopes (
scp), allowing developers to determine and enforce specific actions - Data Integrity: The digital signature featured in JWTs guarantees that the transmitted data remains unaltered during transit.
OAuth 2 (and OpenID Connect) Token verification
In the context of OAuth2 or protocols based on it, such as OpenID Connect, one token validation solution is the use of the introspection endpoint. The introspection endpoint serves as a dedicated mechanism for validating JWT tokens and provides an efficient way to check the token's validity and obtain essential token information.
This approach offloads the token verification process from the relying party, allowing for centralized management and real-time monitoring of tokens on the authorization server side. The main advantage of centralizing the verification process is that makes the token invalidation almost immediate compared to a decentralized approach.
Here is an example of how to use the introspection endpoint:
POST /introspect HTTP/1.1
Host: server.example.com
Authorization : Basic <basic-header>
token=<access-token>
The token parameter in the request body contains the access token to be introspected.
The response from the introspection endpoint typically includes the token's validity status, the token's scope, the token's client ID, and other relevant information. The response may look like this:
{
"active": true,
"scope": "read write",
"client_id": "client_id",
"username": "user_id",
"token_type": "Bearer",
"exp": 1635200000,
"iat": 1635196400,
"nbf": 1635196400,
"sub": "user_id",
"aud": "https://api.example.com"
}
If the token is valid, the active field will be set to true, indicating that the token is currently active and can be used to access protected resources. If the token is invalid, the active field will be set to false, signaling that the token should not be accepted as follows:
{
"active": false
}
SPoF Warning
It's important to note that while the introspection endpoint can be powerful for JWT verification, it also introduces a potential single point of failure (SPoF) in your system. Relying solely on the introspection endpoint means that if it becomes unavailable or experiences issues, it can disrupt your entire authentication process.
Therefore, it's advisable to use it judiciously and only when there's a genuine need for real-time token verification. In some cases, a combination of introspection and other verification methods, like JWT signature validation, may provide a more robust and fault-tolerant approach to JWT verification, reducing the risk.
Always consider the specific requirements and constraints of your system when deciding whether to adopt the introspection endpoint for JWT verification.
JWT Verification
First, it is strongly encouraged to utilize established JWT verification libraries in your language instead of crafting your own basic verification mechanisms to benefit from well-tested and robust security solutions. Check out for your language which library exists for making JWT verification.
When employing these libraries, it's essential to configure the expected signing algorithm. Not configuring the expected algorithm and using the one existing in JWT can lead to algorithm manipulation with some known vulnerabilities like using None algorithm.
In addition, you will have to configure the secret or public key URL, depending on the algorithm employed (secret for HMAC and public key with kid for RSA and ECDSA).
These libraries typically handle the verification of essential JWT claims, including but not limited to:
In addition, your service may require additional claims to be verified to limit token usage to specific audiences or scopes with the following claims:
If the library supports issuer and audience verification, configure them with your expected values. However, if the library lacks this verification, you'll need to manually verify these claims with strict equality to ensure they match your expected values.
