Thereforeâ„¢ Help

JSON Web Token (JWT) is an open standard (RFC 7519) that defines a compact and self-contained way for securely transmitting information between parties as a JSON object. This information can be verified and trusted because it is digitally signed. JWTs can be signed using a ‘secret’ (with the HMAC algorithm) or a public/private key pair using RSA or ECDSA.

Although JWTs can be encrypted to provide secrecy between parties, we will focus on signed tokens. Signed tokens can verify the integrity of the claims contained within it, while encrypted tokens hide those claims from other parties. When tokens are signed using public/private key pairs, the signature also certifies that only the party holding the private key is the one that signed it.

To enable integrating Thereforeâ„¢ into a customer provided authentication infrastructure, Thereforeâ„¢ supports declaration 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 save to Thereforeâ„¢ to allow Therefore to validate 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â„¢.

Use Case:

The customer already has an authentication infrastructure or wants the Thereforeâ„¢ Portal to be integrated with their own portal. If a user is already authenticated in the customer portal, it should not be required to authenticate again for Thereforeâ„¢, hence having a SSO experience in between different applications. The customer portal application can then create such a custom token and use this to automatically log the user into Thereforeâ„¢ with the provided user account. No additional login required.

1.Configuration in the Thereforeâ„¢ Solution Designer:

 The following information needs to be populated in the respective fields:

 Issuer Id: must match the Issuer Id in the jwt token sent to Thereforeâ„¢.

 Name: Any name can be given to the UI (only). This is optional.

 Active: Enable or Disable a customer issuer.

 Secret/Certificate: Define a shared key or upload a .cer file for validation of the token.

2.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

 

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

}

 

aud = CustomerId of the Therefore System

iss = Issuer Id – must match Therefore Configuration

urn:oauth:scope = scope of the token - values "therefore_user" (all user permissions) or "therefore_read" (read only)

3.Custom JWT Tokens can be used to authenticate users of Thereforeâ„¢ in Web Client, Portal, API, WebAPI.

Example (Web Client):

https://<server>/TWA/Client/Web/Viewer/Viewer.aspx?docno=349738&ssoToken=<token>

https://<server>/TWA/Portal/Portal.aspx?qNo=123&ssoToken=<token>

Example API:

string sToken = "<token>;

string sNodeInternal, sNodeFriendly;

TheServer s = new TheServer();

s.ConnectBearerToken(TheClientType.CustomApplication, sToken, "", "", "", true, TheConnectMode.NoLicenseMove, out sNodeInternal, out sNodeFriendly);

4.Special permissions can be defined for a token. Reference: Permissions for JWT tokens.

Test Walkthrough:

1.Create Test Tokens here: https://jwtbuilder.jamiekurtz.com/

2.Configure the issuer in Thereforeâ„¢ Solution Designer.

3.Use the token with any access option described above (Web Client, Portal, API, Web API).