8000 Deprecate legacy cookie behaviour behind `LEGACY_COOKIES` profile by jonkoops · Pull Request #26161 · keycloak/keycloak · GitHub
[go: up one dir, main page]

Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions common/src/main/java/org/keycloak/common/Profile.java
Original file line number Diff line number Diff line change
Expand Up @@ -99,6 +99,9 @@ public enum Feature {
TRANSIENT_USERS("Transient users for brokering", Type.EXPERIMENTAL),

MULTI_SITE("Multi-site support", Type.PREVIEW),

@Deprecated
LEGACY_COOKIES("Legacy cookies without 'SameSite' attribute for older browsers.", Type.DEPRECATED),
;

private final Type type;
Expand Down
3 changes: 2 additions & 1 deletion common/src/test/java/org/keycloak/common/ProfileTest.java
Original file line number Diff line number Diff line change
Expand Up @@ -81,7 +81,8 @@ public void checkDefaults() {
Profile.Feature.TOKEN_EXCHANGE,
Profile.Feature.CLIENT_SECRET_ROTATION,
Profile.Feature.UPDATE_EMAIL,
Profile.Feature.LINKEDIN_OAUTH
Profile.Feature.LINKEDIN_OAUTH,
Profile.Feature.LEGACY_COOKIES
));

// KERBEROS can be disabled (i.e. FIPS mode disables SunJGSS provider)
Expand Down
24 changes: 24 additions & 0 deletions docs/documentation/release_notes/topics/24_0_0.adoc
Comment thread
jonkoops marked this conversation as resolved.
Resolved
Original file line number Diff line number Diff line change
@@ -1,3 +1,27 @@
= Deprecation of 'legacy' cookie behavior

As part of the https://privacysandbox.com/[Privacy Sandbox] effort, Keycloak is making changes to the way cookies are handled. Specifically we are preparing for the https://developers.google.com/privacy-sandbox/blog/cookie-countdown-2023oct[end of third-party cookies], and are looking to improve the consistency, privacy and security of how cookies are handled by default within Keycloak. This has several implications for how Keycloak is configured and used:

== Removal of cookies suffixed in `_LEGACY`

Since the introduction of the https://web.dev/articles/samesite-cookies-explained[`SameSite`] attribute on cookies provided by Keycloak, another set of 'legacy' cookies (name suffixed in `_LEGACY`) were also introduced in order to support older browsers that were https://www.chromium.org/updates/same-site/incompatible-clients/[not compatible] with this attribute. Since the `SameSite` attribute is now https://caniuse.com/same-site-cookie-attribute[widely supported], this behavior is now deprecated, so that only the cookies using the `SameSite` attribute remain.

== `SameSite` attribute set to `Strict` by default
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this title accurate or it is more about our future plans? We don't necessarily need to force strict but also consider making the attribute configurable, as per discussions we had in the past.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The documentation updates here reflect what I intend the implementation to be under this PR (yet to be implemented).

We don't necessarily need to force strict but also consider making the attribute configurable, as per discussions we had in the past.

It would still be 'overwritable' in code for specific use-cases, but not globally configurable if that is what you mean here. Is there a link to these previous discussions somewhere that can be referenced?

Future changes in Chrome will move all these to Strict by default, as part of the 3rd-party cookie phase-out. So this is just about getting ahead of these changes by forcing it as the default.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Future changes in Chrome will move all these to Strict by default, as part of the 3rd-party cookie phase-out. So this is just about getting ahead of these changes by forcing it as the default.

Yeah, but only if we don't set the attribute, right? My point is that I'm not sure if we should do the Strict now because, AFAIK, it is perfectly fine to go with secure and none. And TBH, I think that should be the default as a balance between security and usability.

I'll need to go over the closed/open issues to filter discussions ...

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, but only if we don't set the attribute, right?

To my knowledge also if we don't set the attribute, it will eventually not be possible to share cookies in a third-party context.

@stianst stianst Jan 16, 2024 •
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We can NOT use strict for cookies as that will break single-sign on for any applications coming from a different origin.

Basically if the KEYCLOAK_IDENTITY cookie uses strict it won't be accessible on redirect/links from the application, and hence not available for the authorization request.

We can consider lax although that would break anything using POST such as some SAML flows.

@pedroigor pedroigor Jan 16, 2024 •
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not really for applications running within the same domain, right?

We have open issues about making it possible to configure our cookies and use strict. As I mentioned before, for now we should keep using none and have a follow-up to properly discuss the best/secure default settings. But I think it makes sense to make this configurable too.


All cookies provided by Keycloak will now have the `SameSite` attribute set to https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#strict[`Strict`] by default. This means that cookies will only be sent in a first-party context, that is, requests originating from the same site that set the cookie. Some specific cookies that are required in a third party contexts, such as the session cookie are exempt from this behavior for now, but this will likely change in the future as using cookies in a third-party context will no longer supported by browsers.
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
All cookies provided by Keycloak will now have the `SameSite` attribute set to https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#strict[`Strict`] by default. This means that cookies will only be sent in a first-party context, that is, requests originating from the same site that set the cookie. Some specific cookies that are required in a third party contexts, such as the session cookie are exempt from this behavior for now, but this will likely change in the future as using cookies in a third-party context will no longer supported by browsers.
All cookies provided by Keycloak will now have the `SameSite` attribute set to https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#strict[`Strict`] by default. This means that cookies will only be sent in a first-party context, that is, requests originating from the same site that set the cookie. Some specific cookies that are required in a third party contexts, such as the session cookie are exempt from this behavior for now, but this will likely change in the future as using cookies in a third-party context will no longer be supported by browsers.

It looks the word be missing (or some other similar word)?

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

See above - strict also has implications on cookies not being available after redirects/links to Keycloak


== Support for insecure contexts dropped

Due to the aforementioned changes, we are officially dropping support for running Keycloak outside of a https://developer.mozilla.org/en-US/docs/Web/Security/Secure_Contexts[secure context]. You should therefore ensure that your Keycloak instance if always running on what is https://developer.mozilla.org/en-US/docs/Web/Security/Secure_Contexts#when_is_a_context_considered_secure[considered a secure context]. As part of this, all cookies set by Keycloak will have the https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#secure[`Secure`] attribute by default.
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does this mean that some more update might need to be done in the documentation in relation to this? I can think of some update for the option http-enabled documented here https://www.keycloak.org/server/enabletls (as per my understanding http-enabled won't work correctly unless people are running on localhost or legacy cookies feature is enabled).

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does this mean that some more update might need to be done in the documentation in relation to this?

Yes, the documentation will have to be reviewed and modified in this regard. Once the implementation settles down that will be the next step.


You can restore this behavior by enabling the `legacy-cookies` feature. For example:

```
kc.[sh|bat] start --features legacy-cookies
```

This is however considered a temporary workaround, and will be removed in a future release. You should make sure to migrate your Keycloak instance to a secure context as soon as possible.

= New Welcome Page

The 'welcome' page that is shown when a user starts Keycloak for the first time, has been redesigned to provide a better setup experience and has been upgraded to the latest version of https://www.patternfly.org/[PatternFly]. The page layout has been simplified and now includes only a form to register the administrative user. After completing the registration, the user is redirected directly to the Administration Console.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -50,17 +50,17 @@ Feature:
admin2[:v1], authorization[:v1], ciba[:v1], client-policies[:v1],
client-secret-rotation[:v1], device-flow[:v1], docker[:v1], dpop[:v1],
dynamic-scopes[:v1], fips[:v1], impersonation[:v1], js-adapter[:v1], kerberos
[:v1], linkedin-oauth[:v1], multi-site[:v1], par[:v1], preview,
recovery-codes[:v1], scripts[:v1], step-up-authentication[:v1],
[:v1], legacy-cookies[:v1], linkedin-oauth[:v1], multi-site[:v1], par[:v1],
preview, recovery-codes[:v1], scripts[:v1], step-up-authentication[:v1],
token-exchange[:v1], transient-users[:v1], update-email[:v1], web-authn[:v1].
--features-disabled <feature>
Disables a set of one or more features. Possible values are: account-api,
account2, account3, admin-api, admin-fine-grained-authz, admin2,
authorization, ciba, client-policies, client-secret-rotation, device-flow,
docker, dpop, dynamic-scopes, fips, impersonation, js-adapter, kerberos,
linkedin-oauth, multi-site, par, preview, recovery-codes, scripts,
step-up-authentication, token-exchange, transient-users, update-email,
web-authn.
legacy-cookies, linkedin-oauth, multi-site, par, preview, recovery-codes,
scripts, step-up-authentication, token-exchange, transient-users,
update-email, web-authn.

HTTP(S):

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -61,17 +61,17 @@ Feature:
admin2[:v1], authorization[:v1], ciba[:v1], client-policies[:v1],
client-secret-rotation[:v1], device-flow[:v1], docker[:v1], dpop[:v1],
dynamic-scopes[:v1], fips[:v1], impersonation[:v1], js-adapter[:v1], kerberos
[:v1], linkedin-oauth[:v1], multi-site[:v1], par[:v1], preview,
recovery-codes[:v1], scripts[:v1], step-up-authentication[:v1],
[:v1], legacy-cookies[:v1], linkedin-oauth[:v1], multi-site[:v1], par[:v1],
preview, recovery-codes[:v1], scripts[:v1], step-up-authentication[:v1],
token-exchange[:v1], transient-users[:v1], update-email[:v1], web-authn[:v1].
--features-disabled <feature>
Disables a set of one or more features. Possible values are: account-api,
account2, account3, admin-api, admin-fine-grained-authz, admin2,
authorization, ciba, client-policies, client-secret-rotation, device-flow,
docker, dpop, dynamic-scopes, fips, impersonation, js-adapter, kerberos,
linkedin-oauth, multi-site, par, preview, recovery-codes, scripts,
step-up-authentication, token-exchange, transient-users, update-email,
web-authn.
legacy-cookies, linkedin-oauth, multi-site, par, preview, recovery-codes,
scripts, step-up-authentication, token-exchange, transient-users,
update-email, web-authn.

Config:

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -61,17 +61,17 @@ Feature:
admin2[:v1], authorization[:v1], ciba[:v1], client-policies[:v1],
client-secret-rotation[:v1], device-flow[:v1], docker[:v1], dpop[:v1],
dynamic-scopes[:v1], fips[:v1], impersonation[:v1], js-adapter[:v1], kerberos
[:v1], linkedin-oauth[:v1], multi-site[:v1], par[:v1], preview,
recovery-codes[:v1], scripts[:v1], step-up-authentication[:v1],
[:v1], legacy-cookies[:v1], linkedin-oauth[:v1], multi-site[:v1], par[:v1],
preview, recovery-codes[:v1], scripts[:v1], step-up-authentication[:v1],
token-exchange[:v1], transient-users[:v1], update-email[:v1], web-authn[:v1].
--features-disabled <feature>
Disables a set of one or more features. Possible values are: account-api,
account2, account3, admin-api, admin-fine-grained-authz, admin2,
authorization, ciba, client-policies, client-secret-rotation, device-flow,
docker, dpop, dynamic-scopes, fips, impersonation, js-adapter, kerberos,
linkedin-oauth, multi-site, par, preview, recovery-codes, scripts,
step-up-authentication, token-exchange, transient-users, update-email,
web-authn.
legacy-cookies, linkedin-oauth, multi-site, par, preview, recovery-codes,
scripts, step-up-authentication, token-exchange, transient-users,
update-email, web-authn.

Config:

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -61,17 +61,17 @@ Feature:
admin2[:v1], authorization[:v1], ciba[:v1], client-policies[:v1],
client-secret-rotation[:v1], device-flow[:v1], docker[:v1], dpop[:v1],
dynamic-scopes[:v1], fips[:v1], impersonation[:v1], js-adapter[:v1], kerberos
[:v1], linkedin-oauth[:v1], multi-site[:v1], par[:v1], preview,
recovery-codes[:v1], scripts[:v1], step-up-authentication[:v1],
[:v1], legacy-cookies[:v1], linkedin-oauth[:v1], multi-site[:v1], par[:v1],
preview, recovery-codes[:v1], scripts[:v1], step-up-authentication[:v1],
token-exchange[:v1], transient-users[:v1], update-email[:v1], web-authn[:v1].
--features-disabled <feature>
Disables a set of one or more features. Possible values are: account-api,
account2, account3, admin-api, admin-fine-grained-authz, admin2,
authorization, ciba, client-policies, client-secret-rotation, device-flow,
docker, dpop, dynamic-scopes, fips, impersonation, js-adapter, kerberos,
linkedin-oauth, multi-site, par, preview, recovery-codes, scripts,
step-up-authentication, token-exchange, transient-users, update-email,
web-authn.
legacy-cookies, linkedin-oauth, multi-site, par, preview, recovery-codes,
scripts, step-up-authentication, token-exchange, transient-users,
update-email, web-authn.

Config:

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -61,17 +61,17 @@ Feature:
admin2[:v1], authorization[:v1], ciba[:v1], client-policies[:v1],
client-secret-rotation[:v1], device-flow[:v1], docker[:v1], dpop[:v1],
dynamic-scopes[:v1], fips[:v1], impersonation[:v1], js-adapter[:v1], kerberos
[:v1], linkedin-oauth[:v1], multi-site[:v1], par[:v1], preview,
recovery-codes[:v1], scripts[:v1], step-up-authentication[:v1],
[:v1], legacy-cookies[:v1], linkedin-oauth[:v1], multi-site[:v1], par[:v1],
preview, recovery-codes[:v1], scripts[:v1], step-up-authentication[:v1],
token-exchange[:v1], transient-users[:v1], update-email[:v1], web-authn[:v1].
--features-disabled <feature>
Disables a set of one or more features. Possible values are: account-api,
account2, account3, admin-api, admin-fine-grained-authz, admin2,
authorization, ciba, client-policies, client-secret-rotation, device-flow,
docker, dpop, dynamic-scopes, fips, impersonation, js-adapter, kerberos,
linkedin-oauth, multi-site, par, preview, recovery-codes, scripts,
step-up-authentication, token-exchange, transient-users, update-email,
web-authn.
legacy-cookies, linkedin-oauth, multi-site, par, preview, recovery-codes,
scripts, step-up-authentication, token-exchange, transient-users,
update-email, web-authn.

Config:

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -77,17 +77,17 @@ Feature:
admin2[:v1], authorization[:v1], ciba[:v1], client-policies[:v1],
client-secret-rotation[:v1], device-flow[:v1], docker[:v1], dpop[:v1],
dynamic-scopes[:v1], fips[:v1], impersonation[:v1], js-adapter[:v1], kerberos
[:v1], linkedin-oauth[:v1], multi-site[:v1], par[:v1], preview,
recovery-codes[:v1], scripts[:v1], step-up-authentication[:v1],
[:v1], legacy-cookies[:v1], linkedin-oauth[:v1], multi-site[:v1], par[:v1],
preview, recovery-codes[:v1], scripts[:v1], step-up-authentication[:v1],
token-exchange[:v1], transient-users[:v1], update-email[:v1], web-authn[:v1].
--features-disabled <feature>
Disables a set of one or more features. Possible values are: account-api,
account2, account3, admin-api, admin-fine-grained-authz, admin2,
authorization, ciba, client-policies, client-secret-rotation, device-flow,
docker, dpop, dynamic-scopes, fips, impersonation, js-adapter, kerberos,
linkedin-oauth, multi-site, par, preview, recovery-codes, scripts,
step-up-authentication, token-exchange, transient-users, update-email,
web-authn.
legacy-cookies, linkedin-oauth, multi-site, par, preview, recovery-codes,
scripts, step-up-authentication, token-exchange, transient-users,
update-email, web-authn.

Hostname:

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -77,17 +77,17 @@ Feature:
admin2[:v1], authorization[:v1], ciba[:v1], client-policies[:v1],
client-secret-rotation[:v1], device-flow[:v1], docker[:v1], dpop[:v1],
dynamic-scopes[:v1], fips[:v1], impersonation[:v1], js-adapter[:v1], kerberos
[:v1], linkedin-oauth[:v1], multi-site[:v1], par[:v1], preview,
recovery-codes[:v1], scripts[:v1], step-up-authentication[:v1],
[:v1], legacy-cookies[:v1], linkedin-oauth[:v1], multi-site[:v1], par[:v1],
preview, recovery-codes[:v1], scripts[:v1], step-up-authentication[:v1],
token-exchange[:v1], transient-users[:v1], update-email[:v1], web-authn[:v1].
--features-disabled <feature>
Disables a set of one or more features. Possible values are: account-api,
account2, account3, admin-api, admin-fine-grained-authz, admin2,
authorization, ciba, client-policies, client-secret-rotation, device-flow,
docker, dpop, dynamic-scopes, fips, impersonation, js-adapter, kerberos,
linkedin-oauth, multi-site, par, preview, recovery-codes, scripts,
step-up-authentication, token-exchange, transient-users, update-email,
web-authn.
legacy-cookies, linkedin-oauth, multi-site, par, preview, recovery-codes,
scripts, step-up-authentication, token-exchange, transient-users,
update-email, web-authn.

Hostname:

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -78,17 +78,17 @@ Feature:
admin2[:v1], authorization[:v1], ciba[:v1], client-policies[:v1],
client-secret-rotation[:v1], device-flow[:v1], docker[:v1], dpop[:v1],
dynamic-scopes[:v1], fips[:v1], impersonation[:v1], js-adapter[:v1], kerberos
[:v1], linkedin-oauth[:v1], multi-site[:v1], par[:v1], preview,
recovery-codes[:v1], scripts[:v1], step-up-authentication[:v1],
[:v1], legacy-cookies[:v1], linkedin-oauth[:v1], multi-site[:v1], par[:v1],
preview, recovery-codes[:v1], scripts[:v1], step-up-authentication[:v1],
token-exchange[:v1], transient-users[:v1], update-email[:v1], web-authn[:v1].
--features-disabled <feature>
Disables a set of one or more features. Possible values are: account-api,
account2, account3, admin-api, admin-fine-grained-authz, admin2,
authorization, ciba, client-policies, client-secret-rotation, device-flow,
docker, dpop, dynamic-scopes, fips, impersonation, js-adapter, kerberos,
linkedin-oauth, multi-site, par, preview, recovery-codes, scripts,
step-up-authentication, token-exchange, transient-users, update-email,
web-authn.
legacy-cookies, linkedin-oauth, multi-site, par, preview, recovery-codes,
scripts, step-up-authentication, token-exchange, transient-users,
update-email, web-authn.

Hostname:

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -78,17 +78,17 @@ Feature:
admin2[:v1], authorization[:v1], ciba[:v1], client-policies[:v1],
client-secret-rotation[:v1], device-flow[:v1], docker[:v1], dpop[:v1],
dynamic-scopes[:v1], fips[:v1], impersonation[:v1], js-adapter[:v1], kerberos
[:v1], linkedin-oauth[:v1], multi-site[:v1], par[:v1], preview,
recovery-codes[:v1], scripts[:v1], step-up-authentication[:v1],
[:v1], legacy-cookies[:v1], linkedin-oauth[:v1], multi-site[:v1], par[:v1],
preview, recovery-codes[:v1], scripts[:v1], step-up-authentication[:v1],
token-exchange[:v1], transient-users[:v1], update-email[:v1], web-authn[:v1].
--features-disabled <feature>
Disables a set of one or more features. Possible values are: account-api,
account2, account3, admin-api, admin-fine-grained-authz, admin2,
authorization, ciba, client-policies, client-secret-rotation, device-flow,
docker, dpop, dynamic-scopes, fips, impersonation, js-adapter, kerberos,
linkedin-oauth, multi-site, par, preview, recovery-codes, scripts,
step-up-authentication, token-exchange, transient-users, update-email,
web-authn.
legacy-cookies, linkedin-oauth, multi-site, par, preview, recovery-codes,
scripts, step-up-authentication, token-exchange, transient-users,
update-email, web-authn.

Hostname:

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,8 @@
import org.keycloak.Token;
import org.keycloak.TokenCategory;
import org.keycloak.common.ClientConnection;
import org.keycloak.common.Profile;
import org.keycloak.common.util.ServerCookie;
import org.keycloak.models.ClientModel;
import org.keycloak.models.KeycloakContext;
import org.keycloak.models.KeycloakSession;
Expand Down Expand Up @@ -125,6 +127,12 @@ public static void setRestartCookie(KeycloakSession session, RealmModel realm, C
String encoded = session.tokens().encode(restart);
String path = AuthenticationManager.getRealmCookiePath(realm, uriInfo);
boolean secureOnly = realm.getSslRequired().isRequired(connection);
if (!Profile.isFeatureEnabled(Profile.Feature.LEGACY_COOKIES)) {
// Make the KC_RESTART cookie depend on the 'secure context' like the other authentication cookies to have a correct cookie detection later.
// The other authentication cookies will use the samesite attribute with 'None' which will trigger the secure context in `addCookie`.
// As we don't want to have samesite set to 'None' for KC_RESTART, set this one to true for secureOnly directly.
secureOnly = true;
}
CookieHelper.addCookie(KC_RESTART, encoded, path, null, null, -1, secureOnly, true, session);
}

Expand Down
Loading
0