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. These endpoints were disabled on July 16, 2018, beginning a brief grace period in which usage of the endpoints could be re-enabled on a per-tenant basis until a migration could be completed. The endpoints have been removed from service as of August 6, 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.

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.

  1. 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.

  2. 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.

Embedded login for web uses Cross Origin Authentication. In some browsers this can be unreliable if you do not set up a Custom Domain and host your app on the same domain. Using Custom Domains with Auth0 is a paid feature. If you cannot use Custom Domains, consider migrating to Universal Login.

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, as they have been removed from service as of August 6, 2018. Applications using those endpoints will no longer function 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 multi-factor 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.

Other considerations

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.

Session management

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 was removed from service on August 6, 2018. The getSSOData() function will continue to work, but will behave differently, and in most cases, can be replaced with use of checkSession().

The getSSOData() and checkSession() functions should only be used from a Single Page Application

checkSession()
  • 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() unless getSSOData() features are needed.
getSSOData()
  • 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 Single Log Out is desired (a user logging out of one application needs to be logged out of other applications), an application can be set up to periodically poll Auth0 using checkSession() to see if a session exists. If the session does not exist, you can then log the user out of the application. The same polling method can be used to implement silent authentication for a Single Sign On scenario.

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.

This was previously done with getSSOData(). The 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.

Web applications

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.

Using Lock with AD/LDAP and Kerberos

If your application is using Lock in embedded mode with the goal of detecting IP ranges with AD/LDAP + Kerberos, this will no longer work.

The solution for the Kerberos case is to migrate to Universal Login. Lock will no longer attempt to detect an IP range by itself when embedded in an application. However, when using Universal Login with Lock inside your hosted login page, it will use the /user/ssodata endpoint (which still works from within the login page), and that endpoint will still return “true” when the user is in the Kerberos IP range. That means that using Universal Login you can:

  • Use getSSOData() to achieve an automatic login
  • Use Lock and get the Use Windows Authentication button (log in with Kerberos).

Troubleshooting

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.

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.