When you use a signed request for authentication in your canvas app, you receive a CanvasRequest object in the initial POST message from Desk.com. This object contains fields related to the request, and also contains the Context and Client objects. The CanvasRequest object is returned in JSON format and contains the following fields.
The signed request is a string of the following elements concatenated:
- The hash generated as a result of signing the context with the Canvas app consumer secret, using the HMAC SHA–256 algorithm
- A period (“.”)
- The context JSON encoded in Base64
The signed request looks similar to this, although it will be much longer:
Signed request considerations:
- Desk.com performs an HTTP POST with the signed request as the body when invoking the canvas app URL.
- Server-side code is needed to verify and decode the request.
- Client-side code can be used to decode the request, but for security reasons, should not be used to verify it.
Verifying and Decoding a Signed Request
When using a signed request, Desk.com 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 Desk.com. To verify and decode the signed request, your application should:
- Receive the POST message that contains the initial signed request from Desk.com.
- 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, refer to the Example CanvasRequest Object section below. 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 to notify them that the request could not be verified.
Example CanvasRequest Object
The following code snippet shows an example of the CanvasRequest object.
"currentTime": "Mon, 05 Jan 2015 10:26:14 -0800",
"expiresAt": "Mon, 05 Jan 2015 10:27:14 -0800",
"fullName": "Joe Agent",
"timeZone": "Pacific Time (US & Canada)",
"name": "Canvas Demo",
"name": "My Amazing Company"
"name": "Acme Inc."
currentTime: The timestamp when this context object was generated (used to prevent replay attacks). The timestamp reflects the current time to ensure that the request is not being replayed on your canvas application to gain unauthorized access.
expiresAt: The timestamp when this context object should be considered expired. As a best practice, we recommend checking that the context object has not expired at the moment your application receives it.
algorithm: The algorithm used to sign the request. "HMACSHA256" is currently the only valid value.
userId: The context user's ID.
The Client object is a JSON-formatted object returned by the signed request in the CanvasRequest object. It contains context information about the client app.
instanceUrl: The URL of the Desk.com instance. For example, http://support.desk.com. Used to preface the URLs
returned by the Links object.
oauthToken: This field is currently not used and only retained with a placeholder value to improve compatibility with existing Desk.com Canvas applications.
targetOrigin: The URL of the canvas app. Used internally for cross-domain communication between the page and the iFrame that contains the canvas app.
The Context object provides information to your app about how and by whom it’s being consumed. You can use this information to make subsequent calls for information and code your app so that it appears completely integrated with the Desk.com agent interface. This object is returned in JSON format and contains the following objects:
The User object is a JSON-formatted object containing context information about the current user, such as locale, name, user ID, email, and so on. This information can be used within the canvas app (for example, to display the user’s name) or to make subsequent calls to retrieve additional information.
userId: The ID associated with the current user.
userName: The context user's login username.
email: The context user's email address.
fullName: The context user's full name.
language: The context user’s language. String is 2-5 characters long. The first two characters are always an ISO language code, for example “fr” or “en.” If the value is further qualified by country, then the string also has an underscore (_) and another ISO country code, for example “us” or “uk.” For example, the string for the United States is “en_us,” and the string for French Canadian is “fr_ca.”
locale: The context user's locale.
timeZone: The context user’s time zone.
roleId: The ID of the context user’s currently assigned role.
profileThumbnailUrl: The URL for a thumbnail of the context user’s profile photo taken from Gravatar. If the user does not have a profile picture set up on Gravatar, this link will return a generic thumbnail.
userType: The type of user license assigned to the profile associated with the context user.
The Links object is a JSON-formatted object containing URLs that can be helpful when integrating your canvas app. For example, you can make a GET request to the
userUrl to get more information about the current user.
restUrl: URL to return a list of REST API resources.
userUrl: URL for the context user.
The Application object contains canvas app information collected when the application was added as an Integration Url in the Desk.com Admin, such as the Canva url and the assigned Id.
name: The name of the canvas app.
canvasUrl: The URL of the canvas app.
applicationId: The ID of the canvas app.
authType: The access method of the canvas app. "SIGNED_REQUEST" is currently the only valid value.
The Organization object is a JSON-formatted object containing context information about the organization in which the canvas app is running.
organizationId: The ID of the context organization/site.
name: The name of the context organization.
The Environment object is a JSON-formatted object containing context information about the canvas app environment. This object contains the dimensions object, the record object, and the displayLocation object.
locationUrl: The URL of the page in Desk.com where the user is accessing the canvas app. For example, if users access your canvas app by navigating to a case, this field contains the URL of that case.
displayLocation: The location in the application where the canvas app is currently being called from. Valid values are:
- CaseLayout - The canvas app was called as part of a custom field on the case details pane.
- CustomerLayout - The canvas app was called as part of a custom field on the customer detail pane.
- CompanyLayout - The canvas app was called as part of a custom field on the company detail pane.
- CaseInteraction - The canvas app was called as a component of a case interaction.
- ApplicationLevel - The canvas app was called as a persistent component of Desk.com that is accessible application-wide.
width: The width of the iFrame in pixels.
height: The height of the iFrame in pixels.
maxWidth: The maximum width of the iFrame in pixels.
maxHeight: The maximum height of the iFrame in pixels.
clientWidth: The values of clientWidth are sent to the canvas app within SignedRequest and can be used to set the width of the outermost div element. The field can be referenced as
clientHeight: The values of clientHeight are sent to the canvas app within SignedRequest and can be used to set the height of the outermost div element. The field can be referenced as
id: The ID of the current case (if applicable).
url: The URL of the associated case. The format of the URL is the same as the REST API resource for the given case.
channelType: The Channel of the case (e.g., chat, twitter, email, qna, facebook, phone).
id: The ID of the current customer (if applicable).
url: The URL of the associated customer. The format of the URL is the same as the REST API resource for the given customer.
firstName: The customer's first name.
lastName: The customer's last name.
emailAddresses: Array of email objects, each specifying the contact type and value of the email address.
phoneNumbers: Array of phone number objects, each specifying the contact type and value of the phone number.
twitterHandle: The customer's Twitter handle (including the preceding @ symbol).
id: The ID of the current company (if applicable).
url: The URL of the associated company. The format of the URL is the same as the REST API resource for the given company.
name: The name of the company.