Canvas Developer Guide

Introducing Canvas
Quick Start
Quick Start—Advanced
Canvas SDK
Referencing the Canvas SDK
Authentication
Signed Request Authentication
Canvas App User Flow—Signed Request
Verifying and Decoding a Signed Request
Requesting a Signed Request
OAuth 2.0 Authorization
SAML Single Sign-On for Canvas Apps
Getting Context in Your Canvas App
Cross-Domain XHR
Alternatives to Cookies for User Tracking
Resizing a Canvas App
Implementing Canvas App Events
Using Streaming API in a Canvas App
Debugging in a Canvas App
Using the <select> Tag in a Canvas App
Canvas Apps and Visualforce Pages
Lightning Component Code Examples
Canvas Apps in a Page Layout or a Mobile Card
Canvas Apps in the Publisher
Canvas Apps in the Chatter Feed
Canvas in the Salesforce Mobile App
Customizing Your App Lifecycle
Objects
Canvas Limits
PDF

Signed Request Authentication

Signed request is the default authorization method for Canvas apps. The signed request authorization flow varies depending on whether the administrator gives users access to the Canvas app or if users can self-authorize. You can verify signed request information with a client secret, then use signed requests to customize the app and make subsequent calls to Salesforce.

If your Canvas app URL contains a URL fragment identifier (#), then the hash mark (#) and all characters that follow are stripped from the URL during the authentication flow. To prevent unexpected behavior, avoid using hash marks (#) in a Canvas app URL.

Important

Permitted Users Value Canvas App Accessibility When the User Must Approve the Canvas App
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 approve or deny access. Never
All users can 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
  • The administrator revokes the access token
  • The administrator sets a time limit on the token and that time limit is exceeded

POST or GET Behavior: Admin-Approved Users Are Pre-Authorized

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.

POST or GET Behavior: All Users Can Self-Authorize

If the user previously approved the app and access hasn't expired or been revoked, Salesforce performs a POST to the Canvas app with a signed request payload.

If the user hasn't approved the app, or if access has expired or been revoked, 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 initiates the approve or deny OAuth flow.

_sfdc_canvas_authvalue = user_approval_required

After the OAuth flow is initiated and the user approves the app, the Canvas app calls the repost() method with a parameter of true to retrieve the signed request.

Signed Request Format

The signed request is a string of these elements concatenated.

  • The Canvas app consumer secret encrypted with the HMAC SHA–256 algorithm
  • A period (.)
  • The context and authorization token JSON encoded in Base64

The signed request looks similar to this string, although it can be 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 verifies and decodes the request.
  • After the app is invoked, you can request a signed request on demand by using the SDK.