Application Re-Authentication

What this step is for

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

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

Triggered by:

• Manual re-authentication: the Test action on a connected application.

• Scheduled re-authentication.

After every successful renewal Canvas also runs the Authorization script, so the new tokens are used straight away.

What you see on the page

The Configuration tab:

Control	When it is shown	What it does
Trigger refreshing (session expiry)	Always	Never, Fixed interval or Sliding date time. See below.
Session timeout (minutes)	Fixed interval only	The number of minutes between the sign-ins.
Use custom refresh script	Fixed interval or Sliding date time	Off: the Authentication script is repeated. On: the refresh script is used.
Label "Re-authentication will be processed by Authentication script, but you can customize it"	Use custom refresh script is off	Reminds you what happens when no custom script is set.
JS script editor	Use custom refresh script is on	The refresh script.

The Test tab shows the generated test script (read only) and the right side of the page shows the Preview. See Testing.

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

Never: no scheduled re-authentication. A manual re-authentication (Test on the connected application) repeats the Authentication script and keeps the existing appVault and appVaultSecret values.

Fixed interval: enter the number of minutes (1 or more). Pick a value a little shorter than the real token lifetime. Canvas sets the time of the next sign-in itself: the time of the last sign-in plus this number of minutes.

Sliding date time: your refresh script sets the time of the next sign-in in utcNextAuth (UTC date and time in ISO format), for example from the token's expires_in, using the answer that api.send returned (see the example below):

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 signs in again every minute.

Assign utcLastAuth and utcNextAuth directly, do not declare them again with let or const. Both are ISO strings, or null when there has been no sign-in yet.

Use custom refresh script

Setting	What happens at each renewal
Off	Canvas repeats the Authentication script (a full new sign-in), keeping the existing appVault and appVaultSecret values. Write the Authentication script so that it also works when the vaults already have values.
On	Canvas runs your refresh script, for example to use the refresh_token instead of asking for the password again.

What you can use in the refresh script

Name	Meaning
appVault, appVaultSecret	The vaults with the values saved by the previous sign-in and by the Context questions. Read and write them. Secrets only in appVaultSecret.
utcLastAuth, utcNextAuth	The time of the last sign-in and of the next one (ISO strings or null). Assign them to change the schedule.
api	The api.send helper to call the application.

If the refresh needs something that the user entered when connecting the application (for example a client ID) or something from the sign-in, save it to appVault (or appVaultSecret for secrets) in the Authentication step and read it here.

The refresh script has no response variable: the answer of the application is what api.send returns to you, so name your own variable (as in the example below).

Canvas takes the changed appVault, appVaultSecret, utcLastAuth and utcNextAuth after the script and keeps them for the next time. The vaults are saved only when the script finishes without an error.

Calling the application with api.send

The script calls the application with await api.send(...), checks the answer and saves the new tokens. It returns nothing. This is exactly what the Preview of this step runs.

const response = await api.send({
  verb: 'POST',
  baseUrl: appVault.baseUrl,
  requestUrl: 'refresh',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  data: new URLSearchParams({
    grant_type: 'refresh_token',
    refresh_token: appVaultSecret.refresh_token
  }).toString(),
  getFullResponse: true
});

if (response.statusCode == 200 && !!response.content) {
  appVaultSecret.access_token = response.content.access_token;
  appVaultSecret.refresh_token = response.content.refresh_token;

  // Sliding date time: schedule the next renewal one minute before the token expires
  const next = new Date();
  next.setSeconds(next.getSeconds() + response.content.expires_in - 60);
  utcLastAuth = new Date().toISOString();
  utcNextAuth = next.toISOString();
} else {
  throw new Error('Refresh failed: ' + response.statusCode);
}

Always use getFullResponse: true and check the status, as api.send does not throw on an error answer. See api.send.

An error in the refresh script is reported as [JS_REFRESH_ERROR] ....

When things run

What happens	What Canvas does
User presses Test on a registered application	Renewal: the refresh script if there is one, otherwise the Authentication script. Then the Authorization script.
Canvas checks for due renewals about every minute	Looks for connected applications with Fixed interval or Sliding date time whose next sign-in time (utcNextAuth) has passed, and renews them in the same way.

When the renewal works, the new tokens are saved to appVault and appVaultSecret and are used for all following calls.

If a scheduled renewal fails, the application is marked as failed and the failure is counted. Canvas tries again on the following checks. After 12 failed attempts it stops trying automatically. Press Test on the connected application to sign in again; after a successful sign-in the counter is reset.

Testing

Test tab. A read-only editor with the script that the wizard runs. So the script is tested exactly as it is, with the vaults that the previous steps produced. The test runs in your browser.

Preview (right panel). It works as on the Authorization step:

Situation	What you see
The application has not been authenticated in the wizard yet	A message that you must complete authentication first, with a button that takes you to Step 3. Authentication.
The context questions are not completed	A message that you must complete the context configuration first, with a button that takes you to Step 4. Context configuration.
Everything is ready	The current appVault and appVaultSecret and the button Preview Re-Authentication.

Press Preview Re-Authentication to run the refresh script. The Preview then shows the appVault and appVaultSecret that the script returns, so you can check that the new tokens are saved in the right place.

When Use custom refresh script is off there is no script on this step: test the Authentication script on Step 3.