Use the OIDC Endpoint to Log Users Out of Auth0

Auth0 implements OpenID Connect’s RP-Initiated Logout 1.0 for end-user logout. This standard is part of the OpenID Connect collection of final specifications.

By default, the RP-Initiated Logout endpoint is enabled. Applications using OIDC-compliant SDKs can use OpenID Connect Discovery 1.0 with the .well-known path prefix in the URL to discover the enabled endpoint. To use endpoint discovery, contact Auth0 Support.

Once you have contacted Auth0 Support to enable endpoint discovery, use the following command with your tenant information:

curl -X GET https://acme.eu.auth0.com/.well-known/openid-configuration
{
  "issuer": "https://acme.eu.auth0.com/",
  "authorization_endpoint": "https://acme.eu.auth0.com/authorize",
  ...
  "end_session_endpoint": "https://acme.eu.auth0.com/oidc/logout"
}

Your request should initiate logout from a valid Auth0 session by directing end-users to the /oidc/logout endpoint. To verify the legitimacy of the request, include the id_token_hint parameter from the ID token Auth0 issued during login. Other parameters are optional if this is provided.

The attached ID token contains the registered claims issuer (iss), audience (aud), and the Auth0 session ID (sid) for verification. To learn more about ID token claims, read ID Token Structure.

https://{yourDomain}/oidc/logout?id_token_hint={yourIdToken}&post_logout_redirect_uri={yourCallbackUrl}

curl --request POST \
  --url 'https://{yourDomain}/oidc/logout' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data 'id_token_hint=YOUR_ID_TOKEN' \
  --data 'post_logout_redirect_uri=YOUR_CALLBACK_URL'

Alternatively, you can use the logout_hint parameter if your application is not able to store ID tokens. Assign logout_hint with the session ID in the server (sid) making the request. Both values must match the server’s metadata associated to the calling session.

https://{yourDomain}/oidc/logout?{clientId}={yourClientId}&logout_hint=SESSION_ID

The OIDC standard defines that the logout flow should be interrupted to prompt the user for consent if the server does not have certainty that the logout request was initiated by that end-user. This is enforced by redirecting the browser to a logout consent prompt:

When the user confirms the logout request, the Auth0 session is ended.

The following rules determine a user should be asked for confirmation before terminating the session.

• Neither id_token_hint nor logout_hint are provided.

• The ID token's sid claim does not correspond to the browser session in the request.

• The logout_hint does not match current session data.

If these conditions occur, the end-user is redirected to a consent prompt to confirm the user wants to logout from the identity provider.

To disable the consent prompt:

1. Navigate to Auth0 Dashboard > Settings > Advanced.

2. Click the toggle under Show RP-Initiated Logout prompt.

When the prompt option is off, the rules are no longer applicable and logout of the existing session proceeds automatically.

Upon successful logout, you can redirect users to a specific URL.  You can instruct the server to redirect the browser with the post_logout_redirect_uri parameter. Register the redirect URL in your tenant or application settings.

1. Add a post_logout_redirect_uri query string parameter with the target URL as the value. Encode the target URL being passed in. For example, to redirect the user to https://www.example.com after logout, make the following request: https://{yourDomain}/oidc/logout?post_logout_redirect_uri=http%3A%2F%2Fwww.example.com

2. Add the unencoded post_logout_redirect_uri URL (for these examples, it is http://www.example.com) as an Allowed Logout URLs in one of two places:

   • Tenant Settings: For logout requests that do not include the client_id or an id_token_hint parameter, you must add the post_logout_redirect_uri URL (for example http://www.example.com) to the Allowed Logout URLs list in Tenant Settings > Advanced. For example: https://{yourDomain}/oidc/logout?post_logout_redirect_uri=http%3A%2F%2Fwww.example.com.

     To add a list of URLs that the user may be redirected to after logging out at the tenant level, go to the Tenant Settings > Advanced of the Auth0 Dashboard.

     

   • Auth0 Application Settings: For logout requests that include the client_id or an id_token_hint parameter, you must add the post_logout_redirect_uri URL (for example http://www.example.com) to the Allowed Logout URLs list in Applications > Applications > Settings associated with the specified Client ID. For example: https://{yourDomain}/oidc/logout?post_logout_redirect_uri=http%3A%2F%2Fwww.example.com&client_id={clientId}

     To redirect the user after they log out from a specific application, you must add the URL used in the post_logout_redirect_uri parameter of the redirect URL to the Allowed Logout URLs list in the Settings tab of your Auth0 application that is associated with the CLIENT_ID parameter.

     

When providing the URL list, you can:

• Specify multiple, valid, comma-separated URLs.

• Use * as a wildcard for subdomains (such as http://*.example.com).

In order to avoid validation errors, make sure that you include the scheme part of the URL. For example, setting the value to *.example.com will result in a validation error, so you should use http://*.example.com instead.

If post_logout_redirect_uri is omitted, the server returns an empty HTTP 200 response. 

Query parameters are declared as part of the Allowed Logout URLs and should be added in Auth0 Dashboard > Settings > Advanced. For example, for testing purposes, you might use test=true or test=false. Your URL should include the test parameters after the ?: https://{yourDomain}/oidc/logout?test=true.

If you are using multiple query parameters, all parameters must be added or the call could fail. For example, https://{yourDomain}/oidc/logout?test=true&parameter1=2.

Similarly to the login message, logout prompt texts are localized according to the browser setting. The standard optional ui_locales parameter is ignored.

We recommend using Auth0 SDKs with OIDC standards incorporated into the design.

• You may call the logout endpoint with redundant information. For example, you may send an id_token_hint and a logout_hint, or an id_token_hint and a client_id. In all cases, the service checks for consistent information and returns an error otherwise. 

To log the user out of both Auth0 and the IdP, you must include the federated querystring parameter with your call to the Logout endpoint.

Redirecting the user to this URL clears all SSO cookies set by Auth0 for the user. To learn more about cookies, read Authentication API Cookies.

If you are using the alternative logout endpoint, review the API documentation.

• Log Users Out of Applications
• Log Users Out of Identity Providers
• Log Users Out of SAML Identity Providers
• Redirect Users with Alternative Logout