Custom JWT Tokens

Therefore™ supports declarations of custom JWT Token issuers. By using this features a customer can create and send JWT Tokens to Therefore™ for user authentication.

Therefore™ supports HS256 and RS256 signed JWT Tokens.

For HS256 a shared key must be saved to Therefore™ to allow validating the token on connection
For RS256 the public key of the certificate used to sign the token must be uploaded as a .cer file to Therefore™

Configuration in the Therefore™ Solution Designer

Right-click 'Custom JWT Token' and select 'Manage'.

Click 'Add' to enter a new row. The following information needs to be populated in the respective fields:

Field	Description
Issuer ID	Match the Issuer ID in the jwt token sent to Therefore™
Name	Optional name for the JWT token
Active	Enable or Disable a customer issuer
Secret/Certificate	Define a shared key or upload a .cer file for validation of the token

Configure usage of Azure Key Vault for shared secrets

If secrets should be saved to Azure Key Vault, the following registry keys must be defined:

HEKY_LOCAL_MACHINE\Software\Therefore\Server - KeyVaultAppId - KeyVaultAppSec - KeyVaultBaseUri

This key must be added as a shared key to the new custom issuer so it can be validated.
The minimal length for the pre-shared key is 32 characters

Copy

Custom JWT Token Payload

{

  "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name": "Test AD",

  "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress": "testad@therefore.net",

  "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname": "ADOS\\testad",

  "aud": "<CustomerId>",

  "nbf": 1547106872,

  "exp": 1547108072,

  "urn:oauth:scope": "therefore_user"

  "iss": https://testissuer.therefore.net

}

Token Parameters	Explanation
aud	The Customer ID of the Therefore™ System
iss	The Issuer ID for the JWT token. This value must match the one used in the Therefore™ Configuration.
urn:oauth:scope	The scope of the token. The possible values are 'therefore_user' for all permissions or 'therefore_read' for read-only access

Custom JWT Tokens can be used to authenticate users of Therefore™ in the Therefore™ Web Client, Portal, API, and WebAPI.

For security reasons JWT/OAuth Tokens must only be used with SSL (https://)
Therefore™ Web Client, Portal: add a new query parameter ssoToken=<token> to any initial request to the Web Client or Portal.

Copy

Example API

string sToken = "<token>;
string sNodeInternal, sNodeFriendly;
TheServer s = new TheServer();
s.ConnectBearerToken(TheClientType.CustomApplication, sToken, "", "", "", true, TheConnectMode.NoLicenseMove, out sNodeInternal, out sNodeFriendly);

Special permissions can be defined for a token.

Permissions for JWT Tokens