Signature Logic

Signature is used to ensure that the JSON Web Token (JWT) requestor is truly known by the JWT issuer. Since JWTs will grant access to data and behavior representing a specific organization or merchant, this allows for JWTs to only be requested when a value is known by each server.

🚧

Server Side Only

Your signature should never be sent to a client side application. Always execute this logic on your server, where the secret can be encrypted and stored securely.

A JSON Web Token (JWT) contains a lot of information and must be trusted when used. Each of these steps are intended to ensure that the JWT can only be created in a truly trusted manner, protecting against easily decrypted signatures, replay attacks, etc.

Here is a pseudocode summary of the logic used to generate the signature. If you want to double-check your logic, you can use this tool.

1. Random Value

Generate a random string, at least 16 characters, with longer values being encouraged. We suggest 64 characters.
Example: rMC%aeVO$&jH3oM4LkijKsz$MS533SZ7f%qLdHZyrB71!7xRQAq!2si&$nBV!Ypm

2. Current Time

Get the current time in seconds (GMT), which must be within 5 seconds of the current EPOCH.
Example: 1565870400

3. Build Signature Input

Combine your random string, the length of that string, and the timestamp together in a string, with dots separating each value.
Example: rMC%aeVO$&jH3oM4LkijKsz$MS533SZ7f%qLdHZyrB71!7xRQAq!2si&$nBV!Ypm.64.1565870400

4. Create Signature

HMAC 256 encodes the value created using the shared secret (secret key) and output in Base64.
Example: BJY6fZBoq84Fo5JKFoQh6XpeQgeKz1kVz2DrErIp6sU=

📘

I don't know my Secret Key

Your Client ID & Secret Key are provided to you when you are granted access to the Authvia API. If you feel you should have one but do not, please contact us - [email protected]

📘

Gotchas

Make sure your base 64 encoding includes the padding characters (per the spec) or your signature will be considered invalid.

Another thing we've noticed, is machines out of sync with the atomic clock. Make sure your server/local machine is not to far out of sync, or JWTs will never be issuable. You can check your machine's time here

👍

Recipe!

We have a recipe that goes into detail for this object.

Code Examples

const crypto = require('crypto');

// 1. Create random string for value.
const signatureValue = crypto.randomBytes(64).toString('hex');

// 2. Get current timestamp in seconds.
const timestamp = Math.min(Date.now()/1000);

// 3. Assemble
const signatureString = `${signatureValue}.${signatureValue.length}.${timestamp}`;

// 4. Generate HMAC and output Base64
const signature = crypto.createHmac('SHA256','{your_shared_secret}').update(signatureString).digest('base64');

import base64
import hmac
import hashlib
import uuid
import time

# 1. Use GUID for our 'random' string value.
signature_value = uuid.uuid4()

# 2. Get current timestamp in seconds.
timestamp = int(time.time())

# 3. Assemble
signature_string = signature_value + '.' + len(signature_value) + '.' + timestamp

# 4. Generate HMAC and output Base64
digest = hmac.new('{your_shared_secret}', signature_string, hashlib.sha1).digest()
signature = base64.encodestring(digest)

// 1. Use GUID for our 'random' string value.
var signatureValue = Guid.NewGuid();

// 2. Get current timestamp in seconds.
TimeSpan t = DateTime.UtcNow - new DateTime(1970, 1, 1);
int secondsSinceEpoch = (int)t.TotalSeconds; 

// 3. Assemble
var data = signatureValue + "." + signatureValue.Length + "." + secondsSinceEpoch;

// 4. Generate HMAC and output Base64
HMACSHA256 hashObject = new HMACSHA256(Encoding.UTF8.GetBytes("{your_shared_secret}"));
var signatureHmac = hashObject.ComputeHash(Encoding.UTF8.GetBytes(data));
var signature = Convert.ToBase64String(signatureHmac);

// 1. Use GUID for our 'random' string value.
String signatureValue = generateRandomString(32);

// 2. Get current timestamp in seconds.
BigDecimal timeInMille = new BigDecimal(System.currentTimeMillis());
BigDecimal timeInSeconds = timeInMille.divide(new BigDecimal(1000));

// 3. Assemble
String signatureString = signatureValue + '.' + signatureValue.trim().length() + '.' + timeInSeconds.toPlainString();

// 4. Generate HMAC and output Base64
Mac sha256_HMAC = Mac.getInstance("HmacSHA256");
SecretKeySpec secret_key = new SecretKeySpec({your_shared_secret}.getBytes(), "HmacSHA256");
sha256_HMAC.init(secret_key);

byte[] hashBytes = sha256_HMAC.doFinal(signatureString.getBytes());
String signatureEncodedFromBytes = Base64.getEncoder().encodeToString(hashBytes);

// 
// Do not use this code in a browser, it will leak your secret key.
// See the Node.js example for a server side solution.
//

Still having issues? Try our recipe HERE

Scopes

📘

What are my scopes?

The list of scopes available to you depends on your account with Authvia. You will receive the scopes you have when you get API access. Think you need more scopes? Let us know!

The JSON Web Token (JWT) must contain the correct permissions for the call to be authorized and executed successfully. Permissions are defined in the scope claim of the JWT, which is granted during the creation of the JWT by the JWT issuer. You will only be granted a scope for the application requesting the JWT. It's best practice to only ask for what is needed principle of least privilege. So, when creating your JWT, specify a scope that limits the JWT abilities to the specific use case it is intended for.

Within each endpoint, we will document what scope must be granted on the JWT to be granted access to that API call. If you have trouble figuring out what scopes are necessary or available to you, please contact us.

📘

JWT Spec

RFC-7519