Logout Redirects Migration Guide

On 01 December 2021, the logout behavior will change to always redirect users to the URI passed to the Auth0 logout APIs instead of using the returnTo query parameter passed by Identity Providers to the /login/callback during the execution of the logout. The URI used will depend on the API called to request the session logout:

• https://{yourDomain}/logout: Auth0 will use the returnTo parameter

• https://{yourDomain}/v2/logout?federated: Auth0 will use the returnTo parameter

• https://{yourDomain}/wsfed/{yourClientId}?wa=wsignout1.0: the wreply parameter

If Auth0 does not have a record of a preceding call to one of these APIs, logout will complete, but redirection will not occur and an error page will be displayed to end users.

The following endpoints are affected by this change:

• https://{yourDomain}/v2/logout when using the federated query parameter to log users out of Identity Providers

• https://{yourDomain}/wsfed/{yourClientId}?wa=wsignout1.0 when using the wreply query to log out of Auth0 using the WS-Fed Protocol

• https://{yourDomain}/login/callback when using the returnTo query parameter.

Tenants relying on the following usage patterns will not be able to redirect to their desired redirect URI after 01 December 2021.

1. Applications that call /login/callback?returnTo without a preceding call to /v2/logout or /wsfed/{yourClient}?wa=wsignout1.0 to specify the Logout URL.

2. Identity Providers that call /login/callback?returnTo with a value in returnTo that is different to the value originally provided in a preceding call to /v2/logout or /wsfed/{yourClientId}.

3. Applications that make concurrent calls to one of the affected APIs while providing different redirection URIs in the different calls.

4. Applications or users that make calls to the /authorize API concurrently or interleaved with calls to one of the affected APIs regardless of whether there was a preceding call to /v2/logout or /wsfed/{yourClientId}?wa=wsignout1.0.

1. Go to Auth0 Dashboard > Monitoring > Logs, and search for type:depnote AND description:*unvalidated*redirects* to find applications that rely on the deprecated behavior.

2. For each affected application, ensure that:

   1. the application or Relying Party initiates the logout using one of Auth0’s public APIs: Authentication API: Logout or Authentication API: WS-Federation.

   2. the application does not rely on Identity Providers modifying the Logout URL that is passed back to /login/callback?returnTo as these modifications will no longer be honored.

   3. the application does not make concurrent calls to logout APIs using different Logout URLs. Auth0 will store only a single Logout URL for a user agent at any one time, which means that concurrent logout processes will fail to redirect.

   4. the application does not make calls to /authorize concurrently or interleaved with calls to the logout APIs. Completing a login transaction will clear the stored Logout URL for a user agent, which means that concurrent logout processes will fail to redirect.

   5. the application and users do not interleave calls to /authorize with calls to one of the affected APIs.

Once the migration actions have been completed and tested, you should verify the migration.

Once you have migrated your applications and are sure that they no longer rely on the deprecated usage patterns, verify your changes by disabling the deprecated behavior at a time of your choosing and ahead of 01 December 2021.

1. Go to Auth0 Dashboard > Tenant Settings > Advanced, and locate the Migrations section.

2. Disable the Unvalidated redirects from /login/callback switch. Turning off this switch disables the deprecated behavior for your tenant, preventing it from being used.

   

If redirection to the Logout URL does not work as expected after disabling this switch, it is a sign that your application still relies on the deprecated behavior.

Once migrations have been successfully performed and confirmed in production environments, the you can disable the switch permanently to ensure that the deprecated features can no longer be used. On 01 December 2021, Auth0 will remove the deprecated behavior completely together with the associated switch.