TsgcHTTP_JWT_Client › Properties › JWTOptions

JWTOptions Property

Token configuration: algorithm, signing key material, standard claims and custom header/payload entries.

Syntax

property JWTOptions: TsgcHTTP_JWT_Client_Options read FJWTOptions write SetJWTOptions;

Default Value

Header.alg=jwtHS256; RefreshTokenAfter=0 (token regenerated on every request); all other string/integer claims empty.

Remarks

Publishes everything required to build and sign a JSON Web Token (RFC 7519). The sub-objects map 1:1 to the JWT wire format:

• Header – JOSE header. Main field is alg (jwtHS256/384/512, jwtRS256/384/512, jwtES256/384/512, jwtMLDSA44/jwtMLDSA65/jwtMLDSA87); optional typ and kid. Call Header.AddKeyValue to add any extra field.
• Payload – standard registered claims: iss (issuer), sub (subject), aud (audience), exp (expiration, Unix time), nbf (not-before), iat (issued-at), jti (JWT ID). Custom claims are added via Payload.AddKeyValue.
• Algorithms – key material selected by Header.alg:
  • HS.Secret – shared secret for HMAC (HS256/384/512).
  • RS.PrivateKey – PEM-encoded RSA private key for RS256/384/512.
  • ES.PrivateKey – PEM-encoded ECDSA private key for ES256/384/512.
  • MLDSA.PrivateKey, a PKCS#8 PEM ML-DSA private key for ML-DSA-44/65/87 (RFC 9964). Any of the three private key forms of RFC 9881 is accepted, the seed form, the expanded form or both, and the parameter set of the key must be the one Header.alg names, otherwise signing raises.
• RefreshTokenAfter – seconds the signed token is valid. When greater than zero, Sign automatically refreshes iat and recomputes exp = iat + RefreshTokenAfter; leave at 0 to regenerate the token on every request.
• OpenSSL_Options – OpenSSL API version and library path (APIVersion, LibPath, LibPathCustom, UnixSymLinks) used by the RS and ES algorithms. The ML-DSA algorithms do not use it, they are pure Object Pascal from the sgcCrypto pack and need no OpenSSL library.

An ML-DSA signature is large, 2420 bytes for ML-DSA-44 and 4627 for ML-DSA-87, so the token grows by roughly 3.2 KB to 6.2 KB of base64url compared with an ES256 one. Check the header size limit of every proxy and server the token passes through before choosing one. See JWT for the algorithm itself and for the AKP JSON Web Key helpers that convert a JWK into the PEM this property takes.

There is no Issuer/Audience/Expiration property at the root of JWTOptions; those RFC 7519 claims are set via Payload.iss, Payload.aud and Payload.exp respectively.

Example

oJWT.JWTOptions.Header.alg := jwtHS256;
oJWT.JWTOptions.Algorithms.HS.Secret := '79F66F1E-E998-436B-8A0A-3E5DEFA4FD9E';
oJWT.JWTOptions.Payload.iss := '2886EC7547B7BA6A9009';
oJWT.JWTOptions.Payload.sub := '1234567890';
oJWT.JWTOptions.Payload.iat := 1630925658;
oJWT.JWTOptions.Payload.exp := 1630933158;
oJWT.JWTOptions.Payload.AddKeyValue('origin', 'www.yourwebsite.com');
oJWT.JWTOptions.RefreshTokenAfter := 60 * 40;

// Post-quantum signatures, no OpenSSL involved
oJWT.JWTOptions.Header.alg := jwtMLDSA65;
oJWT.JWTOptions.Algorithms.MLDSA.PrivateKey.Text :=
  '-----BEGIN PRIVATE KEY-----' + sLineBreak +
  'MFICAQAwCwYJYIZIAWUDBAMSBECy...' + sLineBreak +
  '-----END PRIVATE KEY-----';
oJWT.JWTOptions.Payload.sub := '1234567890';

Back to Properties