Migrating to from Auth0.js v8 to v9
Update the Auth0.js library using npm or yarn.
Once updated, you can add it to your build system or bring it in to your project with a script tag.
If you do not want to use a package manager, you can retrieve Auth0.js from Auth0's CDN.
Configure your Auth0 application for embedded login
When implementing embedded login, Auth0.js v9 will use cross-origin calls inside hidden iframes to perform authentication. To make sure this can be done securely, Auth0 needs to know the domains where you will be hosting your applications.
Add the domain to the Allowed Web Origins field. You can find this field in the Application Settings area of your Dashboard.
Review calls to getSSOData()
getSSOData() function was reimplemented in Auth0.js v9 to simplify migration from older versions, but the behavior is not exactly the same.
The function will not work as expected when you use it in Web Applications that use the Authorization Code Flow (such as when you specify
response_type='code'). It will always return that there is not a current session.
If you want to avoid showing the Lock dialog when there is an existing session in the server, you can use the checkSession() function in Auth0.js.
We recommend that you do not use
getSSOData() and use checkSession() instead. Note that in order for
checkSession() to work properly, it requires that you set the Allowed Web Origins field in the dashboard.
If you are going to keep using
getSSOData(), take into account the changes in the return values described in the table below. In most applications, the only value that was actually used was the
sso property, which still has the same semantics.
|Property||Old Value||New Value|
|sessionClients||List of applications ids the user has active sessions with||List with a single element with the client id configured in auth0.js|
|lastUsedClientId||The client id for the last active connection||The last application used when authenticating from the current browsers|
|lastUsedUserId||The user id for the current session||The same|
|lastUsedUsername||User's email or name||The same (requires
|lastUsedConnection||Last used connection and strategy.||Last connection used when authenticated from the current browser. It will be
For the function to work properly, you need to ask for
scope='openid profile email' when you initialize Auth0.js.
Migration with getSSOData demo
Configure your custom domain
Ensure that your application updates are made prior to setting up custom domains in your application, as the older versions of Auth0.js v9 will not work when configured with a custom domain.
Use the custom domain when instantiating Lock.
- Set the
If you intend to use the Auth0.js
auth0.Management to get user information or perform account linking operations, you will need to instantiate a new Auth0 object with the Auth0 domain rather than your custom domain. The Management API only accepts Auth0 domains.
See the Auth0.js documentation on user management for more information on using the Management API in Auth0.js.
Migrating from legacy authentication flows
The OIDC conformant flows disallow certain practices that were common when developing applications with older versions of the library, like using Refresh Tokens, using ID Tokens to call APIs, and accessing non-standard claims in the user profile.
Follow the steps in the Migration from Legacy Authentication Flows to learn what changes you need to make in your application.
Verifying your migration
Once you have migrated your codebase, you should no longer see deprecation notes in your logs.
If you would like to be sure that your applications are no longer calling the legacy endpoints, you can go to the Dashboard under Tenant Settings > Advanced then scroll down to Migrations and toggle off the Legacy Lock API switch. Turning off this switch will disable the deprecated Lock / Auth0.js endpoints for your tenant, preventing them from being used at all.
After disabling this switch, if the Legacy Lock API errors in your logs do not clear up or if turning it off results in failed logins, this is a sign that you have yet to completely remove all instances of legacy code from your applications.
Once migrations have been successfully performed in production environments, the switch can be toggled off and left off, to ensure that the deprecated features can no longer be used.
Auth0.js v9 will default the value of the scope parameter to
openid profile email.
If you are running your website from
http://127.0.0.1 and you do not specify the
openid profile email scope when initializing auth0.js, calling the
getSSOData() method will result in the following error in the browser console:
This will not happen when you run your application in production, or if you specify the required scope. You can read more about this scenario in the documentation on skipping consent for first-party applications.