|
| 1 | +<img src="https://raw.githubusercontent.com/Thalhammer/jwt-cpp/master/.github/logo.svg" alt="logo" width="100%"> |
| 2 | + |
| 3 | +[](https://github.com/Thalhammer/jwt-cpp/blob/master/LICENSE) |
| 4 | +[](https://app.codacy.com/gh/Thalhammer/jwt-cpp/dashboard) |
| 5 | +[![Linux Badge][Linux]][Cross-Platform] |
| 6 | +[![MacOS Badge][MacOS]][Cross-Platform] |
| 7 | +[![Windows Badge][Windows]][Cross-Platform] |
| 8 | +[](https://coveralls.io/github/Thalhammer/jwt-cpp?branch=master) |
| 9 | + |
| 10 | +[](https://thalhammer.github.io/jwt-cpp/) |
| 11 | + |
| 12 | +[](https://github.com/Thalhammer/jwt-cpp/stargazers) |
| 13 | +[](https://github.com/Thalhammer/jwt-cpp/releases) |
| 14 | +[](https://repology.org/project/jwt-cpp/versions) |
| 15 | +[](https://repology.org/project/jwt-cpp/versions) |
| 16 | + |
| 17 | +[Linux]: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/Thalhammer/jwt-cpp/badges/cross-platform/ubuntu-latest/shields.json |
| 18 | +[MacOS]: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/Thalhammer/jwt-cpp/badges/cross-platform/macos-latest/shields.json |
| 19 | +[Windows]: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/Thalhammer/jwt-cpp/badges/cross-platform/windows-latest/shields.json |
| 20 | +[Cross-Platform]: https://github.com/Thalhammer/jwt-cpp/actions?query=workflow%3A%22Cross-Platform+CI%22 |
| 21 | + |
| 22 | +A header only library for creating and validating [JSON Web Tokens](https://tools.ietf.org/html/rfc7519) in C++11. For a great introduction, [read this](https://jwt.io/introduction/). |
| 23 | + |
| 24 | +## Signature algorithms |
| 25 | + |
| 26 | +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](https://github.com/Thalhammer/jwt-cpp/issues/new). |
| 27 | + |
| 28 | +For completeness, here is a list of all supported algorithms: |
| 29 | + |
| 30 | +| HMSC | RSA | ECDSA | PSS | EdDSA | |
| 31 | +|-------|-------|--------|-------|---------| |
| 32 | +| HS256 | RS256 | ES256 | PS256 | Ed25519 | |
| 33 | +| HS384 | RS384 | ES384 | PS384 | Ed448 | |
| 34 | +| HS512 | RS512 | ES512 | PS512 | | |
| 35 | +| | | ES256K | | | |
| 36 | + |
| 37 | +## SSL Compatibility |
| 38 | + |
| 39 | +In the name of flexibility and extensibility, jwt-cpp supports [OpenSSL](https://github.com/openssl/openssl), [LibreSSL](https://github.com/libressl-portable/portable), and [wolfSSL](https://github.com/wolfSSL/wolfssl). Read [this page](docs/ssl.md) for more details. These are the version which are currently being tested: |
| 40 | + |
| 41 | +| OpenSSL | LibreSSL | wolfSSL | |
| 42 | +|-------------------|----------------|----------------| |
| 43 | +| ![1.0.2u][o1.0.2] | ![3.3.6][l3.3] | ![5.1.1][w5.1] | |
| 44 | +| ![1.1.0i][o1.1.0] | ![3.4.3][l3.4] | ![5.2.0][w5.2] | |
| 45 | +| ![1.1.1q][o1.1.1] | ![3.5.3][l3.5] | ![5.3.0][w5.3] | |
| 46 | +| ![3.0.5][o3.0] | | | |
| 47 | + |
| 48 | +> ℹ️ Note: A complete list of versions tested in the past can be found [here](https://github.com/Thalhammer/jwt-cpp/tree/badges). |
| 49 | +
|
| 50 | +[o1.0.2]: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/Thalhammer/jwt-cpp/badges/openssl/1.0.2u/shields.json |
| 51 | +[o1.1.0]: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/Thalhammer/jwt-cpp/badges/openssl/1.1.0i/shields.json |
| 52 | +[o1.1.1]: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/Thalhammer/jwt-cpp/badges/openssl/1.1.1q/shields.json |
| 53 | +[o3.0]: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/Thalhammer/jwt-cpp/badges/openssl/3.0.5/shields.json |
| 54 | +[l3.3]: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/Thalhammer/jwt-cpp/badges/libressl/3.3.6/shields.json |
| 55 | +[l3.4]: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/Thalhammer/jwt-cpp/badges/libressl/3.4.3/shields.json |
| 56 | +[l3.5]: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/Thalhammer/jwt-cpp/badges/libressl/3.5.3/shields.json |
| 57 | +[w5.1]: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/Thalhammer/jwt-cpp/badges/wolfssl/5.1.1/shields.json |
| 58 | +[w5.2]: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/Thalhammer/jwt-cpp/badges/wolfssl/5.2.0/shields.json |
| 59 | +[w5.3]: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/Thalhammer/jwt-cpp/badges/wolfssl/5.3.0/shields.json |
| 60 | + |
| 61 | +## Overview |
| 62 | + |
| 63 | +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](https://json-schema.org/understanding-json-schema/reference/type.html) for a value, object, array, string, number, integer and boolean, as well as methods to translate between them. |
| 64 | + |
| 65 | +```cpp |
| 66 | +jwt::basic_claim<my_favorite_json_library_traits> claim(json::object({{"json", true},{"example", 0}})); |
| 67 | +``` |
| 68 | +
|
| 69 | +This allows for complete freedom when picking which libraries you want to use. For more information, [read this page](docs/traits.md)). |
| 70 | +
|
| 71 | +For your convenience there are serval traits implementation which provide some popular JSON libraries. They are: |
| 72 | +
|
| 73 | +[![picojson][picojson]](https://github.com/kazuho/picojson) |
| 74 | +[![nlohmann][nlohmann]](https://github.com/nlohmann/json) |
| 75 | +[![jsoncons][jsoncons]](https://github.com/danielaparker/jsoncons) |
| 76 | +[![boostjson][boostjson]](https://github.com/boostorg/json) |
| 77 | +
|
| 78 | +[picojson]: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/Thalhammer/jwt-cpp/badges/traits/kazuho-picojson/shields.json |
| 79 | +[nlohmann]: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/Thalhammer/jwt-cpp/badges/traits/nlohmann-json/shields.json |
| 80 | +[jsoncons]: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/Thalhammer/jwt-cpp/badges/traits/danielaparker-jsoncons/shields.json |
| 81 | +[boostjson]: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/Thalhammer/jwt-cpp/badges/traits/boost-json/shields.json |
| 82 | +
|
| 83 | +In order to maintain compatibility, [picojson](https://github.com/kazuho/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](https://github.com/Thalhammer/jwt-cpp/tree/master/example/traits) for details. |
| 84 | +
|
| 85 | +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. |
| 86 | +
|
| 87 | +### Getting Started |
| 88 | +
|
| 89 | +Simple example of decoding a token and printing all [claims](https://tools.ietf.org/html/rfc7519#section-4) ([try it out](https://github.com/Thalhammer/jwt-cpp/tree/master/example/print-claims.cpp)): |
| 90 | +
|
| 91 | +```cpp |
| 92 | +#include <jwt-cpp/jwt.h> |
| 93 | +#include <iostream> |
| 94 | +
|
| 95 | +int main() { |
| 96 | + std::string token = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXUyJ9.eyJpc3MiOiJhdXRoMCJ9.AbIJTDMFc7yUa5MhvcP03nJPyCPzZtQcGEp-zWfOkEE"; |
| 97 | + auto decoded = jwt::decode(token); |
| 98 | +
|
| 99 | + for(auto& e : decoded.get_payload_json()) |
| 100 | + std::cout << e.first << " = " << e.second << std::endl; |
| 101 | +} |
| 102 | +``` |
| 103 | + |
| 104 | +In order to verify a token you first build a verifier and use it to verify a decoded token. |
| 105 | + |
| 106 | +```cpp |
| 107 | +auto verifier = jwt::verify() |
| 108 | + .allow_algorithm(jwt::algorithm::hs256{ "secret" }) |
| 109 | + .with_issuer("auth0"); |
| 110 | + |
| 111 | +verifier.verify(decoded_token); |
| 112 | +``` |
| 113 | +
|
| 114 | +The created verifier is stateless so you can reuse it for different tokens. |
| 115 | +
|
| 116 | +Creating a token (and signing) is equally as easy. |
| 117 | +
|
| 118 | +```cpp |
| 119 | +auto token = jwt::create() |
| 120 | + .set_issuer("auth0") |
| 121 | + .set_type("JWS") |
| 122 | + .set_payload_claim("sample", jwt::claim(std::string("test"))) |
| 123 | + .sign(jwt::algorithm::hs256{"secret"}); |
| 124 | +``` |
| 125 | + |
| 126 | +> To see more examples working with RSA public and private keys, visit our [examples](https://github.com/Thalhammer/jwt-cpp/tree/master/example)! |
| 127 | +
|
| 128 | +### Providing your own JSON Traits |
| 129 | + |
| 130 | +To learn how to writes a trait's implementation, checkout the [these instructions](docs/traits.md) |
| 131 | + |
| 132 | +## Contributing |
| 133 | + |
| 134 | +If you have an improvement or found a bug feel free to [open an issue](https://github.com/Thalhammer/jwt-cpp/issues/new) 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. |
| 135 | + |
| 136 | +## Dependencies |
| 137 | + |
| 138 | +In order to use jwt-cpp you need the following tools. |
| 139 | + |
| 140 | +* libcrypto (openssl or compatible) |
| 141 | +* libssl-dev (for the header files) |
| 142 | +* a compiler supporting at least c++11 |
| 143 | +* basic stl support |
| 144 | + |
| 145 | +In order to build the test cases you also need |
| 146 | + |
| 147 | +* gtest |
| 148 | +* pthread |
| 149 | + |
| 150 | +## Troubleshooting |
| 151 | + |
| 152 | +See the [FAQs](docs/faqs.md) for tips. |
| 153 | + |
| 154 | +## Conference Coverage |
| 155 | +[](https://www.youtube.com/watch?v=Oq4NW5idmiI) |
0 commit comments