Cross-Origin Authentication

For most situations, Auth0 recommends that authentication transactions be handled at the Hosted Login Page. Doing so offers the easiest and most secure way to authenticate users. It is, however, understood that some scenarios necessitate that the Lock widget or a custom login form be directly embedded in an application. Cross-origin authentication provides a way to do this securely.

What is Cross-Origin Authentication?

When authentication requests are made from your application (via the Lock widget or a custom login form) to Auth0, the user's credentials are sent to a domain which differs from the one that serves your application. Collecting user credentials in an application served from one origin and then sending them to another origin can present certain security vulnerabilities, including the possibility of a phishing attack.

Auth0 provides a cross-origin authentication flow which makes use of third-party cookies. The use of third-party cookies allows Lock and Auth0's backend to perform the necessary checks to allow for secure authentication transactions across different origins. This helps to prevent phishing when creating a single sign-on experience with the Lock widget or a custom login form in your application and it also helps to create a secure login experience even if single sign-on is not the goal.

Cross-origin authentication is only necessary when authenticating against a directory using a username and password. Social IdPs and enterprise federation use a different mechanism, redirecting via standard protocols like OpenID Connect and SAML. Additionally, this cross-origin authentication is only applicable to embedded login on the web (using Lock or auth0.js). Native applications using embedded login make use of the standard OAuth 2.0 token endpoint.

Limitations of Cross-Origin Authentication

Because cross-origin authentication is achieved using third-party cookies, the user must have a browser that supports third-party cookies. Additionally, in some browsers, disabling third-party cookies will make cross-origin authentication fail (see the browser testing matrix below).

If you wish to use cross-origin authentication, in order to avoid situations in which your users would be unable to authenticate, you may wish to ask your users to leave third party cookies enabled or to switch browsers. You could also simply inform users of the non-support of those browsers when third party cookies are disabled.

This limitation is another reason why the more practical solution, where possible, is to use the Hosted Login Page and circumvent this issue entirely.

Configure Your Client for Cross-Origin Authentication

Configuring your client for cross-origin authentication is a process that requires a few steps:

  1. In the Client Settings for your application, click Show Advanced Settings > OAuth and find the Cross Origin Authentication Mode switch. Ensure that the switch is in the on position.
  2. Εnsure that the OIDC Conformant switch is toggled on in the same settings panel. Cross-Origin Authentication switch
  3. Ensure that the Allowed Origins (CORS) field is set to the domain making the request. You can find this field in the Client Settings.
  4. Ensure that your application is using Lock version 10.22 or higher, or Auth0.js version 8.7 or higher.
  5. If you are using Lock 10, make sure that you are using the oidcconformant option.
  6. Third-party cookies do not work in some browsers. To handle these cases, you will need to author a page which uses auth0.js to act as a fallback for the cross-origin transaction. More information on setting up this page is provided below.

Using oidcconformant: true option in Lock without toggling the Cross Origin Authentication Mode on in the client's settings will not work.

Create a Cross-Origin Fallback Page

There are some cases when third party cookies will not be available. Certain browser versions do not support third party cookies and, if they do, there will be times that they will be disabled in a user's settings. You can use auth0.js in your application on a dedicated page to properly handle cases when third-party cookies are disabled. This page must be served over SSL.

Note that using crossOriginAuthenticationCallback as a fallback will only work if the browser is on the support matrix as Yes under "Third-Party Cookies Disabled". For some browsers, such as Chrome and Opera (Desktop & Android versions of both), when third party cookies are disabled, cross-origin authentication will not work at all.

Provide a page in your application which instantiates WebAuth from auth0.js. Call crossOriginAuthenticationCallback immediately. The name of the page is at your discretion.

<!-- callback-cross-auth.html -->

<head>
  <script src="https://cdn.auth0.com/js/auth0/8.10.1/auth0.min.js"></script>
  <script type="text/javascript">
    var auth0 = new auth0.WebAuth({
      clientID: 'YOUR_CLIENT_ID',
      domain: 'YOUR_AUTH0_DOMAIN',
      redirectUri: 'https://YOUR_APP/callback'
    });
    auth0.crossOriginAuthenticationCallback();
  </script>
</head>

When third party cookies are not available, auth0.js will render an iframe which will be used to call a different cross-origin verification flow.

Please see the cross-origin auth sample for more detail.

Browser Testing Matrix

This table lists which browsers can use cross-origin authentication when third-party cookies are disabled.

OS Browser Third-Party Cookies Disabled
Windows IE Yes
Windows Edge Yes
Windows Firefox Yes
Windows Chrome No
Windows Opera No
macOS Sierra Safari Yes
macOS Firefox Yes
macOS Chrome No
macOS Opera No
iOS (iPhone) Safari Yes
iOS (iPhone) Chrome Yes
iOS (iPhone) Firefox Yes
iOS (iPad) Safari Yes
iOS (iPad) Chrome Yes
Android Galaxy S7 Chrome No
Android Galaxy S7 Firefox Yes