README.md

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

Signature algorithms

jwt-cpp supports all the algorithms defined by the specifications. The modular design allows to easily add additional algorithms without any problems. If you need any feel free to create a pull request or open an issue.

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

HMSC	RSA	ECDSA	PSS	EdDSA
HS256	RS256	ES256	PS256	Ed25519
HS384	RS384	ES384	PS384	Ed448
HS512	RS512	ES512	PS512
		ES256K

SSL Compatibility

In the name of flexibility and extensibility, jwt-cpp supports OpenSSL, LibreSSL, and wolfSSL. Read this page for more details. These are the version which are currently being tested:

OpenSSL	LibreSSL	wolfSSL

ℹ️ Note: A complete list of versions tested in the past can be found here.

Overview

There is no hard dependency on a JSON library. Instead, there's a generic jwt::basic_claim which is templated around type traits, which described the semantic JSON types for a value, object, array, string, number, integer and boolean, as well as methods to translate between them.

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

This allows for complete freedom when picking which libraries you want to use. For more information, read this page).

For your convenience there are serval traits implementation which provide some popular JSON libraries. They are:

In order to maintain compatibility, picojson is still used to provide a specialized jwt::claim along with all helpers. Defining JWT_DISABLE_PICOJSON will remove this optional dependency. It's possible to directly include the traits defaults for the other JSON libraries. See the traits examples for details.

As for the base64 requirements of JWTs, this library provides base.h with all the required implementation; However base64 implementations are very common, with varying degrees of performance. When providing your own base64 implementation, you can define JWT_DISABLE_BASE64 to remove the jwt-cpp implementation.

Getting Started

Simple example of decoding a token and printing all claims (try it out):

#include <jwt-cpp/jwt.h>
#include <iostream>

int main() {
    std::string token = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXUyJ9.eyJpc3MiOiJhdXRoMCJ9.AbIJTDMFc7yUa5MhvcP03nJPyCPzZtQcGEp-zWfOkEE";
    auto decoded = jwt::decode(token);

    for(auto& e : decoded.get_payload_json())
        std::cout << e.first << " = " << e.second << std::endl;
}

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

auto verifier = jwt::verify()
    .allow_algorithm(jwt::algorithm::hs256{ "secret" })
    .with_issuer("auth0");

verifier.verify(decoded_token);

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

Creating a token (and signing) is equally as easy.

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

To see more examples working with RSA public and private keys, visit our examples!

Providing your own JSON Traits

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

Contributing

If you have an improvement or found a bug feel free to open an issue or add the change and create a pull request. If you file a bug please make sure to include as much information about your environment (compiler version, etc.) as possible to help reproduce the issue. If you add a new feature please make sure to also include test cases for it.

Dependencies

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

Troubleshooting

See the FAQs for tips.

Conference Coverage