Authentication

If an authentication-enabled app has a publish extension, users of the app must authenticate with a third-party platform before they can publish their designs.
This topic explains how to implement authentication in a publish extension.
For guidelines on creating a delightful authentication flow, see Optimizing the authentication flow.
Step 1: Enable authentication
By default, authentication is disabled.
To enable authentication:
1.Navigate to an app via the Developer Portal.
2.Click Authentication.
3.Enable This app requires authentication.
The Authentication page has two fields:
Redirect URL
Authentication base URL
The purpose of these fields is explained in the following steps.
Step 2: Check if the user is authenticated
When a user opens a publish extension, Canva sends a POST request to the following endpoint:
1
<authentication_base_url>/configuration
Copied!
<authentication_base_url> is a placeholder that refers to the app's Authentication base URL field, which can be set via the Authentication page in the Developer Portal.
Canva automatically appends the /configuration path to the URL. Don't include the path in the Authentication base URL field.
The body of this request includes a user property that contains the ID of the user. Your extension can use this ID to check if the current user is associated with a user in the backend of a third-party platform.
If the ID of the Canva user is not associated with a user of the third-party platform, respond to the request with the following object:
1
{
2
  "type": "ERROR",
3
  "errorCode": "CONFIGURATION_REQUIRED"
4
}
Copied!
This tells Canva to render a Connect button. Users can select the button to begin the authentication flow.
The user's ID is obfuscated and unique to each app. If an app has multiple extensions, each extension will receive the same ID for a user, but different apps will receive different IDs for the same user.
If the ID of the Canva user is associated with a user of the third-party platform, respond to the request with the following object:
1
{
2
  "type": "SUCCESS",
3
  "labels": ["PUBLISH"]
4
}
Copied!
This tells Canva to continue loading the publish extension. All subsequent requests that Canva sends to the extension include the user's ID in the request body. The extension can use this ID to:
Show the user their files and folders. (This only applies to extensions using the Flat list or Nested list layout.)
Associate the user's published designs with the correct user in the platform's backend.
Canva includes the ID of the user's team in all requests, via the brand property. You can use this ID to add team-specific features to an extension.
Step 3: Redirect users to the Redirect URL
When a user clicks the Connect button, Canva opens a pop-up window.
Inside this window, Canva redirects the user to the app's Redirect URL.
The Redirect URL must point to a page that lets users authenticate with the third-party platform. For example, this could be a login form with a username and password, or the start of an OAuth 2.0 authorization flow. The exact authentication method is the responsibility of the app. Canva doesn't enforce any specific approach.
When redirecting users to the Redirect URL, Canva automatically appends a number of query parameters to the URL. All of these parameters serve a purpose, but the user and state parameters are of particular importance.
The user parameter contains the ID of the user. If the user successfully authenticates, the app needs to persist this ID to a data store. When the user returns to the app, the app can use this ID to check if the user is authenticated or not.
The state parameter contains a unique token for the authentication flow. For security reasons, the app must return this token to Canva at the end of the authentication flow. This protects the app against cross-site request forgery (CSRF) attacks.
To see the complete list of query parameters, see Redirect URL.
For guidelines on providing a friendly and familiar-looking Redirect URL, see Provide a user-friendly Redirect URL.
Step 4: Redirect the user back to Canva
At the end of the authentication flow, redirect users to the following URL from within the pop-up window:
1
https://canva.com/apps/configured?success=<true|false>&state=<token>
Copied!
This must be a 302 redirect.
You also need to append the following parameters to the URL:
success
state
If the user has successfully authenticated, set the success parameter to true. This tells Canva to close the pop-up window and reload the extension. When the extension reloads, it can once again check if the user is authenticated.
If the user has not successfully authenticated, set the success parameter to false. This tells Canva to close the pop-up window without reloading the extension.
Always set the state parameter to the value of the token that Canva provided at the start of the authentication flow. If the state parameter is missing or invalid, an error occurs and the authentication fails.
Canva's state parameter is distinct from OAuth 2.0's state parameter.
Once a user has authenticated, don't require them to authenticate with any of the app's other extensions. For example, if an app has a content and a publish extension, only require them to navigate through the authentication flow once. In other words, handle authentication on an app-wide basis, not a per-extension basis. This is because users don't distinguish between apps and extensions. As far as they're concerned, they're simply using an app that supports various features.
Step 5: Let users disconnect from Canva
After a user authenticates, they have the option of revoking that authentication. Your app must support this option to be eligible for distribution via the Apps Directory.
When a user disconnects an app, Canva sends a POST request to the following endpoint:
1
<authentication_base_url>/configuration/delete
Copied!
The body of this request includes a user property, which contains the ID of the user. Your app can use this ID to remove the association between the Canva user and the user in the backend of the third-party platform.
When a user disconnects an app, the app must disconnect the user from all of its extensions. This means, if an app has a content and a publish extension, it must disconnect the user from both extensions. (This relates to the earlier point about authentication being app-wide.)
To learn more about this endpoint, see the API reference.
Step 6: Verify request signatures
Before you can submit an app for review, you must implement signature verification for the following endpoints:
Redirect URL
/configuration
/configuration/delete
/publish/resources/find
/publish/resources/get
/publish/resources/upload
This prevents third-parties from sending requests to these URLs.
The redirection from Canva to the Redirect URL is a GET request. To learn how to set up signature verification for a GET request, see Verifying GET requests.
All other requests from Canva are POST requests. To learn how to set up signature verification for a POST request, see Verifying POST requests.
Example
This example uses ESM modules, which means it uses the import keyword instead of the require keyword. To run the example, add 'type': 'module' to the package.json file.
1
import basicAuth from "express-basic-auth";
2
import express from "express";
3
import querystring from "querystring";
4
import fs from "fs-extra";
5
import jimp from "jimp";
6
import path from "path";
7
import url from "url";
8
import { Low, JSONFile } from "lowdb";
9
​
10
const app = express();
11
​
12
app.use(express.json());
13
app.use(express.static("public"));
14
​
15
// Set up the database
16
// Docs: https://github.com/typicode/lowdb
17
const adapter = new JSONFile("db.json");
18
const db = new Low(adapter);
19
await db.read();
20
db.data ||= { loggedInUsers: [] };
21
​
22
// Set up Redirect URL
23
app.get(
24
  "/login",
25
  basicAuth({
26
    users: { admin: "password123" },
27
    challenge: true,
28
  }),
29
  async (request, response) => {
30
    const { loggedInUsers } = db.data;
31
    const { user } = request.query;
32
​
33
    // Add the user to the database
34
    if (!loggedInUsers.includes(user)) {
35
      loggedInUsers.push(user);
36
      await db.write();
37
    }
38
​
39
    // Create query parameters for redirect back to Canva
40
    const params = querystring.stringify({
41
      success: true,
42
      state: request.query.state,
43
    });
44
​
45
    // Redirect back to Canva
46
    response.redirect(302, `https://canva.com/apps/configured?${params}`);
47
  }
48
);
49
​
50
// Handle upload requests
51
app.post("/publish/resources/upload", async (request, response) => {
52
  const { loggedInUsers } = db.data;
53
  const { user } = request.body;
54
​
55
  // The user is logged-in
56
  if (loggedInUsers.includes(user)) {
57
    // Ensure the "public" directory exists
58
    await fs.ensureDir("public");
59
​
60
    // Get the first asset from the "assets" array
61
    const [asset] = request.body.assets;
62
​
63
    // Download the asset
64
    const image = await jimp.read(asset.url);
65
    const filePath = path.join("public", asset.name);
66
    await image.writeAsync(filePath);
67
​
68
    // Respond with the URL of the published design
69
    response.send({
70
      type: "SUCCESS",
71
      url: url.format({
72
        protocol: request.protocol,
73
        host: request.get("host"),
74
        pathname: asset.name,
75
      }),
76
    });
77
    return;
78
  }
79
​
80
  // The user not is logged-in
81
  response.send({
82
    type: "ERROR",
83
    errorCode: "CONFIGURATION_REQUIRED",
84
  });
85
});
86
​
87
// Handle authentication requests
88
app.post("/configuration", async (request, response) => {
89
  const { loggedInUsers } = db.data;
90
  const { user } = request.body;
91
​
92
  // The user is logged-in
93
  if (loggedInUsers.includes(user)) {
94
    response.send({
95
      type: "SUCCESS",
96
      labels: ["PUBLISH"],
97
    });
98
    return;
99
  }
100
​
101
  // The user is not logged-in
102
  response.send({
103
    type: "ERROR",
104
    errorCode: "CONFIGURATION_REQUIRED",
105
  });
106
});
107
​
108
// Handle disconnection requests
109
app.post("/configuration/delete", async (request, response) => {
110
  // Remove the current user from the database
111
  db.data.loggedInUsers = db.data.loggedInUsers.filter((user) => {
112
    return user !== request.body.user;
113
  });
114
  await db.write();
115
​
116
  response.send({
117
    type: "SUCCESS",
118
  });
119
});
120
​
121
app.listen(process.env.PORT || 3000);
Copied!

Messages

Next - Frontend development

Assets

Last modified 1mo ago

Copy link

Contents

Step 1: Enable authentication

Step 2: Check if the user is authenticated

Step 3: Redirect users to the Redirect URL

Step 4: Redirect the user back to Canva

Step 5: Let users disconnect from Canva

Step 6: Verify request signatures

Example