Repository files navigation

A header only library for creating and validatingJSON Web Tokens in C++11. For a great introduction,read this.

The objective is to deliver a versatile and universally applicable collection of algorithms, classes, and data structures, fostering adaptability and seamless integration with other libraries that you may already be employing.

jwt-cpp comprehensively supports all algorithms specified in the standard. Its modular design facilitates the seamlessinclusion of additional algorithms without encountering any complications. Should you wish to contribute new algorithms, feel free to initiate a pull request oropen an issue.

For completeness, here is a list of all supported algorithms:

Installation instructions can be foundhere.

A simple example is decoding a token and printing all of itsclaims let's (try it out):

#include<jwt-cpp/jwt.h>#include<iostream>intmain() {    std::stringconst token ="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXUyJ9.eyJpc3MiOiJhdXRoMCIsInNhbXBsZSI6InRlc3QifQ.lQm3N2bVlqt2-1L-FsOjtR6uE-L4E9zJutMWKIe1v1M";auto decoded =jwt::decode(token);for(auto& e : decoded.get_payload_json())        std::cout << e.first <<" =" << e.second <<'\n';}

You can build and runthis example locally after cloning the repository.Running some commands, we can see the contents of theJWT payload

cmake.cmake --build. --target print-claims./print-claims# iss = "auth0"# sample = "test"

You'll very quickly notice JWT are not encrypted but rather cryptographically signed toprovidenon-repudiation.

In order to verify a token you first build a verifier and use it to verify a decoded token.

auto verifier = jwt::verify()    .with_issuer("auth0")    .with_claim("sample", jwt::claim(std::string("test")))    .allow_algorithm(jwt::algorithm::hs256{"secret"});verifier.verify(decoded_token);

The verifier is stateless so you can reuse it for different tokens.

Creating the token above (and signing it) is equally as easy.

auto token = jwt::create()    .set_type("JWS")    .set_issuer("auth0")    .set_payload_claim("sample", jwt::claim(std::string("test")))    .sign(jwt::algorithm::hs256{"secret"});

If you are looking to issue or verify more unique tokens, checkout out theexamples working with RSA public and private keys, elliptic curve tokens, and much more!

Building on the goal of providing flexibility.

jwt-cpp supportsOpenSSL,LibreSSL, andwolfSSL. For a listed of tested versions, checkthis page for more details.

There is no strict reliance on a specific JSON library in this context. Instead, the jwt-cpp utilizes a genericjwt::basic_claim that is templated based on type trait. This trait provides the semanticJSON types for values, objects, arrays, strings, numbers, integers, and booleans, along with methods to seamlessly translate between them.

This design offers flexibility in choosing the JSON library that best suits your needs. To leverage one of the provided JSON traits, refer todocs/traits.md for detailed guidance.

jwt::basic_claim<my_favorite_json_library_traits>claim(json::object({{"json",true},{"example",0}}));

To learn how to writes a trait's implementation, checkout thethese instructions

With regard to the base64 specifications for JWTs, this library includesbase.h encompassing all necessary variants. While the library itself offers a proficient base64 implementation, it's worth noting that base64 implementations are widely available, exhibiting diverse performance levels. If you prefer to use your own base64 implementation, you have the option to defineJWT_DISABLE_BASE64 to exclude the jwt-cpp implementation.

If you have suggestions for improvement or if you've identified a bug, please don't hesitate toopen an issue or contribute by creating a pull request. When reporting a bug, provide comprehensive details about your environment, including compiler version and other relevant information, to facilitate issue reproduction. Additionally, if you're introducing a new feature, ensure that you include corresponding test cases to validate its functionality.

In order to use jwt-cpp you need the following tools.

• libcrypto (openssl or compatible)
• libssl-dev (for the header files)
• a compiler supporting at least c++11
• basic stl support

In order to build the test cases you also need

• gtest
• pthread

See theFAQs for tips.