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>
This commit is contained in:
Marek Posolda 2024-04-11 08:18:41 +02:00 committed by GitHub
parent 33b747286e
commit 13daaa55ba
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
11 changed files with 85 additions and 9 deletions

View file

@ -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.

View file

@ -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[]

View file

@ -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}].

View file

@ -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}].

View file

@ -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.

View file

@ -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[]

View file

@ -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.

View file

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

View file

@ -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>>.

View file

@ -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.
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.
<<_authentication-sessions, Authentication sessions>> track the state of the authentication. The text below is applicable regardless of the source flow.
NOTE: This section describes deployments that use the {jdgserver_name} provider for authentication sessions.

View file

@ -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.