diff --git a/docs/modules/ROOT/pages/servlet/oauth2/login/logout.adoc b/docs/modules/ROOT/pages/servlet/oauth2/login/logout.adoc index 32577615ed2..1f233650336 100644 --- a/docs/modules/ROOT/pages/servlet/oauth2/login/logout.adoc +++ b/docs/modules/ROOT/pages/servlet/oauth2/login/logout.adoc @@ -223,6 +223,128 @@ The overall flow for a Back-Channel logout is like this: Remember that Spring Security's OIDC support is multi-tenant. This means that it will only terminate sessions whose Client matches the `aud` claim in the Logout Token. +One notable part of this architecture's implementation is that it propagates the incoming back-channel request internally for each corresponding session. +Initially, this may seem unnecessary. +However, recall that the Servlet API does not give direct access to the `HttpSession` store. +By making an internal logout call, the corresponding session can now be validated. + +Additionally, forging a logout call internally allows for each set of ``LogoutHandler``s to be run against that session and corresponding `SecurityContext`. + +=== Customizing the Session Logout Endpoint + +By default, the session logout endpoint is `{baseScheme}://localhost{basePort}/logout`. +The `LogoutHandler` will collect the stored CSRF token and session identifier and populate them into a back-end call that allows the corresponding session to be invalidated. + +Given that propagating the CSRF token can be a challenge, a new configuration point was released in 6.4 which defaults the endpoint to `{baseUrl}/logout/connect/back-channel/{registrationId}`. +You can activate this in the following way: + + +[tabs] +====== +Java:: ++ +[source=java,role="primary"] +---- +http + // ... + .oidcLogout((oidc) -> oidc + .backChannel((backChannel) -> backChannel + .sessionLogout(Customizer.withDefaults()) + ) + ); +---- + +Kotlin:: ++ +[source=kotlin,role="secondary"] +---- +http { + oidcLogout { + backChannel { + sessionLogout { } + } + } +} +---- +====== + +In the event that you need to customize the endpoint, you can provide the URL as follows: + + +[tabs] +====== +Java:: ++ +[source=java,role="primary"] +---- +http + // ... + .oidcLogout((oidc) -> oidc + .backChannel((backChannel) -> backChannel + .sessionLogout((session) -> session + .uri("http://localhost:9000/logout/connect/back-channel/{registrationId}") + )) + ) + ); +---- + +Kotlin:: ++ +[source=kotlin,role="secondary"] +---- +http { + oidcLogout { + backChannel { + sessionLogout { + uri = "http://localhost:9000/logout/connect/back-channel/{registrationId}" + } + } + } +} +---- +====== + +=== Customizing the Session Logout Cookie Name + +By default, the session logout endpoint uses the `JSESSIONID` cookie to correlate the session to the corresponding `OidcSessionInformation`. + +However, the default cookie name in Spring Session is `SESSION`. + +You can configure Spring Session's cookie name in the DSL like so: + +[tabs] +====== +Java:: ++ +[source=java,role="primary"] +---- +http + // ... + .oidcLogout((oidc) -> oidc + .backChannel((backChannel) -> backChannel + .sessionLogout((session) -> session + .cookieName("SESSION") + )) + ) + ); +---- + +Kotlin:: ++ +[source=kotlin,role="secondary"] +---- +http { + oidcLogout { + backChannel { + sessionLogout { + cookieName = "SESSION" + } + } + } +} +---- +====== + === Customizing the OIDC Provider Session Registry By default, Spring Security stores in-memory all links between the OIDC Provider session and the Client session.