Prefill Lookups Using Secure Parameters 


In this Article
Related Articles

Overview

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


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


Secure prefilling is done by adding a "signature" to the end of your prefilled link. If you would like to learn more about prefilled links, you can check out this help document. You create this signature in one of two ways:

  1. You can create a signature inside your Salesforce Prefill Connector and manually add it to your prefilled link. 
  2. You can dynamically create the signature inside of Salesforce and then add it onto the prefilled link using Apex code. 

The first option can be done entirely inside of FormAssembly without any custom code. However, you can only sign a single set of search values with this method. This means that your prefilled link would not be able to change based on the respondent. 

If you would like your prefilled link to be able to change for each respondent, you will need to dynamically create the signature with the second option inside of Salesforce. This does require some technical knowledge and familiarity with custom Apex coding & Visualforce, and our Support Team is unable to assist with writing and editing custom code. 


Requirements

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

Static (unchanging) Secure Parameters

As we noted above, you do have an option if you'd like to use secure parameters but do not know custom code. If your prefilled link is going to remain the same for every respondent, this is a great option!

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").

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

3. Add an Optional Expiry 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.

4. Click "Sign"

5. Retrieve the Prefilled Link

You will now see a "Result" section appear. This section will contain your newly generated prefilled link. You can use this link to prefill your form with the parameters and values that you have signed. This way, your respondents won't be able to change the values or parameters to try and prefill the form differently. Only these parameters and values will work with this signature. 


Dynamic Secure Parameters

While static parameters are useful when you're sending out one link to all of your respondents, it's more likely that your parameter values change dynamically. In this case, you need to compute the signature automatically using the standard HMAC-SHA256 algorithm and the secret key obtained from your connector. The resulting signature must then be base64- and URL-encoded.  

Please note that we do not provide support for dynamically signing secure parameters.

This process must be done inside of Salesforce. For example, you could use Apex code and VisualForce pages to open a prefilled link with secure parameters when a button is clicked on a record. You could also send out emails using a process in Salesforce which would then utilize Apex code to create a prefilled link with secure parameters and add it to the email. 

Because this needs to occur inside of Salesforce, and every single instance of Salesforce is different, we're not able to provide examples for every single use case. Instead, we've provided some basic Apex code to get started with below.


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;


Apex Code Sample with Optional Expire Parameter

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.

// 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;


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 1: 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.  

Note 2: It is not possible to prefill by simply referencing the signature. The prefilled link must also include the parameter(s) -- "acctnum" in the example above. Without the parameter(s), prefilling will not be successful.



Terms of Service · Privacy Policy