delphi-jose-jwt gives Delphi a JWT library with a swappable crypto backend

JWS is implemented, JWE is only planned

delphi-jose-jwt is a Delphi implementation of JWT, the JSON Web Token, and the JOSE, the JSON Object Signing and Encryption, specification suite.

The scope statement in the README is precise and worth repeating to yourself before anything else. This library supports the JWS, the JSON Web Signature, compact serializations with several JOSE algorithms, plus full JWK, the JSON Web Key, support and a swappable crypto provider backend. JWE support is planned, which means the encryption half of JOSE is not there yet.

That is the single most important fact for an integrator. If your requirement is a signed token that a relying party verifies with a shared secret or a public key, this library does that. If your requirement is an encrypted token, where the payload is only readable by the intended recipient, this library does not do that, and no configuration flag changes it.

The rest of the surface is a proper JOSE implementation rather than a JWT-only convenience wrapper. The compact serialization, which is the dot-separated form you see in an Authorization header, is the one used. JWK support is full, which covers generating, importing and exporting keys, and that matters for deployments where a key is provisioned as a JSON document rather than a PEM file.

The audience is a Delphi developer building a server-side component that issues or validates tokens. The repository topics list auth, jwt, jwt-authentication, jwt-token and rest, and the samples directory includes Basic, Console, CryptoTest, CustomClaims, Exe and Keys, which is a fair picture of the intended use.

Three crypto stacks, and only one of them is registered for you

Since PR #95, every crypto and Base64 operation goes through a swappable provider registry, TJOSEProviders in the JOSE.Providers unit, instead of calling OpenSSL directly. Three provider stacks ship with the library, and the difference between them is the single most consequential choice you make.

The default is TJOSEDefaultProviders in JOSE.Providers.Default, backed by OpenSSL 1.0.x and 1.1.x through Indy, and it is registered automatically at startup. The README is blunt about its limitation: it pokes a few raw OpenSSL struct fields internally, so it does not work against OpenSSL 3.x or 4.x, where those structs are opaque. If you need OpenSSL 3 or 4, you need a different stack.

That is what TJOSETaurusTLSProviders in JOSE.Providers.TaurusTLS is for, backed by OpenSSL 1.1.x, 3.x and 4.x through the TaurusTLS binding for Indy, vendored under Libs\TaurusTLS. It only touches OpenSSL through accessor functions such as RSA_get0_key, RSA_set0_key, EC_KEY_get0_public_key and EC_POINT_get and set_affine_coordinates, so it stays forward-compatible as OpenSSL's structs get more opaque. TaurusTLS itself probes for OpenSSL 4.x DLLs before falling back to 3.x, 1.1 or 1.0.

The third is TJOSECryptoLibProviders in JOSE.Providers.CryptoLib, backed by pure Pascal CryptoLib4Pascal, and it needs no native OpenSSL DLLs at all. That is the stack for a deployment where shipping a native OpenSSL alongside your Delphi binary is not an option.

All three implement JWK PEM import and export. The two newer ones are not part of the .dpk package contains list, so you add the unit and the backing library to your project manually.

Switching crypto backends is a Register call at startup

The provider switch is a small amount of code, and the README shows the shape of it:

uses
  JOSE.Providers,
  JOSE.Providers.TaurusTLS,
  JOSE.Providers.CryptoLib;

begin
  TJOSETaurusTLSProviders.Register; // OpenSSL 3.x/4.x capable, via TaurusTLS
  ...

The pattern is a uses clause listing the provider units you want, and a Register call at startup for the one you want active. The call replaces the default registration, so the choice is made once, in one place, before any token work happens.

The README's warning about packaging is the part that catches people out. Unlike the default OpenSSL and Indy stack, the TaurusTLS and CryptoLib providers are not built into the JOSE .dpk packages. Using either one in your own project means adding its unit and backing library to your project manually, and the TaurusTLS stack additionally needs its runtime package and the OpenSSL 3.x or 4.x binaries, with the location for those binaries documented in the README file under Libs\TaurusTLS\OpenSSL\binaries.

The test suite has the same split, and for the same reason. The TaurusTLS and CryptoLib test projects are separate projects from the main test project precisely because each pulls in its own extra, non-dpk dependencies. The README points you at the test running section before you try to build them.

So the practical cost of the non-default stacks is build and packaging work, not API work. The calls to sign and verify a token do not change. That is a good property of a registry-based design, and it is why the feature is worth having even though it is inconvenient to set up.

The OpenSSL requirement depends on the algorithm and the Delphi version

The README has a section headed Important: OpenSSL requirements, and the rules differ by algorithm and by compiler version.

For HMAC with a SHA algorithm, prior to Delphi 10 Seattle the HMAC-SHA algorithm uses OpenSSL through the Indy library, so in order to generate the token you should have the OpenSSL DLLs on your server system. In Delphi 10 Seattle or newer Delphi versions the HMAC algorithm is also in the System.Hash unit, so OpenSSL is not needed.

For HMAC using RSA or ECDSA, the HMAC-RSA and HMAC-ECDSA algorithms use necessarily OpenSSL, so if you plan to use these algorithms to sign your token you have to download and deploy OpenSSL on the server.

The client-side point is the one that saves deployment headaches. The client does not have to generate or verify the token using SHA or RSA, so on the client side there is no need for the OpenSSL DLLs. If you are writing a mobile or desktop client for a system where the server issues tokens, you can leave the native dependency entirely on the server.

The OpenSSL binaries themselves come from the Indy project page, with the instruction to always update to the latest version and to match your application's bitness. The bitness warning is the one that bites in practice, because a 32-bit Delphi application and a 64-bit OpenSSL build will not load together.

Combined with the provider table, you can now map out your deployment. HMAC with SHA on a modern Delphi needs no native crypto at all if you use the pure Pascal stack, RSA or ECDSA needs OpenSSL on the server whichever stack you choose, and OpenSSL 3 or 4 needs TaurusTLS rather than the default.

The samples and articles are the actual usage documentation

The README's documentation section is a list of four blog articles rather than an API reference, and that choice says something about the project.

The series is JWT authentication with Delphi, in four parts. Part one introduces JWT and authentication technologies, using Delphi. Part two is about understanding the JSON Web Token itself. Part three is about using Delphi-JOSE-JWT to generate and verify JWT tokens. Part four is about using the JWT consumer to validate the claims.

That progression is a teaching sequence rather than a reference manual, and it is the right shape if you are new to JWT. If you are not, the parts that matter are three and four, and the samples directory is the faster route.

The samples cover a spread of situations. Samples/Basic is the minimal case. Samples/Console is a command-line usage. Samples/CryptoTest is where you exercise the crypto providers, which is the file to look at if you are choosing between the three stacks. Samples/CustomClaims is about claims beyond the registered ones, and Samples/Keys is about key handling, which pairs with the JWK support. Samples/Exe is presumably a fuller application.

The repository layout is conventional for a Delphi library. Source/ holds the units, Packages/ holds the .dpk package files, Tests/ the test projects, Docs/ the documentation, and Samples/ the sample projects. There is a boss.json and a boss-lock.json, which are the BOSS (Build Organizer for Source Sets) project files used to describe the package, and a delphi-jose-jwt.dspec file, which is a Delphi package specification.

The Docs directory is worth a look before you start, because the README itself does not enumerate the API.

Where delphi-jose-jwt is the wrong tool

The first wrong-tool case is anything that needs JWE. Encryption of the token payload is planned rather than implemented, and if a security requirement says the token contents must be confidential on the wire, signing is not a substitute. A signed token is readable by anyone who has the token; it is only its integrity that is protected.

The second wrong-tool case is a team that wants the cryptography to be a solved problem with no native dependencies and no packaging work. The pure Pascal CryptoLib4Pascal stack exists precisely for that, and it is a separate package that you add to your project yourself, not a dependency the installer pulls in. If your build is a single self-contained Delphi executable, expect to spend time on the unit search path and the runtime packages.

The third wrong-tool case is a project on a Delphi version where the System.Hash unit is not available and the default provider stack is the only option. On a pre-Seattle compiler, HMAC with SHA goes through OpenSSL and Indy, which means native DLLs on the server for a signature algorithm that most people consider simple.

For the alternative approach, the difference in approach is between a general purpose JOSE implementation and a focused one. A general purpose JOSE library for Delphi or for .NET will cover JWS and JWE, support the whole algorithm set including things like ECDH-ES and the AES key-wrapping algorithms, and ship a broader key management surface. This library covers JWS compact serialization and JWK, and leaves the cryptographic backend to you as a choice of three stacks. If your requirement is a signed JWT, the narrower scope is an advantage, because there is less surface to get wrong and the provider registry makes the crypto auditable. If your requirement is anything in the encryption half of JOSE, the broader library is the only option.

There is also the option of not implementing token handling at all, if your service consumes tokens issued by an identity provider. Verifying a token is a smaller problem than issuing one, and many systems only need the verification path.

MIT licensed, a 4.0 release line, and an active maintenance history

The licence is MIT, and the repository carries a LICENSE file at the root.

The release history shows a project that has been going for a long time and has recently made a significant change. The recent releases are v4.0.2 on 2026-08-23, v4.0.1 on 2026-08-18 and v3.3.1 on 2024-05-02. The gap between 3.3.1 and 4.0.1 is more than two years, and the 4.0 line is a major version, which in Delphi terms usually means unit renames or API changes that will require edits in your code.

What the 4.0 line contains is the provider registry, and the README credits PR #95 for it. So the major version was spent on the crypto backend abstraction, which is a reasonable thing to break a major version for, and it means the older 3.x line does not have the swappable providers.

The last push to the repository was on 2026-10-08, so the tree is being worked on, and the default branch is master.

The practical upgrade path is what to check. Moving from 3.3.1 to 4.0.x means a recompile and probably some renaming, and it means choosing which provider stack you are on. If you are on the default stack and your server runs OpenSSL 3 or 4, the 4.0 line is where the TaurusTLS stack becomes available to you. Reading the Docs directory and the 4.0 release notes before you plan the migration will save more time than the code changes themselves.

For an organisation that has to support an old compiler and a new one at the same time, the two provider stacks and the version gap both point in the same direction: the library gives you room to move, but you have to do the packaging work yourself on the newer stack.

Editorial conclusion

delphi-jose-jwt suits a Delphi developer who needs to sign and verify JWTs in a server-side application, and who needs to choose between OpenSSL through Indy, OpenSSL 3.x and 4.x through TaurusTLS, or a pure Pascal backend. It does not suit a project that needs JWE encryption, since that is only planned, or a team that wants a zero-setup install, because the non-default provider stacks are not part of the shipped packages. Before adopting, decide which crypto backend you will use, because the default stack does not work against OpenSSL 3.x or 4.x, and add the corresponding unit and runtime package to your project before you write the first line of code.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. paolo-rossi/delphi-jose-jwt on GitHub
4. README
5. Releases