News Improving The Developer Experience of Your APIs

Enterprise Documentation

Recent changes

You are viewing a previous version of KrakenD Enterprise Edition (v2.1) , go to the latest version

JSON Web Tokens overview

Document updated on Nov 3, 2018

The JSON Web Token specification is an industry standard to represent claims securely between two parties. The JWT is a base64 encoded JSON object that contains key-value pairs of attributes that are signed by a trusted authority.

When JWT shields a specific set of endpoints, requests to the API gateway must provide a token. Verification of the token takes place in every request, including the check of the signature and optionally the assurance that its issuer, roles, and audience are sufficient to access the endpoint. No external access is needed other than the initial load of the JWK url to validate tokens.

Only in the case that the token is valid and passes all the checks, the user is authorized to access the endpoint and continue with the request.

KrakenD JWT implementations

KrakenD implements both JWT signing and JWT validation models to protect endpoints from undesired users that are not entitled to use the information, reinforcing security.

  • Sign tokens when you have no identity server yet (like a classic monolithic application with a /login endpoint) and let KrakenD take care of the token signing with the private key.
  • Validate tokens issued by a third party or the JWT signing middleware, ensuring their integrity and proper claims.

A stateless system like KrakenD does not issue tokens, this is the responsibility of your backend or identity server.

Key concepts

The JSON Web Token carries the information your end-users pass to the system to be recognized as legitimate users with other metadata.

KrakenD uses standard JWT tokens to protect endpoints, using JSON Web Signature (JWS), to check the tokens’ digital signature integrity of the contained claims and defending against attacks using tampered tokens.

A JWT token is a base64 encoded string with the structure header.payload.signature.

A typical request to an endpoint requiring JWT validation includes a Bearer in the Authorization header:

$GET /resource HTTP/1.1
Authorization: Bearer eyJhbGciOiJIUzI1NiIXVCJ9.(truncated).ktIOfzak2ekD7IrCa9-UiO4QA

Or instead, you can send the token inside a cookie (see cookie_key).

All tokens transmitted between users and KrakenD have to be signed using JWS to ensure they are legitimate and not forged by an attacker. JWS represents digitally signed content using JSON data structures that are base64url encoded using the format header.payload.signature.

Finally, KrakenD needs to retrieve the keys from the trusted authority (your Identity Provider) that let the system validate the signature. These keys transmit between KrakenD and the IdP using the JWK format, a JSON object representing a set of cryptographic keys. Objects will use one or another algorithm depending on the system and implementation in your IdP. JWA represents the set of algorithms you can use to sign your tokens.

The introduction above is very superficial; the recommended read is the RFC:

New to JWT?
If you are not familiar with JWT yet, read the “Introduction to JSON Web Tokens

Unresolved issues?

The documentation is only a piece of the help you can get! Whether you are looking for Open Source or Enterprise support, see more support channels that can help you.