Created
December 2, 2019 11:05
-
-
Save Tanver-Hasan/c0bf7fa63c9dadcb9f8220e1bed3b4a1 to your computer and use it in GitHub Desktop.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Auth0 Node 4 to 8 migration guide |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
title: "Migration Guide: Extensibility and Node 8"
description: This article covers the Auth0 features/modules affected, as well as our recommendations to ensure a smooth migration process.
toc: true
topics:
contentType:
useCase:
Migration Guide: Extensibility and Node 8
On April 30, 2018, Node.js v4 went out of long-term support (LTS), which means that the Node.js development team no longer back-ports critical security fixes to this version. This could expose your extensibility code to security vulnerabilities.
As such, Auth0 is migrating from Node 4 to Node 8.
We will be ending support for the Node 4 runtime on June 30, 2019. Tenants which have not already migrated to Node 8 will be migrated automatically. Automatic migrations will begin on April 29, 2019, and continue through June 30, 2019. Automatic migrations are happening in cohorts:
Customers will be notified two weeks in advance of their automatic migration date, with additional periodic reminders leading up to their automatic migration date.
::: warning
All tenant automatic upgrades to Node 8 will be completed no later than June 30, 2019. Most tenant upgrades will be completed before this date. Admins for affected tenants will be notified of their exact migration date.
:::
In this document, we:
Summary of the migration
The Webtask runtime powering the following Auth0 features utilize Node 4:
If you do not use any of the extensibility features mentioned above, you are not affected by this migration. Additionally, your tenant will automatically be upgraded to use the Node 8 runtime by June 30, 2019. This will ensure that any future extensibility code you author will be running on a secure runtime.
As part of this migration, the Auth0 development team has performed extensive testing to detect any breaking changes proactively. However, there may be behavioral changes as a result of this migration. As such, we have provided a migration switch that allows you to control the migration of your environment to the new Webtask runtime using Node 8.
::: note
Private Cloud and Managed Private Cloud (PSaaS) customers have had their tenants migrated already. No further action is necessary.
:::
Important Dates
Migration Assistant
We have created a migration assistant to help ease the copying of code between production and development tenants.
Please be sure to test each script individually with its associated Try button. You may, however, test all rules simultaneously with the Try All Rules With button.
In addition, test logging in using the development tenant to ensure that all of the items that you have set up work as expected.
How to enable the Node 8 runtime
Node 8 can be enabled through the new Extensibility panel on the Advanced Tenant Settings page of the Dashboard.
::: warning
Changing the runtime may break your existing Rules, Hooks, and Custom Database/Social Connections. We recommend that you first switch your development tenant to the Node 8 runtime, test your setup, and switch your production tenant only when you have identified there are no breaking changes.
:::
Whitelist the new URLs
The Authorization Extension, the Delegated Administration Extension and the Single Sign-on (SSO) Dashboard Extension require whitelisting the URLs used to access extensions and custom webtasks. When you upgrade to Node 8, the URLs you use to access extensions and custom webtasks will change. This is a breaking change for these extensions.
If you use any of these extensions, you must whitelist the new URLs both as Allowed Callback and as Allowed Logout URLs.
The change is an
8that is appended before thewebtask.iopart. So if you accessed an extension using the URLhttps://${account.tenant}.us.webtask.io/dummy-extension-url, when you upgrade to Node 8 the URL will behttps://${account.tenant}.us8.webtask.io/dummy-extension-url.To do so, go to Dashboard > Applications > Settings, and add the URL to the fields Allowed Callback URLs and Allowed Logout URLs.
The execution URLs will also change for custom webtasks in your Auth0 container. You must update any external applications that call those webtasks.
Authorization Extension Changes
If you use the Authorization Extension, it generates an
auth0-authorization-extensionrule. Republishing this rule from within the Authorization Extension will update the URLs automatically.To ensure a clean upgrade:
Delegated Administration URLs
If you use the Delegated Administration Extension, the matrix that follows contains the updated URLs you must configure after you migrate to Node 8. The URL varies based on your location.
https://${account.tenant}.us8.webtask.io/auth0-delegated-admin/loginhttps://${account.tenant}.us8.webtask.io/auth0-delegated-adminhttps://${account.tenant}.eu8.webtask.io/auth0-delegated-admin/loginhttps://${account.tenant}.eu8.webtask.io/auth0-delegated-adminhttps://${account.tenant}.au8.webtask.io/auth0-delegated-admin/loginhttps://${account.tenant}.au8.webtask.io/auth0-delegated-adminhttps://${account.tenant}.us8.webtask.io/auth0-delegated-admin/loginhttps://${account.tenant}.us8.webtask.io/auth0-delegated-adminSSO Dashboard URLs
The matrix that follows contains the updated URLs you must configure after you migrate to Node 8. The URL varies based on your location.
The login URL for Admins:
https://${account.tenant}.us8.webtask.io/auth0-sso-dashboard/admins/loginhttps://${account.tenant}.eu8.webtask.io/auth0-sso-dashboard/admins/loginhttps://${account.tenant}.au8.webtask.io/auth0-sso-dashboard/admins/loginhttps://${account.tenant}.us8.webtask.io/auth0-sso-dashboard/loginhttps://${account.tenant}.eu8.webtask.io/auth0-sso-dashboard/loginhttps://${account.tenant}.au8.webtask.io/auth0-sso-dashboard/loginAll Extensions
Most extensions use the
PUBLIC_WT_URLhidden secret for authorization. This secret depends on the runtime version and does not update automatically.To update it, you need to save the extension's settings (no changes are necessary). To do so, after switching the runtime to
Node 8, you need to open the extension's settings in the extensions dashboard (gear icon) and hitSave. After that, the extensions gallery will update thePUBLIC_WT_URLsecret accordingly based on the selected runtime.How to ensure a stable migration
As part of the process of introducing Node 8 in our Webtask runtime, we ran a number of tests to determine which modules are not forward-compatible from Node 4 to 8. Most customers should be able to upgrade to Node 8 without any issues.
With that said, before you migrate, we highly recommend testing all of your:
Furthermore, we recommend that the testing be done in your development tenant and migrating your production tenant only if you see no issues in development.
You can query the Management API for your Rules, Custom Database scripts, and Custom Social Connections. This will make it easier for you to move items from your production tenant to development tenant for testing purposes.
Please see our documentation on the Connections and Rules endpoints for additional information on this process.
When using the Connections endpoints in the Management API, Custom Database Scripts can be retrieved or updated using
options.customScripts.Similarly, you can find Custom Social Connections in
options.scripts.fetchUserProfile.You will need to manually copy over any Hooks-related code that you use since they cannot be accessed via the Management API.
Affected modules
If you are using the following built-in modules (that is, modules that you did not explicitly require), please be aware that some versions were updated to work with Node 8. The following table summarizes the changes.
Pinned modules
If you have manually pinned modules, you may need to manually update them so that your code runs with Node 8.
For example, you must change
var mysql = require(‘[email protected]’);to
var mysql = require(‘mysql’);or, if the module must be pinned to a specific version:
var mysql = require(‘[email protected]’);Behavioral and syntactic changes
Some of the behavioral and syntactic changes in modules were not forward-compatible with Node 8.
For example, the default encoding of the
cryptomodule was changed frombinarytoutf8, and the use ofnew Buffer()has been deprecated in favor ofBuffer.from().Please consult Node.js' migration guide for v4 to v6 and v6 to v8 for additional information.
To ensure that your Auth0 implementation functions as intended, please be sure to migrate to the Node 8 runtime before June 30, 2019.