Verifying and Decoding a Signed Request

When using a signed request, Salesforce delivers the user context and authentication information to your canvas app URL. To ensure that the signed request is valid, you must verify that the signed request was signed using your specific canvas app consumer secret. If the correct consumer secret was used, then you can trust the context; otherwise, you can assume that the request was not initiated by Salesforce. To verify and decode the signed request, your application should:

Receive the POST message that contains the initial signed request from Salesforce.
Split the signed request on the first period. The result is two strings: the hashed Based64 context signed with the consumer secret and the Base64 encoded context itself.
Use the HMAC SHA-256 algorithm to hash the Base64 encoded context and sign it using your consumer secret.
Base64 encode the string created in the previous step.
Compare the Base64 encoded string with the hashed Base64 context signed with the consumer secret you received in step 2.

If the two values are the same, then you know that the signed request was signed using your consumer secret and can be trusted. From there, you can Base64 decode the encoded context and parse out any values you need. For more information on those values, see CanvasRequest. If the two strings are different, then the request was not hashed and signed using your consumer secret, and you should return the appropriate message to the user.

Functions for Verifying and Decoding

To verify the signed request, you can call the one the following functions found in the Canvas SDK (in SalesforceCanvasFrameworkSDK\src\main\java\canvas\SignedRequest.java):

verifyAndDecode—Returns a verified and decoded version of the signed request as a Java object.
verifyAndDecodeAsJson—Returns a verified and decoded version of the signed request as a JSON-formatted string.

The following code example shows you how to verify and decode a signed request using the functions in the SDK. This code splits the signed request string at the period to parse out the signed secret and the Base64 JSON string. It then encrypts the canvas app consumer secret signed with the HMAC SHA-256 algorithm and compares the encrypted value with the encrypted value sent to you by Salesforce.

If the two values are the same, you know that the context is valid and came from Salesforce. If the two values are different, then the request didn’t come from Salesforce.

1/**
2*
3* The utility method can be used to validate/verify the signed request. 
4* In this case, the signed request is verified that it's from Salesforce and that 
5* it has not been tampered with.
6* 
7* This utility class has two methods. One verifies and decodes the request
8* as a Java object, the other as a JSON String.
9*
10*/
11public class SignedRequest {
12    public static CanvasRequest verifyAndDecode(String input, String secret) 
13        throws SecurityException {
14        String[] split = getParts(input);
15        String encodedSig = split[0];
16        String encodedEnvelope = split[1];
17
18        // Deserialize the JSON body.
19        String json_envelope = new String(new Base64(true).decode(encodedEnvelope));
20        ObjectMapper mapper = new ObjectMapper();
21        ObjectReader reader = mapper.reader(CanvasRequest.class);
22        CanvasRequest canvasRequest;
23        String algorithm;
24        try {
25            canvasRequest = reader.readValue(json_envelope);
26            algorithm = canvasRequest.getAlgorithm() == null ? 
27                "HMACSHA256" : canvasRequest.getAlgorithm();
28        } catch (IOException e) {
29            throw new SecurityException(String.format("Error [%s] deserializing JSON to 
30                Object [%s]", e.getMessage(), CanvasRequest.class.getName()), e);
31        }
32        verify(secret, algorithm, encodedEnvelope, encodedSig);
33        // If we got this far, then the request was not tampered with.
34        // Return the request as a Java object.
35        return canvasRequest;
36    }
37    public static String verifyAndDecodeAsJson(String input, String secret) 
38        throws SecurityException {
39        String[] split = getParts(input);
40        String encodedSig = split[0];
41        String encodedEnvelope = split[1];
42        String json_envelope = new String(new Base64(true).decode(encodedEnvelope));
43        ObjectMapper mapper = new ObjectMapper();
44        String algorithm;
45        StringWriter writer;
46        TypeReference<HashMap<String,Object>> typeRef
47                = new TypeReference<HashMap<String, Object>>() { };
48        try {
49            HashMap<String,Object> o = mapper.readValue(json_envelope, typeRef);
50            writer = new StringWriter();
51            mapper.writeValue(writer, o);
52            algorithm = (String)o.get("algorithm");
53        } catch (IOException e) {
54            throw new SecurityException(String.format("Error [%s] deserializing 
55                JSON to Object [%s]", e.getMessage(),
56                    typeRef.getClass().getName()), e);
57        }
58        verify(secret, algorithm, encodedEnvelope, encodedSig);
59        // If we got this far, then the request was not tampered with.
60        // Return the request as a JSON string.
61        return writer.toString();
62    }
63
64    private static String[] getParts(String input) {
65        if (input == null || input.indexOf(".") <= 0) {
66            throw new SecurityException(String.format("Input [%s] doesn't 
67                look like a signed request", input));
68        }
69        String[] split = input.split("[.]", 2);
70        return split;
71    }
72
73    private static void verify(String secret, String algorithm, 
74        String encodedEnvelope, String encodedSig ) 
75        throws SecurityException
76    {
77    if (secret == null || secret.trim().length() == 0) {
78            throw new IllegalArgumentException("secret is null, did you 
79                set your environment variable CANVAS_CONSUMER_SECRET?");
80        }
81        SecretKey hmacKey = null;
82        try {
83            byte[] key = secret.getBytes();
84            hmacKey = new SecretKeySpec(key, algorithm);
85            Mac mac = Mac.getInstance(algorithm);
86            mac.init(hmacKey);
87            // Check to see if the body was tampered with.
88            byte[] digest = mac.doFinal(encodedEnvelope.getBytes());
89            byte[] decode_sig = new Base64(true).decode(encodedSig);
90            if (! Arrays.equals(digest, decode_sig)) {
91                String label = "Warning: Request was tampered with";
92                throw new SecurityException(label);
93            }
94        } catch (NoSuchAlgorithmException e) {
95            throw new SecurityException(String.format("Problem with algorithm [%s] 
96                Error [%s]", algorithm, e.getMessage()), e);
97        } catch (InvalidKeyException e) {
98            throw new SecurityException(String.format("Problem with key [%s] 
99            Error [%s]", hmacKey, e.getMessage()), e);
100        }
101        // If we got here and didn't throw a SecurityException then all is good.
102    }
103}

Calling the verifyAndDecode Function

The following code shows an example of getting the signed request, and then verifying and decoding the request by using the verifyAndDecode function.

1// From a JSP or servlet.
2<%@ page import="canvas.SignedRequest" %>
3<%@ page import="java.util.Map" %>
4<%
5    // Pull the signed request out of the request body and verify/decode it.
6    Map<String, String[]> parameters = request.getParameterMap();
7    String[] signedRequest = parameters.get("signed_request");
8    if (signedRequest == null) {%>
9        This app must be invoked via a signed request!<%
10        return;
11    }
12    String yourConsumerSecret=System.getenv("CANVAS_CONSUMER_SECRET");
13    String signedRequest = SignedRequest.verifyAndDecode(signedRequest[0], yourConsumerSecret);
14%>
15...
16// From JavaScript, you can handle the signed request as needed.
17var signedRequest = '<%=signedRequestJson%>';

Calling the verifyAndDecodeAsJson Function

The following code shows an example of getting the signed request, verifying and decoding the request by using the verifyAndDecodeAsJson function, and parsing the returned JSON result.

1// From a JSP or servlet.
2<%@ page import="canvas.SignedRequest" %>
3<%@ page import="java.util.Map" %>
4<%
5    // Pull the signed request out of the request body and verify/decode it.
6    Map<String, String[]> parameters = request.getParameterMap();
7    String[] signedRequest = parameters.get("signed_request");
8    if (signedRequest == null) {%>
9        This App must be invoked via a signed request!<%
10        return;
11    }
12    String yourConsumerSecret=System.getenv("CANVAS_CONSUMER_SECRET");
13    String signedRequestJson = SignedRequest.verifyAndDecodeAsJson(signedRequest[0], yourConsumerSecret);
14%>
15...
16// From JavaScript, you can parse with your favorite JSON library.
17var signedRequest = JSON.parse('<%=signedRequestJson%>');

See Also