Prefill Lookups Using Secure Parameters 


In this Article
Related Articles

Overview

You can use secure parameters with our Salesforce and ExactTarget Prefill Connectors in order to more completely ensure the security of your prefilled data.  This feature is currently available for Premier and Enterprise plans.

Enabling secure parameters does require some technical knowledge and familiarity with Apex coding & Visualforce.

Note: We recommend testing with the unsafe query parameter before moving on to the secure parameter.

The Salesforce and ExactTarget Prefill Connectors only allows query-string parameters that are authenticated with a base64-encoded HMAC-SHA256 signature.

If your query requires a dynamic parameter (i.e., a parameter that is not known at setup time, and changes for each respondent), you can pass the desired value to the form by appending the parameter to the URL.  Please note that we do not provide support for dynamically signed secure parameters.

Note that the parameter must be signed to prevent a respondent from arbitrarily changing the parameter and accessing other records in your database.

You can follow these steps to generate the cryptographic signature:


1. Obtain the Shared Secret Key

This key is set on a form-by-form basis, and displayed in the setup screen of the connector. If no key has been set yet, one can be generated automatically by pressing the generate key button. Make note of the value of the secret key, you'll need it to generate the signature.

You should also keep this key safe, as making it public would defeat the purpose of securing your query parameters. If you believe that your secret key has been compromised, you can generate a new one at any time.


2. Generate the Signature

FormAssembly offers a quick tool to generate a signature if the parameters to be signed are already known (click "Manually Sign Data").

However, it's more likely that your parameter values change dynamically, in which case you need to compute the signature automatically using the standard HMAC-SHA256 algorithm and the secret key obtained above. The resulting signature must then be base64- and URL-encoded.  Please note that we do not provide support for dynamically signing secure parameters.

To prepare your data for signature, you must follow this convention:

  • Include all parameters present in the query string, in the order they appear.
  • Include the parameter names and values, but remove the & and = separators.
  • Do not include any other part of the URL, e.g., domain, path, etc.
  • Sign plain text only (not URL-encoded).

Example:

For this query string: param1=value1&m2=value2

The data to sign is: param1value1param2value2

Apex Code Sample for Visualforce:

// encoding this query string: recordid=9876
String data = 'recordid9876' // strip '&' and '=' from string.
Blob mac = Crypto.generateMac('HMacSHA256', Blob.valueOf(data), Blob.valueOf('secret_key'));
String sig = EncodingUtil.urlEncode(EncodingUtil.base64Encode(mac), 'UTF-8');
String url = 'https://tfaforms.com/12345?recordid=9876&signature=' + sig;

Optional Expire Parameter

You can also set your secure prefilling links to expire at a certain point in time by adding an expiration timestamp to the prefilling link. This optional feature helps to improve the security of prefilling by preventing links from being reused if found in a browser history or old email.

When working with an expire parameter, there are two important things to keep in mind: 

1. The expire parameter is optional. If it is set, it must be included in the list of parameters signed with HMAC.

2. The expire value must be a unix timestamp, set in the future. The timestamp indicates when the link should expire. Depending on your use case, it could be within a few minutes, hours or days.

Here's the code sample updated with the timestamp parameter:

// encoding this query string: recordid=9876 
String data = 'recordid9876' // strip '&' and '=' from string. 
// current timestamp 
Integer time = DateTime.now().getTime() / 1000; 
// add 5 minutes (300 seconds) 
time = time + 300; 
// add the expiration parameter. 
data = data+"expire"+String.valueof(time); 
// sign 
Blob mac = Crypto.generateMac('HMacSHA256', Blob.valueOf(data), Blob.valueOf('secret_key')); 
String sig = EncodingUtil.urlEncode(EncodingUtil.base64Encode(mac), 'UTF-8'); 
String url = 'https://tfaforms.com/12345?recordid=9876&signature=' + sig;

3. Append the Parameter(s) and the Signature to the URL

See more on building a prefilling link.

Example:

Let's say your form is hosted at:

https://tfaforms.com/12345

You have the value 9876 you want to send as the parameter acctnum of the record that you want to use to prefill your form. To pass these values to the form, you modify the address like this:

https://tfaforms.com/12345?acctnum=9876

To add the signature, compute its correct value and append it to the URL as the signature parameter.

https://tfaforms.com/12345?acctnum=9876&signature=g%2BRg6RkStnFYysLJKcgaWxhqwYHSJc%2BuY%3D
Note: The example provided above does not include the optional expiry parameter. If using the optional expiry parameter, you will need to append it to your URL.  Please see the screenshot at the end of this article for an example that includes the optional expiry parameter. 

How to Generate a Link Manually

For more information on manually building a prefilling link, please see how to Direct Respondents to a Prefilled Form.

To do this, visit the Data Management page for your form.  This can be accessed on the sidebar (for Enterprise users) or by clicking on the Manually Sign Data link at the bottom of your Prefill Connector. 

In the first field, you will need to enter the data to be signed. This will take the form of the parameters and values you are setting up for your prefilling link.

If you choose to add in an optional expiry parameter, you will also need to enter a numeric value for the expire time and selection the expiration interval in terms of minutes, hours, days, weeks, or months.

After you have completed these steps, click sign and you will be given a signature with an expiration timestamp  (if you chose to use the expiry parameter) which you can append to your prefilling link:

Terms of Service · Privacy Policy