Use a Connected App

Creating the canvas app as a connected app is no longer recommended. Use external client apps for all new Canvas integrations.

note: In Spring ’26, the ability to create new connected apps is disabled by default. To enable creation of new connected apps, contact Salesforce Customer Support. We recommend using an external client app instead for all new Canvas integrations.

In Salesforce, from Setup, enter Apps in the Quick Find box, then select App Manager.
Click New Connected App.
In the Connected App Name field, enter Hello World.
Accept the default API Name of Hello_World. This is the internal name of the canvas app and can’t be changed after you save it.
In the Contact Email field, enter your email address.
In the Logo Image URL field, enter https://localhost:8443/images/salesforce.png. This is the default Salesforce “No Software” image. This image appears on the installation screen and on the detail screen for the app.
In the Icon URL field, enter https://localhost:8443/examples/hello-world/logo.png. This is the default Salesforce “No Software” image.

This is the image that appears next to the app name in the user interface. If you leave this field blank, a default cloud image appears next to the app name.
In the API (Enable OAuth Settings) section, select the Enable OAuth Settings field.
In the Callback URL field, enter https://localhost:8443/sdk/callback.html.
In the Selected OAuth Scopes field, select Access the identity URL service (id, profile, email, address, phone).
In the Canvas App Settings section, select Canvas.
In the Canvas App URL field, enter https://localhost:8443/examples/hello-world/index.jsp.
In the Access Method field, select Signed Request (Post).
In the Locations field, select Chatter Tab.
Save the app, then click Continue.

After the canvas app is saved, the detail page appears.
On the detail page for the canvas app, click Manage Consumer Details, and then verify your identity.
Select the consumer secret value and press Ctrl+c (Windows) to copy it. The consumer secret is used in the app to authenticate.
Go to the command window and stop the Jetty Web server by pressing Ctrl+c (Windows). At the prompt, enter Y.

Create an environment variable named CANVAS_CONSUMER_SECRET and set that value to the consumer secret you just copied. To do this in Windows, in the command window, enter set CANVAS_CONSUMER_SECRET=value_you_just_copied.

If you’re using Unix/OS X, set the environment variable with the command export CANVAS_CONSUMER_SECRET=value_you_just_copied.

The “hello world” page (c:\SalesforceCanvasFrameworkSDK\src\main\webapp\examples\hello-world\index.jsp) uses the consumer secret, as shown in the following code:

<%@ page import="canvas.SignedRequest" %>
<%@ page import="java.util.Map" %>
<%
    // Pull the signed request out of the request body and verify and decode it.
    Map<String, String[]> parameters = request.getParameterMap();
    String[] signedRequest = parameters.get("signed_request");
    if (signedRequest == null) {%>
        This app must be invoked via a signed request!<%
        return;
    }
    String yourConsumerSecret=System.getenv("CANVAS_CONSUMER_SECRET");
    String signedRequestJson = SignedRequest.verifyAndDecodeAsJson(signedRequest[0], yourConsumerSecret);
%>

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en">
<head>

    <title>Hello World Canvas Example</title>

    <link rel="stylesheet" type="text/css" href="/sdk/css/connect.css" />

    <script type="text/javascript" src="/sdk/js/canvas-all.js"></script>

    <!-- Third part libraries, substitute with your own -->
    <script type="text/javascript" src="/scripts/json2.js"></script>

    <script>
        if (self === top) {
            // Not in an iFrame.
            alert("This canvas app must be included within an iFrame");
        }

        Sfdc.canvas(function() {
            var sr = JSON.parse('<%=signedRequestJson%>');
            Sfdc.canvas.byId('username').innerHTML = sr.context.user.fullName;
        });

    </script>
</head>
<body>
    <br/>
    <h1>Hello <span id='username'></span></h1>
</body>
</html>

Restart the Web server by entering this command: target\bin\webapp.bat (Windows) or sh target/bin/webapp (Unix/OS X).

See Also