JWT issuer

Creates a signed JSON Web Token for a user, and optionally a refresh token. Use it in a login endpoint after the user's credentials have been checked; the JWT validator with the matching key accepts the token later.

Pins

Pin	Kind	Types	Description
Input	input	Viaducta.Plugins.JWTIssuer.JwtIssuerUserData	User data: UserName, UserId, Email, Claims (dictionary).
Output	output	Viaducta.Plugins.JWTIssuer.JwtData	Token, TokenType, ExpiresIn, Username, UserId, Email, ValidFrom, ValidTo, RefreshToken, RefreshTokenValidTo.

Configuration

Field	Type	Default	Description
UseLifetime	boolean	true	true: the token gets an expiry (exp).
TokenLifetime	string	24:00:00	Validity when UseLifetime is true: hh:mm:ss where the hours may exceed 23 (24:00:00 is one day, 36:00:00 a day and a half), or d.hh:mm:ss (7.00:00:00 is a week).
Issuer	string		Required. iss claim.
Audience	string		aud claim, comma separated for several audiences (omitted when empty).
Algorithm	int	0	0 HS256, 1 HS384, 2 HS512 (shared secret); 3 RS256, 4 RS384, 5 RS512 (RSA key); 6 ES256, 7 ES384, 8 ES512 (EC key); 9 PS256, 10 PS384, 11 PS512 (RSA-PSS).
SigningKey	string		Required. HS*: the shared secret, at least 32 bytes for HS256, 48 for HS384, 64 for HS512. RS*, ES*, PS*: the private key in PEM format (PKCS#8 or PKCS#1, unencrypted; RSA at least 2048 bits, the EC curve must match the algorithm).
KeyEncoding	int	0	Shared secret only: 0 text (its UTF-8 bytes), 1 Base64.
KeyId	string		Optional kid header, lets validators pick the right key from a JWKS while keys are rotated.
RefreshTokenLifetime	string		Optional, same format as TokenLifetime and longer than it. When set a refresh token is issued too.

Behaviour

• For every input record a token is created with iss, aud, iat, nbf, exp, a unique jti, sub = UserName, email = Email, userId = UserId (left out when empty) and one claim per Claims entry.
• A Claims value written as a JSON array (["admin","editor"]) becomes an array in the token. Entries named iss, sub, aud, exp, nbf, iat, jti or token_use are skipped (a warning is shown once); entries with an empty key are skipped.
• ValidFrom (nbf), ValidTo (exp) and RefreshTokenValidTo are UTC. ValidTo is 0001-01-01 and ExpiresIn 0 when UseLifetime is false.
• The refresh token carries the same claims plus token_use = refresh. A JWT validator with TokenUse Access (the default) rejects it, so it cannot be used as an access token.
• A wrong configuration (missing Issuer, short or unreadable key, invalid lifetime) stops the flow at start.

Notes

• Older versions read TokenLifetime with the .NET time span parser, which takes 24:00:00 as 24 days. Flows saved with that value now issue tokens valid for 24 hours.
• Without UseLifetime tokens never expire; avoid that for user logins.
• Keep SigningKey out of the flow: use an expression setting (=Secrets.JwtKey). With HS* the validator needs the same secret; with RS*/ES*/PS* it needs only the public key, so other services can check tokens without being able to issue them.
• To return the token to the caller, serialize JwtData to JSON and send it with Http response.

Example

{ "UseLifetime": true, "TokenLifetime": "00:15:00", "RefreshTokenLifetime": "7.00:00:00", "Issuer": "my-api", "Audience": "my-clients", "Algorithm": 0, "SigningKey": "=Secrets.JwtKey" }

Login: Http listener → Rest handler (login) → Script (check password, build JwtIssuerUserData) → JWT issuer → Json serializer → Http response

Refresh: Rest handler (refresh) → JWT validator (TokenUse Refresh, token as TextRecord) → Script (JwtClaimsData to JwtIssuerUserData, check the user is still active) → JWT issuer → Json serializer → Http response