JWS Sample | Nuapay Developer Hub

JSON Web Signature Sample

To illustrate how to set up the JWS please view the following samples, which include:

A sample Private Key
A sample Certificate
A JOSE Header generated from the certificate
An example JSON payload
The JWS generated using the above data and RFC 7515 specification

Sample Private Key

Sample Certificate

Attribute	Value
Serial Number	1f23f36a87
Subject (OU)	Nuapay API
Subject (CN)	yboqyay92q
Subject (O)	Nuapay
Subject (L)	London
Subject (C)	GB

Sample JOSE Header

The JOSE Header is generated from the certificate attributes above, note that:

The ‘Serial Number’ is first decoded from hexadecimal to decimal before use in the JOSE header as the kid.
In this example the Serial Number from the certificate (1f23f36a87) is decoded to 133747141255 (and used as the kid value).

{
  "alg": "RS256",
  "kid": "133747141255",
  "iat": 0,
  "iss": "C=GB, L=London, OU=Nuapay API, O=Nuapay, CN=yboqyay92q",
  "b64": false,
  "crit": [
    "iat",
    "iss",
    "b64"
  ]
}

Sample HTTP Request Body

The request body that needs to be signed must be provided to generate the JWS. In this example, an empty request body is provided: {}

Tip: The formatting of your request body is important here. If you have pretty-printed your request body but the request is reformatted later, for example if all CR and LF characters are stripped prior to being processed in Nuapay, for example, then the JWS Signature will be invalid.

Sample JWS Signature

The JWS Signature generated, to RFC 7515 specification, which uses the above certificate, private key, JOSE Header and payload is provided below:

ewogICJhbGciOiAiUlMyNTYiLAogICJraWQiOiAiMTMzNzQ3MTQxMjU1IiwKICAiaWF0IjogMCwKICAiaXNzIjogIkM9R0IsIEw9TG9uZG9uLCBPVT1OdWFwYXkgQVBJLCBPPU51YXBheSwgQ049eWJvcXlheTkycSIsCiAgImI2NCI6IGZhbHNlLAogICJjcml0IjogWwogICAgImlhdCIsCiAgICAiaXNzIiwKICAgICJiNjQiCiAgXQp9..d_cZ46lwNiaFHAu_saC-Zz4rSzNbevWirO94EmBlbOwkB1L78vGbAnNjUsmFSU7t_HhL-cyMiQUDyRWswsEnlDljJsRi8s8ft48ipy2SMuZrjPpyYYMgink8nZZK7l-eFJcTiS9ZWezAAXF_IJFXSTO5ax9z6xty3zTNPNMV9W7aH8fEAvbUIiueOhH5xNHcsuqlOGygKdFz2rbjTGffoE_6zS4Dry-uX5mts2duLorobUimGsdlUcSM6P6vZEtcXaJCdjrT9tuFMh4CkX9nqk19Bq2z3i-SX4JCPvhD2r3ghRmX0gG08UcvyFVbrnVZJnpl4MU8V4Nr3-2M5URZOg

Testing

To test your settings, use the JWS Generator tool below.

Note: This tool will allow you to generate a JWS Signature and should be used for testing.

To use the Generator tool below:

Edit the JWS Header section and update the following:
1. "kid"
2. "iss" (COMMON NAME - CN)
Paste the HTTP request body into the JWS Payload section (JSON). Note that in the sample above an empty payload is used i.e. {}.
Paste the Private Key into the Signing Private Key area.
Click the Generate JWS Signature button.
Use the generated string as a JWS-Signature header value when making your call (passed in the Payload) to the Nuapay Endpoint you referenced in step 2 above.

Generator Tool

Paste the required information as indicated below:

Your certificate serial number (kid)
Your Commone Name (CN)
Your JSON Payload
Your Private Key

Click Generate JWS Signature when you’re done:

For further reference see:

Note:

State is not required when creating your CSR.
If you have provided a value for this when generating your CSR, ensure that you add ST to the iss value in the JWS Header.
So for example: “iss”: “C=GB, L=London, ST = Your State, OU=Nuapay API, O=Nuapay, CN= abcdefg123”

Automating the JWS

The Generator Tool allows you to create a JWS signature value based on your certificate details and private key and is intended for your initial testing.

Use the tool above to generate a JWS for a specific payload (e.g. for a Create Beneficiary request).
Copy the generated JWS and paste that as a header value in your Create Beneficiary call.
Generate your request and confirm that it is successful. Once your JWS is working as expected, you will need to code a solution that takes your certificate and private key to automatically generate a JWS and dynamically add it as a header to any requests that require it.

Troubleshooting

If you are unsuccessful in creating a request with the generated JWS signature, please try the following:

When generating the CSR (If you are using REST to generate your certificate), if you have provided a value for State, ensure that you add ST as an attribute in the iss of the JWS Header.
Ensure that you are using the decoded Serial Number for the kid value (and not the raw hexadecimal value).
The Unix Epoch passed in the iat should be set to the current timestamp. Ensure that this date is not a future timestamp; a valid JWS Signature can be generated if the date is in the past but not if a future timestamp has been applied. (In the Generator above this has been set to zero).
Try to pass your request with an empty payload e.g. {} and check the error code returned. If you receive a HTTP 400 then you will know that your JWS is correct (the 400 is because of the empty payload; you will typically receive a 7085: Beneficiary object is required).
If you have pretty-printed your request body when generating a JWS Signature, try removing any CR or LF characters and retry.
Similarly if your payload was not pretty-printed when generating the JWS Signature, ensure that it is not pretty-printed when calling the endpoint with the JWS Signature header.
Ensure that there is no extra spaces or formatting changes applied to the JWS Header when generating the JWS Signature. (Any superfluous formatting will result in an incorrect JWS being generated).
Use the example private key, certificate, JOSE Header and Sample request above and try passing the values into the Generator tool to confirm that that JWS is generated as expected. Once you have confirmed that the Generator tool is creating the same JWS Signature as described in the sample, replace the kid, CN, payload and Private Key with your own values.

Java Example

For an example of how signatures may be generated in Java, see the following sample on Github:

https://github.com/sentenial/jws-sample-java

Input	JWS Header Edit only "kid" and the CN`of the "iss" * iss must match subject on your cert * kid must match your certificate serial number	{ "alg": "RS256", "kid": "PASTE YOUR SERIAL HERE", "iat": 0, "iss": "C=GB, L=London, OU=Nuapay API, O=Nuapay, CN=PASTE YOUR COMMON NAME HERE", "b64": false, "crit": [ "iat", "iss", "b64" ] }
	JWS Payload Your HTTP request body here	PASTE YOUR JSON PAYLOAD HERE
	Signing Private Key in PKCS#8 format The key never leaves your browser	PASTE YOUR PRIVATE KEY HERE

Output JWS Signature Copy it and use as JWS-Signature header value