Documentation for changes related to 'You are already logged in' scen… (#28595)

closes #27879

Signed-off-by: mposolda <mposolda@gmail.com>


Co-authored-by: andymunro <48995441+andymunro@users.noreply.github.com>

docs/documentation/release_notes/topics/25_0_0.adoc

@@ -11,20 +11,25 @@ better security, with almost the same CPU time as previous releases of {project_
 memory, which is a requirement to be resistant against GPU attacks. The defaults for Argon2 in {project_name} requires 7MB
 per-hashing request.
 
-= SameSite attribute set for all cookies
+= Cookies updates
+
+== SameSite attribute set for all cookies
 
 The following cookies did not use to set the `SameSite` attribute, which in recent browser versions results in them
 defaulting to `SameSite=Lax`:
 
 * `KC_STATE_CHECKER` now sets `SameSite=Strict`
 * `KC_RESTART` now sets `SameSite=None`
-* `KC_AUTH_STATE` now sets `SameSite=Strict`
 * `KEYCLOAK_LOCALE` now sets `SameSite=None`
 * `KEYCLOAK_REMEMBER_ME` now sets `SameSite=None`
 
 The default value `SameSite=Lax` causes issues with POST based bindings, mostly applicable to SAML, but also used in
 some OpenID Connect / OAuth 2.0 flows.
 
+== Removing KC_AUTH_STATE cookie
+
+The cookie `KC_AUTH_STATE` is removed and it is no longer set by the {project_name} server as this server no longer needs this cookie.
+
 = Deprecated cookie methods removed
 
 The following methods for setting custom cookies have been removed:
@@ -33,6 +38,13 @@ The following methods for setting custom cookies have been removed:
 * `HttpCookie` - replaced by `NewCookie.Builder`
 * `HttpResponse.setCookieIfAbsent(HttpCookie cookie)` - replaced by `HttpResponse.setCookieIfAbsent(NewCookie cookie)`
 
+= Addressed 'You are already logged in' for expired authentication sessions
+
+The Keycloak 23 release provided improvements for when a user is authenticated in parallel in multiple browser tabs. However, this improvement did not address the case when an authentication session
+expired. Now for the case when user is already logged-in in one browser tab and an authentication session expired in other browser tabs, {project_name} is able to redirect back to the client
+application with an OIDC/SAML error, so the client application can immediately retry authentication, which should usually automatically log in the application because of the SSO session. For more
+details, see link:{adminguide_link}#_authentication-sessions[{adminguide_name} authentication sessions].
+
 = Password policy for check if password contains Username
 
 Keycloak supports a new password policy that allows you to deny user passwords which contains the user username.

docs/documentation/securing_apps/topics.adoc

@@ -12,6 +12,8 @@ include::topics/oidc/available-endpoints.adoc[]
 
 include::topics/oidc/supported-grant-types.adoc[]
 
+include::topics/oidc/oidc-errors.adoc[]
+
 ifeval::[{project_community}==true]
 include::topics/oidc/java/java-adapters.adoc[]
 endif::[]
@@ -41,6 +43,7 @@ endif::[]
 ifeval::[{project_product}==true]
 include::topics/saml/java/java-adapters-product.adoc[]
 endif::[]
+include::topics/saml/saml-errors.adoc[]
 
 include::topics/docker/docker-overview.adoc[]
 include::topics/client-registration.adoc[]

docs/documentation/securing_apps/topics/oidc/oidc-errors.adoc

@@ -0,0 +1,9 @@
+
+[[_oidc-errors]]
+=== {project_name} specific errors
+
+{project_name} server can send errors to the client application in the OIDC authentication response with parameters `error=temporarily_unavailable` and `error_description=authentication_expired`.
+{project_name} sends this error when a user is authenticated and has an SSO session, but the authentication session expired in the current browser tab and hence the {project_name} server cannot automatically do SSO
+re-authentication of the user and redirect back to client with a successful response. When a client application receives this type of error, it is ideal to retry authentication immediately and send a new
+OIDC authentication request to the {project_name} server, which should typically always authenticate the user due to the SSO session and redirect back. For more details, see 
+the link:{adminguide_link}#_authentication-sessions[{adminguide_name}].

docs/documentation/securing_apps/topics/saml/saml-errors.adoc

@@ -0,0 +1,20 @@
+
+[[_saml-errors]]
+=== {project_name} specific errors
+
+{project_name} server can send an error to the client application in the SAML response, which may contain a SAML status such as:
+
+[source,xml]
+----
+<samlp:Status>
+  <samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Responder">
+    <samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:AuthnFailed"/>
+  </samlp:StatusCode>
+  <samlp:StatusMessage>authentication_expired</samlp:StatusMessage>
+</samlp:Status>
+----
+
+{project_name} sends this error when a user is authenticated and has an SSO session, but the authentication session expired in the current browser tab and hence {project_name} server cannot automatically do SSO
+re-authentication of the user and redirect back to client with successful response. When a client application receives this type of error, it is ideal to retry authentication immediately and send a new
+SAML request to the {project_name} server, which should typically always authenticate the user due to the SSO session and redirect back. More details in
+the link:{adminguide_link}#_authentication-sessions[{adminguide_name}].

docs/documentation/securing_apps/topics/saml/saml-overview.adoc

@@ -1,3 +1,5 @@
+
+[[_saml]]
 ==  Using SAML to secure applications and services
 
 This section describes how you can secure applications and services with SAML using either {project_name} client adapters or generic SAML provider libraries.

docs/documentation/server_admin/topics.adoc

@@ -23,9 +23,10 @@ include::topics/authentication/flows.adoc[]
 include::topics/authentication/kerberos.adoc[]
 include::topics/authentication/x509.adoc[]
 include::topics/authentication/webauthn.adoc[]
+include::topics/authentication/passkeys.adoc[]
 include::topics/authentication/recovery-codes.adoc[]
 include::topics/authentication/conditions.adoc[]
-include::topics/authentication/passkeys.adoc[]
+include::topics/authentication/authentication-sessions.adoc[]
 include::topics/identity-broker.adoc[]
 include::topics/identity-broker/overview.adoc[]
 include::topics/identity-broker/default-provider.adoc[]

docs/documentation/server_admin/topics/authentication/authentication-sessions.adoc

@@ -0,0 +1,25 @@
+
+[[_authentication-sessions]]
+=== Authentication sessions
+
+When a login page is opened for the first time in a web browser, {project_name} creates an object called authentication session that stores some useful information about the request.
+Whenever a new login page is opened from a different tab in the same browser, {project_name} creates a new record called authentication sub-session that is stored within the authentication session.
+Authentication requests can come from any type of clients such as the Admin CLI. In that case, a new authentication session is also created with one authentication sub-session.
+Please note that authentication sessions can be created also in other ways than using a browser flow.
+
+The authentication session usually expires after 30 minutes by default. The exact time is specified by the *Login timeout* switch in the *Sessions* tab of the admin console when <<configuring-realms,configuring realm>>.
+
+==== Authentication in more browser tabs
+
+As described in the previous section, a situation can involve a user who is trying to authenticate to the {project_name} server from multiple tabs of a single browser. However, when that user authenticates in one browser tab,
+the other browser tabs will automatically restart the authentication. This authentication occurs due to the small javascript available on the {project_name} login pages. The restart will typically
+authenticate the user in other browser tabs and redirect to clients because there is an SSO session now due to the fact that the user just successfully authenticated in first browser tab. 
+Some rare exceptions exist when a user is not automatically authenticated in other browser tabs, such as for instance when using an OIDC parameter _prompt=login_ or <<_step-up-flow, step-up authentication>>  requesting a stronger
+authentication factor than the currently authenticated factor.
+
+In some rare cases, it can happen that after authentication in the first browser tab, other browser tabs are not able to restart authentication because the authentication session is already
+expired. In this case, the particular browser tab will redirect the error about the expired authentication session back to the client in a protocol specific way. For more details, see the corresponding sections
+of  link:{adapterguide_link}#_oidc-errors[OIDC documentation] and  link:{adapterguide_link}#_saml-errors[SAML documentation]. When the client application receives such an error, it can immediately resubmit the OIDC/SAML authentication request to {project_name} as
+this should usually automatically authenticate the user due to the existing SSO session as described earlier. As a result, the end user is authenticated automatically in all browser tabs.
+The link:{adapterguide_link}#_javascript_adapter[{project_name} Javascript adapter], link:{adapterguide_link}#_saml[{project_name} SAML adapter], and <<_identity_broker, {project_name} Identity provider>>
+support to handle this error automatically and retry the authentication to the {project_name} server in such a case.

docs/documentation/server_admin/topics/authentication/passkeys.adoc

@@ -1,3 +1,4 @@
+
 [id="passkeys_{context}"]
 === Passkeys
 

docs/documentation/server_admin/topics/sso-protocols/con-oidc-auth-flows.adoc

@@ -73,7 +73,7 @@ The _Client Credentials Grant_ creates a token based on the metadata and permiss
 See the <<_service_accounts,Service Accounts>> chapter for more information.
 
 [[_refresh_token_grant]]
-==== Refresh token grant
+===== Refresh token grant
 
 By default, {project_name} returns refresh tokens in the token responses from most of the flows. Some exceptions are implicit flow or client credentials grant described above.
 
@@ -83,7 +83,7 @@ specified interval. Otherwise, the session can be considered "idle" and can expi
 {project_name} supports <<_offline-access,offline tokens>>, which can be used typically when client needs to use refresh token even if corresponding browser SSO session is already expired.
 
 [[_refresh_token_rotation]]
-===== Refresh token rotation
+====== Refresh token rotation
 
 It is possible to specify that the refresh token is considered invalid once it is used. This means that client must always save the refresh token from the last refresh response because older refresh tokens,
 which were already used, would not be considered valid anymore by {project_name}. This is possible to set with the use of _Revoke Refresh token_ option as specified in the <<_timeouts,timeouts section>>.

docs/documentation/server_admin/topics/threat/auth-sessions-limit.adoc

@@ -1,10 +1,7 @@
 [[_limit-authentication-sessions]]
 === Limit Authentication Sessions
 
-When a login page is opened for the first time in a web browser, {project_name} creates an object called authentication session that stores some useful information about the request.
+<<_authentication-sessions, Authentication sessions>> track the state of the authentication. The text below is applicable regardless of the source flow.
-Whenever a new login page is opened from a different tab in the same browser, {project_name} creates a new record called authentication sub-session that is stored within the authentication session.
-Authentication requests can come from any type of clients such as the Admin CLI. In that case, a new authentication session is also created with one authentication sub-session.
-Please note that authentication sessions can be created also in other ways than using a browser flow. The text below is applicable regardless of the source flow.
 
 NOTE: This section describes deployments that use the {jdgserver_name} provider for authentication sessions.
 

docs/documentation/upgrading/topics/changes/changes-25_0_0.adoc

@@ -50,6 +50,12 @@ Behavior supported by STRICT, that is not supported by DEFAULT:
 
 It is not expected that you should be relying upon these behaviors from the WILDCARD or STRICT options.
 
+= Addressed 'You are already logged in' for expired authentication sessions
+
+{project_name} now does not display the message _You are already logged in_ to the end user when an authentication session expires and user is already logged-in. Instead it redirects the error
+about the expired authentication session to the client application, so the client can act on it and restart authentication as described in the link:{adminguide_link}#_authentication-sessions[{adminguide_name} authentication sessions chapter].
+You may consider updating your applications to being able to handle this error.
+
 = Removed a model module
 
 The module `org.keycloak:keycloak-model-legacy` module was deprecated in a previous release and is removed in this release. Use the `org.keycloak:keycloak-model-storage` module instead.