A selected third party can add data to a session via the FormsHub interface. The request needs to be authenticated by signing the JWT (JSON Web Token). The data is then placed in content of the request, usually in JSON format.
The following url can be used to add data to a session: http://< hostUrl>/api/Session/SetSessionData, where the hostUrl is the url of FormsHub. The request with signed JWT and data has to be sent to that url.
The certificate validates the signed JWT. Two different types of certificates are needed: certificate with a private key that will be used to sign the JWT, and a public key for its validation.
It is recomended to use the RSA PKCS#1 signature with SHA-256 when signing the JWT since these contain the certificates with valid keys.
The certificate with the public key is saved on the server (in CGG). The certificate with the private key is saved on the client server and is responsible for secure storage.
JWT is used for authorization. The client application creates JWT and signs in using the certificate. The sign in process is created by the RSA PKCS#1 signature with SHA-256. The JWT is then saved into the header of the request in property Authorization.
| Property name | Description |
|---|---|
| sessionID | sessionID of the session that exists between the client and FormsHub. |
| rendererID | The name of the HTML element used for rendering forms. |
| timeStamp | Current time in the following format: yyyy-MM-ddTHH:mm:sszzz |
| hash | SHA256 of data which is sent by the request body (if the data does not exist then the hash is empty). |
Encode JWT:
eyJhbGciOiJSUzI1NiIsImtpZCI6IlF3QUhfY05QcnpuTUdNRnlvbGxlYmluWWZDVSIsInR5cCI6IkpXVCJ9.eyJzZXNzaW9uSUQiOiJzZXNzaW9uSUQtMTIzIiwicmVuZGVyZXJJRCI6InJlbmRlcmVySUQtMTExIiwidGltZVN0YW1wIjoiMjAxOS0wNS0wMlQxMDowOTowNiswMjowMCIsImhhc2giOiJxZ2tjUlRlbndScjcyNHk4dHpZc0lMRkNnc1plMkJMdXEyS1RmWDhaUStBPSJ9.TxtsSV0uSI00p82GSu7-Tk4wpEnY3uM_rI59aXdiA8uxhycSiS04SduSHMBW05MCjn0UFxFwPVhgvztmQtG95xqnqW-wvekTDoTHCDBrxajyqpUsuShJ1NrLXTXCmVByEmvrx97HcCmBZiiHeLdFcKiKEn5Ol_i-m0TAyx6r9PeWUvX1GWQlYM889PjOzdr07HbMNJGlMPaw2r7ewC1Jy0WMhQm1R6HVJVvbS0hcEj3N8lo5X5bXOaHkk5kBoloJzd05E03pKo0hmXTJiYFXWC8OL6BKvdzPwD94wRkKgISdRkXRsyF6j_x073ky6IuNKkL1ybbTrp2eKe9_HUC7oQ
Decode JWT:
header:
{
"alg": "RS256",
"kid": "QwAH_cNPrznMGMFyollebinYfCU",
"typ": "JWT"
}
payload:
{
"sessionID": "sessionID-123",
"rendererID": "rendererID-111",
"timeStamp": "2019-05-02T10:09:06+02:00",
"hash": "qgkcRTenwRr724y8tzYsILFCgsZe2BLuq2KTfX8ZQ+A="
}
The following part of the article introduces a method used for testing and validation of requests. The method is called ValidateRequest and is used for POST requests. The method accepts all requests and also does their validation.
The url for the method is https://< host>/api/Session/ValidateRequest.
The data the user wishes to save into the session have to appear in the body of the request and they have to be in the JSON format. The key is used as the identifier for the value in the session. The values can be read using keys in NDCode in e-Forms.
{
key1 : "value1",
key2 : "value2",
.
.
.
}
The values of the content in E-Forms can be referenced by their keys using a ThisForm.GetSessionData(string Key) method.
The following part of the code creates and sends the request to FormsHub API. The code uses the method ValidationRequest mentioned above to validate the user's request. To add data to a session, a method called SetSessionData ("< host>/api/Session/SetSessionData") has to be used.
using Microsoft.IdentityModel.Tokens;
using System;
using System.Collections.Generic;
using System.IdentityModel.Tokens.Jwt;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Security.Cryptography;
using System.Security.Cryptography.X509Certificates;
using System.Text;
static string ComputeSha256Hash(string rawData)
{
if (rawData.Length == 0) return "";
using (SHA256 sha256Hash = SHA256.Create())
{
byte[] bytes = sha256Hash.ComputeHash(Encoding.UTF8.GetBytes(rawData));
return Convert.ToBase64String(bytes, 0, bytes.Length);
}
}
static void Main(string[] args)
{
var requestData = "{ BootstrapToken : \"Content of BootstrapToken\", MyData:\"My data to session\" }";
var baseUrl = "your-base-formshub-address";
var setSessionDataUrl = "api/Session/SetSessionData";
var validateRequestUrl = "api/Session/ValidateRequest";
var sessionID = "sessionID-123";
var rendererID = "rendererID-111";
var pfxFile = @"path-to-PFX-file";
var pfxPass = "password-to-PFX";
var headerPayload = new Dictionary()
{
{ "sessionID", sessionID },
{ "rendererID", rendererID },
{ "timeStamp", DateTime.Now.ToString("yyyy-MM-ddTHH:mm:sszzz") },
{ "hash", ComputeSha256Hash(requestData) },
};
//---------------JWT--------------------
var signingCert = new X509Certificate2(pfxFile, pfxPass, X509KeyStorageFlags.Exportable | X509KeyStorageFlags.MachineKeySet);
X509SecurityKey privateKey = new X509SecurityKey(signingCert);
var tokenHandler = new JwtSecurityTokenHandler();
var tokenDescriptor = new SecurityTokenDescriptor
{
SigningCredentials = new SigningCredentials(privateKey, SecurityAlgorithms.RsaSha256Signature),
};
JwtSecurityToken stoken = (JwtSecurityToken)tokenHandler.CreateToken(tokenDescriptor);
stoken.Payload.Clear();
foreach (var p in payload) {
stoken.Payload[p.Key] = p.Value;
}
string token = tokenHandler.WriteToken(stoken);
//---------------JWT--------------------
HttpClient client = new HttpClient()
{
BaseAddress = new Uri(baseUrl)
};
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue(token);
var content = new StringContent(requestData, Encoding.UTF8, "application/json");
HttpResponseMessage response = client.PostAsync(validateRequestUrl, content).Result; //------------- validate request
//HttpResponseMessage response = client.PostAsync(setSessionDataUrl, content).Result; //------------ add data to session
string responseContent = response.Content.ReadAsStringAsync().Result;
Console.WriteLine(responseContent);
Console.ReadKey();
}
The following sample uses a method for validation of the request: http://localhost:54039/api/Session/ValidateRequest
If you wisht to use the sample, please change the host address.
{
"info": {
"_postman_id": "16fab9ae-ccd7-450e-9299-d00b6d4778b9",
"name": "FormsHub",
"schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
},
"item": [
{
"name": "api/Session/ValidateRequest",
"request": {
"method": "POST",
"header": [
{
"key": "Authorization",
"value": "eyJhbGciOiJSUzI1NiIsImtpZCI6IlF3QUhfY05QcnpuTUdNRnlvbGxlYmluWWZDVSIsInR5cCI6IkpXVCJ9.eyJzZXNzaW9uSUQiOiJzZXNzaW9uSUQtMTIzIiwicmVuZGVyZXJJRCI6InJlbmRlcmVySUQtMTExIiwidGltZVN0YW1wIjoiMjAxOS0wNS0wMlQxMDowOTowNiswMjowMCIsImhhc2giOiJxZ2tjUlRlbndScjcyNHk4dHpZc0lMRkNnc1plMkJMdXEyS1RmWDhaUStBPSJ9.TxtsSV0uSI00p82GSu7-Tk4wpEnY3uM_rI59aXdiA8uxhycSiS04SduSHMBW05MCjn0UFxFwPVhgvztmQtG95xqnqW-wvekTDoTHCDBrxajyqpUsuShJ1NrLXTXCmVByEmvrx97HcCmBZiiHeLdFcKiKEn5Ol_i-m0TAyx6r9PeWUvX1GWQlYM889PjOzdr07HbMNJGlMPaw2r7ewC1Jy0WMhQm1R6HVJVvbS0hcEj3N8lo5X5bXOaHkk5kBoloJzd05E03pKo0hmXTJiYFXWC8OL6BKvdzPwD94wRkKgISdRkXRsyF6j_x073ky6IuNKkL1ybbTrp2eKe9_HUC7oQ",
"type": "text"
},
{
"key": "Content-Type",
"name": "Content-Type",
"value": "application/json",
"type": "text"
}
],
"body": {
"mode": "raw",
"raw": "{ BootstrapToken : \"Content of BootstrapToken\", MyData:\"My data to session\" }"
},
"url": {
"raw": "http://localhost:54039/api/Session/ValidateRequest",
"protocol": "http",
"host": [
"localhost"
],
"port": "54039",
"path": [
"api",
"Session",
"ValidateRequest"
]
}
},
"response": []
}
]
}