ydb/contrib/libs/jwt-cpp/README.md

jwt-cpp

A header only library for creating and validating json web tokens in c++.

Signature algorithms

As of version 0.2.0 jwt-cpp supports all algorithms defined by the spec. The modular design of jwt-cpp allows one to add additional algorithms without any problems. If you need any feel free to open a pull request. For the sake of completeness, here is a list of all supported algorithms:

• HS256
• HS384
• HS512
• RS256
• RS384
• RS512
• ES256
• ES384
• ES512
• PS256
• PS384
• PS512

Examples

Simple example of decoding a token and printing all claims:

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

int main(int argc, const char** argv) {
	std::string token = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXUyJ9.eyJpc3MiOiJhdXRoMCJ9.AbIJTDMFc7yUa5MhvcP03nJPyCPzZtQcGEp-zWfOkEE";
	auto decoded = jwt::decode(token);

	for(auto& e : decoded.get_payload_claims())
		std::cout << e.first << " = " << e.second.to_json() << 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 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"});

Here is a simple example of creating a token that will expire in one hour:

auto token = jwt::create()
	.set_issuer("auth0")
	.set_issued_at(std::chrono::system_clock::now())
	.set_expires_at(std::chrono::system_clock::now() + std::chrono::seconds{3600})
	.sign(jwt::algorithm::hs256{"secret"});

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 installed in linker path
• pthread

Troubleshooting

Expired tokens

If you are generating tokens that seem to immediately expire, you are likely not using UTC. Specifically, if you use get_time to get the current time, it likely uses localtime, while this library uses UTC, which may be why your token is immediately expiring. Please see example above on the right way to use current time.

Missing _HMAC amd _EVP_sha256 symbols on Mac

There seems to exists a problem with the included openssl library of MacOS. Make sure you link to one provided by brew. See here for more details.

Building on windows fails with syntax errors

The header "Windows.h", which is often included in windowsprojects, defines macros for MIN and MAX which screw up std::numeric_limits. See here for more details. To fix this do one of the following things:

• define NOMINMAX, which suppresses this behaviour
• include this library before you include windows.h
• place #undef max and #undef min before you include this library