OAuth 2.0 Authorization

Canvas supports the OAuth 2.0 web server flow and the OAuth 2.0 user-agent flow.

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

When using OAuth with Canvas, you have two options.

Web server flow—To integrate a Canvas app with the Salesforce API, use the OAuth 2.0 web server flow, which implements the OAuth 2.0 authorization code grant type. With this flow, the server hosting the web app must be able to protect the connected app’s identity, defined by the client ID and client secret. For more information, see OAuth 2.0 Web Server Flow for Web App Integration in Salesforce Help.
User-agent flow—With the OAuth 2.0 user-agent flow, users authorize a Canvas app to access data using an external or embedded browser. This flow uses the OAuth 2.0 implicit grant type. For more information, see OAuth 2.0 User-Agent Flow for Desktop or Mobile App Integration in Salesforce Help.

Regardless of which OAuth flow that you implement, the Canvas app must provide code for initiating the standards-based OAuth flow. OAuth considerations include:

Salesforce performs an HTTP GET when invoking the Canvas app URL.
With the user agent flow, all authorization is performed in the browser, and no server-side code is needed.

For more information about OAuth, see Authorize Apps with OAuth in Salesforce Help.

Existing Connected Apps and OAuth

If you have an existing connected app that uses OAuth authorization and you want to expose that app as a Canvas app, you have two options.

Edit the existing app, and add the Canvas app information to it. Your app can continue to use the same client ID and secret.
Create a new Canvas app, which gets a new client ID and consumer secret. Make sure to update your app with the client ID and secret.
Canvas App User Flow—OAuth

If your canvas app uses OAuth authorization, the user experience varies depending on where the canvas app is located in the user interface and how user access is set.
Initiate OAuth Flow

Start the authorization process in your Canvas app by using OAuth 2.0. If you store or retrieve data, such as an authentication token, from your Canvas app’s local storage in the callback, use window.opener.localStorage instead of window.localStorage.

See Also