Legacy Lock API Deprecation
On April 4, 2018, Auth0 publicly disclosed a vulnerability. That vulnerability resulted in the deprecation of two endpoints in the Auth0 API, and the libraries and SDKs which used those endpoints. Due to this vulnerability, those endpoints (and thus, the deprecated versions of the libraries) will be removed from service on July 16, 2018.
The purpose of this guide is to help you to select the best migration path for your application(s) if you are impacted by the deprecation notice.
Am I affected?
If your applications match any of the following cases, you are affected:
- Use of versions of Lock previous to v11 and versions of Auth0.js previous to v9 in embedded login scenarios
- Use of /usernamepassword/login endpoint directly from applications
- Use of /user/ssodata endpoint directly from applications
If you do not use the above libraries and do not specifically call the above endpoints, you are not affected. No libraries which are not specifically named are affected by this vulnerability, or in turn, by the migration.
If you already use Universal Login / Hosted Login Page
Applications which log users in via Universal Login through an Auth0 hosted page are not required to update the version of Lock or Auth0.js that they use inside that login page (if you have customized your login page in the Dashboard. However, the use of the newest library versions is strongly recommended, even in the Universal Login Page. For those who have not customized their login page, the Lock v11 widget is already in use and no further action is required.
If you use embedded login
Embedded login with Lock v11 and Auth0.js v9 now rely entirely on cross-origin authentication for any form of username/password authentication (such as Auth0 DB, Custom DB, or LDAP connections). Cross-origin authentication is the situation in which credentials are collected on one domain, but validated on another.
This cross-origin authentication protocol relies on cookies, which will be considered third-party cookies if the domain of the application and Auth0 tenant do not match. Unfortunately, some browsers block third-party cookies, and even if supported, many users may have manually disabled third-party cookies in their browsers.
Because of these cross-origin authentication issues, there are only two general implementations that can be recommended.
Migrate to Universal Login. Universal Login will work with or without custom domains, and will work from most application types as well. It requires the least application code to implement and is the most secure option.
Continue to use embedded login and migrate to newer library versions. A crucial part of this implementation is employing a custom domain to prevent cross-origin issues. The following caveats apply:
- Only one custom domain can be applied per Auth0 tenant, so all applications on the tenant will use the same custom domain (they will need to use the same top-level domain as well).
- This option may not be viable for customers who are not eligible to use custom domains, or who choose not to do so. In those cases, Universal Login is the best approach.
If neither of these recommendations (Universal Login or embedded + custom domains) seem to work for your situation, please visit our Support Center and file a support ticket or a community post for further guidance.
What do I do?
All applications must stop using the deprecated endpoints / library versions prior to July 16, 2018, when they will be removed from service and those applications will cease to work correctly. There are two options for migration:
1. Migrate to Universal Login
Universal Login is strongly recommended for most use cases because it offers many advantages over the embedded form of login screen. These advantages include:
- Developed, hosted and maintained by Auth0 (less maintenance required by your team).
- Provides a single place to make changes.
- More secure because credentials are collected and verified within the same domain. This reduces exposure of static credentials to multiple applications as well as the possibility of CSRF and man-in-the-middle attacks.
- Provides reliable Single Sign On functionality without relying on third-party cookies or restricting the domain of applications.
- Fully customizable in terms of colors, text, logos, buttons as well as custom domain.
- Provides proper cache control to avoid browsers caching old versions.
- Can leverage either the Lock Widget or Auth0.js SDK for flexibility in appearance and function.
- Works with any type of Auth0 connection as well as multifactor authentication.
Universal Login migration guides
2. Continue to use embedded login and migrate
Embedded login (embedding Lock or a custom authentication UI) should be used only if the Universal Login Page cannot be used. If you intend to continue using embedded login, you must upgrade applications from deprecated library versions.
Embedded login migration guides
Continued use of embedded login will require the use of custom domains in order to prevent cross-origin authentication issues. The custom domains documentation includes important information on the use of custom domains, how to set them up, and what configuration is required for more intricate use cases, such as custom domains with SAML.
A few specific items are changing with the new versions / endpoints. If you use any of the following features, you might want to take a look at the corresponding section below.
How to get user info
Once a user has been authenticated, an application may wish to retrieve information about a user. The recommended way to do this now is via the /userinfo endpoint. If you are using Auth0.js v8 or v9 and using the userInfo() method, you already have made this change.
For customers who are using the /tokeninfo endpoint, this endpoint is being replaced with the /userinfo endpoint. Customers should migrate to use the /userinfo endpoint instead of /tokeninfo. The /userinfo endpoint is the only one that will be maintained going forward and is the only endpoint for user information that is supported with the custom domains feature.
As explained in the /userinfo endpoint docs entry, /userinfo obtains information using the Management API and therefore requires an Access Token (obtained during login) instead of the ID Token used by /tokeninfo.
Note also that the /userinfo response may vary based on scopes requested and the value of the OIDC Conformant setting in the Dashboard under Applications > (Your Application) > Settings > Advanced Settings. In that case, application code might need adjusted to handle the slightly altered response format.
Single Page Applications
If a user navigates to a new page in a Single Page Application, your application may wish to check if a user already has an existing session. In order to do this, you may have directly called the /ssodata endpoint or utilized the
getSSOData() function in auth0.js v8 or prior. The /ssodata endpoint is deprecated and will be removed from service on July 16, 2018. The
getSSOData() function will continue to work, but will behave differently, and in most cases, can be replaced with use of
- The Auth0.js
checkSession()function can be used to check whether or not a user has an existing session in Auth0.
- Invoking the
checkSession()function will trigger an /authorize call, which will in turn result in the execution of rules.
- The new
checkSession()function is more lightweight and should be used as a replacement for
getSSOData()features are needed.
- The Auth0.js v9
getSSOData()function will continue to work, but it now behaves differently than in the past.
- In Auth0.js v9,
getSSOData()will check if a user has an existing session and perform a further check to determine if the user is the same one as in the last interactive authentication transaction. This supports Lock’s feature of showing the last logged-in user to facilitate subsequent logins.
- Invoking the
getSSOData()function will now trigger a call to the /authorize endpoint, which will in turn result in the execution of rules.
Polling for an existing session
In some multi-application scenarios, where a user logging out of one application needs to be logged out of other applications, an application may have been set up to periodically poll Auth0 using
getSSOData() to see if a session existed, and if not, log the user out of the application.
Instead of doing this, applications should now use
checkSession() instead of
getSSOData() function performs more work behind the scenes than is needed for this purpose and applications that are not switched to
checkSession() will suffer a needless performance penalty.
The poll interval between checks to
checkSession() should be at least 15 minutes between calls to avoid any issues in the future with rate limiting of this call.
In "web applications", the backend typically has a session for the user. Over time, the application session may expire, in which case the application should renew the session. The application backend should invoke a call to the /authorize endpoint to get a new token. If the Authorization Server (Auth0 in this case) still has a session for the user, the user will not have to re-enter their credentials to log in again. If Auth0 no longer has a session for the user, the user has to log in again.
Customers with web applications which call the API from their backend should use this approach. Specifically, they should call /oauth/token to renew their token.
How to log users out
The deprecation does not require any changes for logout, but if a custom domain has been configured and is used when invoking authentication, the /logout endpoint should be invoked using the custom domain as well.
How to tell if you have deprecated usage
Please take a look at the Deprecation Error Reference to assist with verifying that your application does, or does not, use deprecated features.
How to test whether you are ready before the removal of service date
Auth0 has provided a toggle in the tenant settings in the Dashboard to allow customers to turn off the legacy endpoints manually for their tenant ahead of the deprecation deadline of July 16, 2018. Navigate to the tenant settings screen, Advanced tab and scroll down to the block of migration toggles.
Turn off the Legacy Lock API toggle to stop your tenant from being able to use those endpoints. This toggle allows you to test the removal of the deprecated endpoints with the ability to turn them back on if you encounter issues.
Bookmarking the login page
Bookmarking the Universal Login page is not supported. If a user bookmarks the login page and attempts to initiate authentication by going directly to the bookmarked URL instead of starting from the application, the following error message will be shown:
Password login is disabled for clients using externally hosted login pages with oidc_conformant flag set.
For any customers who have not quite finished migrating away from the above deprecated features, Auth0 has implemented a temporary solution to help mitigate the severity of the issues with the deprecated endpoints. This solution relies on "fingerprinting" checks on the successive calls in an authentication transaction.
If any authentication requests are being rejected by the fingerprinting solution, they can be identified with the following query against logs:
Description: "Unable to verify transaction consistency"
Customers who have any transactions rejected by the fingerprinting checks should complete their upgrades to resolve the issue.