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. However, it is understood that some situations may require that authentication forms 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.
Limitations of Cross-Origin Authentication
Because cross-origin authentication is achieved using third-party cookies, disabling third-party cookies will make cross-origin authentication fail.
There are two approaches you can follow to remediate the issue:
- Enable Custom Domains and host your web application in a domain that has the same top level domain as the Auth0 custom domain. This way the cookies are no longer third-party and are not blocked by browsers.
- Provide a Cross-Origin fallback page that will make cross-origin authentication work in some browsers even with third-party cookies disabled (see the browser testing matrix below).
Additionally, cross-origin authentication is only enabled for first-party clients.
These issues are another reason why the more practical solution is to use the Hosted Login Page.
Configure Your Client for Cross-Origin Authentication
Configuring your client for cross-origin authentication is a process that requires a few steps:
- Ensure that the Allowed Web Origins field is set to the domain making the request. You can find this field in the Client Settings.
- Ensure that your application is using Lock 11 or higher, or Auth0.js version 9 or higher.
- If you don't enable Custom Domains, 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.
Create a Cross-Origin Verification 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.
Provide a page in your application which instantiates
WebAuth from auth0.js. Call
crossOriginVerification immediately. The name of the page is at your discretion.
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.
Add the URL of this callback page to the Cross-Origin Verification Fallback field in your Client's settings in the Dashboard, under the Advanced > OAuth panel.
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|
|Android Galaxy S7||Chrome||No|
|Android Galaxy S7||Firefox||Yes|