Application Authentication

What this step is for

Teaches Canvas how to sign in to the application on the user's behalf, and how to keep the sign-in alive.

You write two small scripts:

1. The Authentication script says what to send to the application to sign in (the address, the method, the data). Canvas sends the request for you.
2. The Post Handler looks at what came back and saves what you need later, usually the access token.

You can also set up how the sign-in is renewed before it expires (the Token Refresh tab).

Triggered by:

• Application registration (when a user connects the application)
• The Test action on a connected application
• Scheduled token refresh

Choose the sign-in type

The dropdown at the top of the Authentication section:

Type	Use it when	What happens
Direct request	The application signs you in with a request: user name and password, an API key, client ID and secret.	Canvas sends the request that your Authentication script describes.
Callback	The application asks the user to approve access on its own web page ("Allow Canvas to access your account").	The user is sent to the application, approves, and is sent back to Canvas. Everything the application returns is given to your script as configOauth. Your script usually exchanges the returned code for tokens.

The Authentication script

The script describes the request. It does not send it. It must return an object with at least a verb and a baseUrl:

Field	Required	Meaning
verb	Yes	The method: GET, POST, ...
baseUrl	Yes	The address of the application's API, for example https://api.example.com.
requestUrl	No	The path added to the address, for example oauth/token.
headers	No	Extra request headers.
data	No	The body of the request.

Example: sign in with a user name and password.

return {
  verb: 'POST',
  baseUrl: 'https://api.example.com',
  requestUrl: 'oauth/token',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  data: {
    grant_type: 'password',
    username: config.username,
    password: config.password
  }
};

What you can use in the script

Name	What it is
config	The answers the user gave on the Credentials Configuration step: config.username, config.apikey, ... Available only in this step.
configOauth	For Callback: everything the application sent back after the user approved (for example code and state). Available only in this step. Empty for Direct request.
appVault	Your application's settings storage. Anything you save here stays for the next steps. Do not keep secrets here.
appVaultSecret	Your application's secret storage (tokens, passwords, keys). It is stored encrypted.

The Post Handler

It runs right after the application answers. Use it to:

• check that the sign-in worked;
• save the result: the tokens and anything else the next steps need;
• optionally set when the next sign-in should happen (see "Token Refresh").

In the Post Handler you can read the answer in response:

Part of response	Meaning
response.statusCode	The status of the answer, for example 200 for success.
response.content	The data returned by the application (JSON is already converted to an object).
response.headers	The headers of the answer.

Canvas does not decide whether the sign-in was successful. If the application answers with an error, throw an error in your script, otherwise Canvas will treat the sign-in as successful.

Example:

if (response.statusCode == 200 && !!response.content) {
  appVaultSecret.access_token = response.content.access_token;
  appVaultSecret.refresh_token = response.content.refresh_token;
} else {
  throw new Error('Sign-in failed: ' + response.statusCode);
}

Never save secrets (tokens, passwords, API keys) in appVault. appVault can be read from workflow scripts. Always use appVaultSecret for sensitive data.

Token Refresh

Sign-ins usually expire. This tab says when Canvas should sign in again and how.

Trigger refreshing (session expiry)

Option	What it means	What you see on the tab
Never (default)	Canvas never signs in again by itself.	Nothing else.
Fixed interval	Canvas signs in again every N minutes after the last sign-in.	Session timeout (minutes), Use custom refresh script
Sliding date time	Your scripts decide when the next sign-in happens.	Use custom refresh script, and a reminder about utcNextAuth

Fixed interval: enter the number of minutes (1 or more). Pick a value a little shorter than the real token lifetime.

Sliding date time: in the Authentication script or the Post Handler, set the time of the next sign-in in utcNextAuth (a UTC date and time, for example from the token's expires_in):

const d = new Date();
utcLastAuth = d.toISOString();
d.setSeconds(d.getSeconds() + response.content.expires_in - 60);   // one minute before it expires
utcNextAuth = d.toISOString();

If you choose Sliding date time and never set utcNextAuth, Canvas will sign in again every minute.

Use custom refresh script

Setting	What happens at each renewal
Off	Canvas repeats the Authentication script (a full new sign-in).
On	Canvas sends a lighter "renew" request that you describe in the refresh script, for example with the refresh_token.

The refresh script is written like the Authentication script. It describes the request to use for the next renewal: Canvas runs it after every sign-in and every renewal, and uses its result the next time.

return {
  verb: 'POST',
  baseUrl: appVault.baseUrl,
  requestUrl: 'refresh',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  data: {
    grant_type: 'refresh_token',
    refresh_token: appVaultSecret.refresh_token
  }
};

In the refresh script you can use config, configOauth, response (the answer to the last request), appVault, appVaultSecret.

When things run

What happens	What Canvas does
A user connects the application	Authentication script, then sends the request, then the Post Handler, then the refresh script (if you use one).
You or a user press Test, and a renewal request is saved	Sends the saved renewal request, then the Post Handler, then the refresh script to prepare the next renewal.
Test, and nothing is saved	Authentication script, then the request, then the Post Handler.
A scheduled renewal comes due	The same as Test. Canvas checks for due renewals every minute.

When a sign-in or renewal works, the Authorization step runs, so new tokens are used for all following calls.

If a scheduled renewal fails, Canvas tries again. Each failed attempt delays the next one by one more minute: after failure #6 the next attempt is made in 6 minutes. After 12 failed attempts it stops trying automatically. The total wait over 12 failures is 78 minutes (1+2+3+...+12). Press Test to sign in again.

Testing

Use the Test tab to run the step and check the result before you save. If something goes wrong, the message shows which script failed (Authentication, Refresh or Post Handler) and why.

Common problems

Problem	What to check
"Your script doesn't produce a JSON object with obligatory 'verb'/'baseUrl' field(s)"	The script must return an object with verb and baseUrl.
The sign-in "works" but later calls fail	The Post Handler does not check response.statusCode. Add a check and throw an error on failure.
config or configOauth is not defined in a later step	They exist only in this step. Save what you need to appVault or appVaultSecret.
The token is not renewed	Check the Trigger refreshing setting. With Sliding date time, make sure utcNextAuth is set.
The application reconnects every minute	You chose Sliding date time and utcNextAuth is not set.
The first sign-in works but the renewal fails	Check the refresh script: it must return the renewal request, for example with appVaultSecret.refresh_token.

Certificates

If the application requires a client certificate (TLS / mTLS), it is added on the registered application's page, not in this wizard. Canvas then uses it automatically for the requests of this step.