jwt-cpp

JSON Traits define the compatibility mapping between jwt-cpp and a specific JSON library implementation. Because jwt-cpp is designed to be library-agnostic, it uses these traits to understand how to interact with your chosen JSON library's types, how to parse strings into JSON objects, and how to serialize JSON objects back into strings.

When using jwt-cpp, you must pass the traits class as a template parameter to core functions like jwt::create<traits>(), jwt::decode<traits>(), and jwt::verify<traits>().

using traits = jwt::traits::nlohmann_json;

const auto token = jwt::create<traits>()
                       .set_issuer("auth.mydomain.io")
                       .sign(jwt::algorithm::hs256{"secret"});

const auto decoded = jwt::decode<traits>(token);

JWTs generated by this library are encoded but not encrypted. While the signature ensures integrity (preventing unauthorized modification), the payload is readable by anyone who has the token.

Do not store confidential or sensitive information directly in JWT claims.

If you need to include sensitive data, the recommended pattern is to generate a random ID, store the sensitive data on your server, and include only that ID in the JWT claims to look up the data when needed.

jwt-cpp does not force a specific JSON library. Instead, it uses a templated jwt::basic_claim that relies on a type trait to map semantic JSON types (objects, arrays, strings, etc.). You can use provided traits or implement your own to integrate your preferred JSON library.

To use your own JSON library, pass your custom traits to jwt::basic_claim:

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

To use jwt-cpp, ensure your environment meets the following requirements:

• libcrypto (OpenSSL or compatible)
• libssl-dev (for header files)
• A compiler supporting at least C++11
• Basic STL support

If you are building the included test cases, you also need:

• gtest
• pthread

You can use jwt-cpp as a header-only library by downloading the include/ directory.

Requirements:

1. Ensure the jwt-cpp/ subdirectory is visible during compilation.
2. You must correctly link to OpenSSL or an alternative cryptography library.
3. If you wish to use your own JSON traits implementation, you must define the following macros:
   • JWT_DISABLE_BASE64
   • JWT_DISABLE_PICOJSON

Refer to traits.md for details on providing custom JSON traits.

When configuring the project with CMake, you can choose which underlying SSL/TLS library to use for cryptographic operations. By default, the project uses OpenSSL.

You can explicitly select one of the following libraries by setting the JWT_SSL_LIBRARY CMake variable:

• OpenSSL (Default)
• LibreSSL
• wolfSSL

Important Note on Linking: Since jwt-cpp relies on the OpenSSL API, both LibreSSL and wolfSSL require their respective compatibility layers. Ensure that your application only includes one SSL library during compilation to avoid missing symbol errors during the linking stage.

cmake . -DJWT_SSL_LIBRARY:STRING=wolfSSL

It is strongly recommended to use a package manager to handle the dependencies for cryptography and JSON libraries. You can find jwt-cpp recipes for the following package managers:

• Conan: https://conan.io/center/recipes/jwt-cpp
• vcpkg: https://vcpkg.link/ports/jwt-cpp
• Nuget: https://www.nuget.org/packages/jwt-cpp/
• Hunter: https://hunter.readthedocs.io/en/latest/packages/pkg/jwt-cpp.html
• Spack: https://packages.spack.io/package.html?name=jwt-cpp
• Xrepo: https://xrepo.xmake.io/#/packages/linux?id=jwt-cpp-linux

The recommended way to use jwt-cpp in a CMake project is via find_package.

Prerequisites:

• Ensure OpenSSL is installed on your environment.

Installation Steps:

1. Configure and build the library:

cmake .
cmake --build .
cmake --install .

2. In your own project's CMakeLists.txt, use find_package and link against the jwt-cpp::jwt-cpp target:

find_package(jwt-cpp CONFIG REQUIRED)

target_link_libraries(my_app PRIVATE jwt-cpp::jwt-cpp)

The examples located in the example/traits/ directory require an upstream CMake installation to function.

Note the following specific dependency requirements for header discovery:

• Boost.JSON: Headers must be located using a custom CMake configuration.
• PicoJSON: Headers must be located using a custom CMake configuration.