Force.com Canvas Developer's Guide

Clouds with binary code floating aboveCloud with binary code floating above

No Results

Search Tips:

  • Please consider misspellings
  • Try different search keywords
PDF

Newer Version Available

This content describes an older version of this product. View Latest

Signed Request Authentication

This is the default authorization method for canvas apps. The signed request authorization flow varies depending on whether the canvas app’s Permitted Users field is set to "Admin approved users are pre-authorized" or "All users may self-authorize."
Permitted Users Value Canvas App Accessibility When the User Needs to Approve the Canvas App POST or GET Behavior
Admin approved users are pre-authorized The app is accessible to users as soon as the administrator installs it in the organization and configures which users can see it. Users don’t need to approve or deny access. Never Salesforce performs a POST to the canvas app with all the authorization information contained in the body of the signed request, including the refresh token.
All users may self-authorize The app is accessible to all users, but the user is prompted to approve or deny access to the app.
  • The first time that the user opens the app
  • If the access token is revoked by the administrator
  • If the administrator sets a time limit on the token and that time limit is exceeded
 If the user has previously approved the app and the access hasn’t been revoked or expired, Salesforce performs a POST to the canvas app with a signed request payload.
If the user hasn’t approved the app, or if the access has been revoked or expired, Salesforce performs a GET to the canvas app URL. The canvas app must handle the GET by accepting the call and looking for the URL parameter _sfdc_canvas_authvalue. If the canvas app receives this parameter value, the canvas app should initiate the approve or deny OAuth flow.
1_sfdc_canvas_authvalue = user_approval_required

After the OAuth flow is initiated and the user approves the app, the canvas app should call the repost() method with a parameter of true to retrieve the signed request.
The signed request information can be verified with the client secret and used to customize the app, and make subsequent calls to Salesforce.
The signed request is a string of the following elements concatenated:
  • The canvas app consumer secret encrypted with HMAC SHA–256 algorithm
  • A period (“.”)
  • The context and authorization token JSON encoded in Base64
The signed request looks similar to this, although it will be much longer: 9Rpl6rE7R2bSNjoSfYdERk8nffmgtKQNhr5U/5eSJPI=.eyJjb250ZXh0Ijp7InVzZXIiOnsibGFuZ3V....
Signed request considerations:
  • Salesforce performs an HTTP POST or GET when invoking the canvas app URL, depending on the Permitted Users value and whether the refresh token is returned.
  • Server-side code is needed to verify and decode the request.
  • You can request a signed request on demand, after the app is invoked, by using the SDK.