diff --git a/release_notes/topics/18_0_0.adoc b/release_notes/topics/18_0_0.adoc index c50721213c..309c17c009 100644 --- a/release_notes/topics/18_0_0.adoc +++ b/release_notes/topics/18_0_0.adoc @@ -4,18 +4,29 @@ Recovery Codes as another way to do two-factor authentication is now available as a preview feature. +== OpenID Connect Logout Improvements + +Some fixes and improvements were made to make sure that {project_name} is now fully compliant with all the OpenID Connect logout specifications: + +* OpenID Connect RP-Initiated Logout 1.0 +* OpenID Connect Front-Channel Logout 1.0 +* OpenID Connect Back-Channel Logout 1.0 +* OpenID Connect Session Management 1.0 + +For more details, see link:{adminguide_link}#_oidc-logout[{adminguide_name}]. + == Step-up authentication {project_name} now supports Step-up authentication. This feature was added in Keycloak 17 and it was further polished in this version. -For more details, take a look at link:{adminguide_link}#_step-up-flow[{adminguide_name}]. +For more details, see link:{adminguide_link}#_step-up-flow[{adminguide_name}]. Thanks to https://github.com/CorneliaLahnsteiner[Cornelia Lahnsteiner] and https://github.com/romge[Georg Romstorfer] for the contribution. == WebAuthn improvements {project_name} now supports WebAuthn id-less authentication. This feature allows that WebAuthn Security Key will identify the user during authentication as long as the -security key supports Resident Keys. For more details, take a look at link:{adminguide_link}#_webauthn_loginless[{adminguide_name}]. +security key supports Resident Keys. For more details, see link:{adminguide_link}#_webauthn_loginless[{adminguide_name}]. Thanks to https://github.com/vanrar68[Joaquim Fellmann] for the contribution. There are more WebAuthn improvements and fixes in addition to that. diff --git a/securing_apps/topics/oidc/java/logout.adoc b/securing_apps/topics/oidc/java/logout.adoc index e432e0e8ab..a4c8d0475b 100644 --- a/securing_apps/topics/oidc/java/logout.adoc +++ b/securing_apps/topics/oidc/java/logout.adoc @@ -3,12 +3,17 @@ [[_java_adapter_logout]] You can log out of a web application in multiple ways. For Jakarta EE servlet containers, you can call `HttpServletRequest.logout()`. For other browser applications, you can redirect the browser to -`\http://auth-server{kc_realms_path}/{realm-name}/protocol/openid-connect/logout?redirect_uri=encodedRedirectUri`, which logs you out if you have an SSO session with your browser. +`\http://auth-server{kc_realms_path}/{realm-name}/protocol/openid-connect/logout`, which logs the user out if that user has an SSO session with his browser. The actual logout is done once +the user confirms the logout. You can optionally include parameters such as `id_token_hint`, `post_logout_redirect_uri` and others as described in the +https://openid.net/specs/openid-connect-rpinitiated-1_0.html[OpenID Connect RP-Initiated Logout]. As a result, that logout does not need to be explicitly confirmed +by the user. + +If you want to avoid logging out of an external identity provider as part of the logout process, you can supply the parameter `$$initiating_idp$$`, with the value being +the identity (alias) of the identity provider in question. This parameter is useful when the logout endpoint is invoked as part of single logout initiated by the external identity provider. +The parameter `initiating_idp` is the supported parameter of the {project_name} logout endpoint in addition to the parameters described in the RP-Initiated Logout specification. When using the `HttpServletRequest.logout()` option the adapter executes a back-channel POST call against the {project_name} server passing the refresh token. If the method is executed from an unprotected page (a page that does not check for a valid token) the refresh token can be unavailable and, in that case, the adapter skips the call. For this reason, using a protected page to execute `HttpServletRequest.logout()` is recommended so that current tokens are always taken into account and an interaction with the {project_name} server is performed if needed. -If you want to avoid logging out of an external identity provider as part of the logout process, you can supply the parameter `$$initiating_idp$$`, with the value being -the identity (alias) of the identity provider in question. This is useful when the logout endpoint is invoked as part of single logout initiated by the external identity provider. diff --git a/server_admin/topics/sso-protocols/con-oidc-auth-flows.adoc b/server_admin/topics/sso-protocols/con-oidc-auth-flows.adoc index a1f7a875ca..5e0de4a559 100644 --- a/server_admin/topics/sso-protocols/con-oidc-auth-flows.adoc +++ b/server_admin/topics/sso-protocols/con-oidc-auth-flows.adoc @@ -312,9 +312,10 @@ User Resolver Provider is provided as SPI provider so that users of {project_nam ==== OIDC Logout -OIDC has three different specifications relevant to logout mechanisms, all of these are currently in draft status: +OIDC has four specifications relevant to logout mechanisms. These specifications are in draft status: . https://openid.net/specs/openid-connect-session-1_0.html[Session Management] +. https://openid.net/specs/openid-connect-rpinitiated-1_0.html[RP-Initiated Logout] . https://openid.net/specs/openid-connect-frontchannel-1_0.html[Front-Channel Logout] . https://openid.net/specs/openid-connect-backchannel-1_0.html[Back-Channel Logout] @@ -325,15 +326,21 @@ Again since all of this is described in the OIDC specification we will only give This is a browser-based logout. The application obtains session status information from {project_name} at a regular basis. When the session is terminated at {project_name} the application will notice and trigger it's own logout. -===== Frontchannel Logout +===== RP-Initiated Logout This is also a browser-based logout where the logout starts by redirecting the user to a specific endpoint at {project_name}. +This redirect usually happens when the user clicks the `Log Out` link on the page of some application, which previously used {project_name} to authenticate the user. Once the user is redirected to the logout endpoint, {project_name} is going to send logout requests to clients to let them to invalidate their local user sessions, and potentially redirect the user to some URL -once the logout process is finished. +once the logout process is finished. The user might be optionally requested to confirm the logout in case that `id_token_hint` parameter was not used +or the client referenced in the ID Token from `id_token_hint` has `Consent Required` enabled. -Depending on the client configuration, logout requests can be sent to clients through the front-channel or through the back-channel. +Depending on the client configuration, logout requests can be sent to clients through the front-channel or through the back-channel. For the frontend browser clients, which rely on the +Session Management described in the previous section, {project_name} does not need to send any logout requests to them; these clients automatically detect that SSO session +in the browser is logged out. + +===== Frontchannel Logout To configure clients to receive logout requests through the front-channel, look at the <<_front-channel-logout, Front-Channel Logout>> client setting. When using this method, consider the following: diff --git a/upgrading/topics/keycloak/changes-18_0_0.adoc b/upgrading/topics/keycloak/changes-18_0_0.adoc index 34397be117..a2158761b5 100644 --- a/upgrading/topics/keycloak/changes-18_0_0.adoc +++ b/upgrading/topics/keycloak/changes-18_0_0.adoc @@ -18,3 +18,51 @@ the migration. Consider these possible actions: insert into CLIENT_SCOPE_CLIENT (CLIENT_ID, SCOPE_ID, DEFAULT_SCOPE) select CLIENT.ID as CLIENT_ID, CLIENT_SCOPE.ID as SCOPE_ID, true as DEFAULT_SCOPE from CLIENT_SCOPE, CLIENT where CLIENT_SCOPE.REALM_ID='test' and CLIENT_SCOPE.NAME='acr' and CLIENT.REALM_ID='test' and CLIENT.PROTOCOL='openid-connect'; ``` + += OpenID Connect Logout + +Previous versions of {project_name} had supported automatic logout of the user and redirecting to the application by opening logout endpoint URL such as +`http(s)://example-host/auth/realms/my-realm-name/protocol/openid-connect/logout?redirect_uri=encodedRedirectUri`. While that implementation was easy to use, it had potentially negative impact +on performance and security. The new version has better support for logout based on the OpenID Connect RP-Initiated Logout specification. The parameter `redirect_uri` is no longer supported; also, +in the new version, the user needs to confirm the logout. It is possible to omit the confirmation and do automatic redirect to the application when you include parameter `post_logout_redirect_uri` +together with the parameter `id_token_hint` with the ID Token used for login. + +The existing deployments are affected in the following ways: + +- If your application directly uses links to logout endpoint with the `redirect_uri` parameter, you may be required to change this as described above. + Consider either removing the `redirect_uri` parameter entirely or replacing it with the `id_token_hint` and `post_logout_redirect_uri` parameters. +- If you use java adapters and your application does logout by call `httpServletRequest.logout()`, you are not affected because this call uses the backchannel variant of the logout endpoint + and that one was not changed. +- If you use the latest javascript adapter, you are also not affected. However if your application uses an older version of the JavaScript adapter, you are affected as this + adapter uses the variant of the logout endpoint with the deprecated `redirect_uri` parameter. In this case, you may need to upgrade to the latest version of the JavaScript adapter. + The same applies for the Node.js adapter. + +There is a backwards compatibility option, which allows your application to still use the old format of the `redirect_uri` parameter. + +ifeval::["{kc_dist}" == "quarkus"] +You can enable this parameter when you start the server by entering the following command: + +``` +bin/kc.[sh|bat] --spi-login-protocol-openid-connect-legacy-logout-redirect-uri=true start +``` +endif::[] + +ifeval::["{kc_dist}" == "wildfly"] +You can enable this parameter by including the following configuration in the `standalone-*.xml` file + +[source,bash,subs=+attributes] +---- + + + + + + + +---- +endif::[] + +With this configuration, you can still use the format with the `redirect_uri` parameter. Note the confirmation screen will be needed if the `id_token_hint` is omitted. + +WARNING: The backwards compatibility switch will be removed in some future version - probably Keycloak 21. You are encouraged to update your clients as soon as possible +as described above rather than rely on this switch.