Skip to content
Draft
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
13 changes: 9 additions & 4 deletions docs/documentation/release_notes/topics/27_0_0.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -33,12 +33,17 @@ The `UPDATE_CREDENTIAL` events emitted by built-in required actions now carry th

= Themes

== Login and welcome UI upgraded to PatternFly 6
== User interfaces upgraded to PatternFly 6

The built-in login theme is now `keycloak.v3`, based on PatternFly 6. The previous `keycloak.v2` login theme has been removed.
The built-in welcome theme also uses PatternFly 6.
{project_name} 27 upgrades the built-in login, welcome, Account Console, and Admin Console UIs to PatternFly 6:

Realms that explicitly used `keycloak.v2` are migrated to `keycloak.v3` during upgrade. If you maintain a custom login theme based on `keycloak.v2`, or a custom welcome theme based on PatternFly 5, see the link:{upgradingguide_link}[{upgradingguide_name}] for migration steps.
* Login theme is now `keycloak.v3` (replaces `keycloak.v2`).
* Welcome theme uses PatternFly 6 markup and styles.
* Account Console theme is now `keycloak.v4` (replaces `keycloak.v3`).
* Admin Console theme is now `keycloak.v3` (replaces `keycloak.v2`).

Built-in realm themes are migrated automatically during upgrade.
If you maintain custom themes, see the link:{upgradingguide_link}[{upgradingguide_name}] and *Migrating custom themes to PatternFly 6* in the https://www.keycloak.org/guides#migration[Migration guides].

== OID4VP verifier infers the DCQL query from mappers (experimental)

Expand Down
73 changes: 73 additions & 0 deletions docs/documentation/upgrading/topics/changes/changes-27_0_0.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -71,6 +71,79 @@ node misc/scripts/migrate-login-theme-pf5-to-pf6.mjs --theme-path /path/to/your/
Run the script in dry-run mode first, review the generated report, and then rerun with `--apply` when ready.
After migration, validate your customizations manually for light and dark mode, social provider buttons, and custom CSS overrides.

For a full walkthrough covering login, welcome, account, and admin custom themes, see *Migrating custom themes to PatternFly 6* in the https://www.keycloak.org/guides#migration[Migration guides].

=== Account Console moved to `keycloak.v4` and PatternFly 6
// https://github.com/keycloak/keycloak/issues/52344

The built-in Account Console is now the `keycloak.v4` theme, based on PatternFly 6.
The previous `keycloak.v3` Account Console theme and the `account:v3` feature value have been removed.

For new realms, `keycloak.v4` is the default Account Console theme when the `account:v4` feature is enabled (the default).
Existing realms that explicitly use `keycloak`, `keycloak.v2`, or `keycloak.v3` as the account theme are migrated to `keycloak.v4` during upgrade.
Custom account themes are left unchanged.

If you maintain a custom Account Console theme that extends or copies `keycloak.v3`, migrate it to PatternFly 6 before switching its parent to `keycloak.v4`.

The helper script below migrates an Account UI *source checkout* (a directory whose `package.json` name is `@keycloak/keycloak-account-ui`), not an installed or inherited theme directory under `themes/`.
Pass the path of that source package with `--app-path`:

[source,bash]
----
node misc/scripts/migrate-account-ui-pf5-to-pf6.mjs --app-path /path/to/keycloak-account-ui
----

Run the script in dry-run mode first, review the generated report, and then rerun with `--apply` when ready.
For CSS-only custom themes that only override resources of `keycloak.v3`, update PatternFly 5 classes and CSS variables to PatternFly 6 manually; the helper does not process those theme directories.
If you explicitly enable `account:v3` (for example `--features=account:v3` or `KC_FEATURES=account:v3`), replace it with `account:v4`, or remove the entry because `account:v4` is enabled by default.
Servers that still request `account:v3` fail feature validation at startup.

See also *Migrating custom themes to PatternFly 6* in the https://www.keycloak.org/guides#migration[Migration guides].

=== Admin console migrated to PatternFly 6
// https://github.com/keycloak/keycloak/issues/52343

The admin console has been upgraded to PatternFly 6 and the built-in admin theme has been renamed from `keycloak.v2` to `keycloak.v3`.
Realms that explicitly use the built-in admin theme are migrated automatically.
Custom admin themes must be updated manually.

If your custom admin theme extends the built-in theme, update `theme.properties`:

[source,properties]
----
# Before
parent=keycloak.v2

# After
parent=keycloak.v3
----

If your theme extends `rh-sso.v2`, change the parent to `rh-sso.v3` if available in your distribution, or extend `keycloak.v3` instead.

If you explicitly enable or disable the admin console through startup features, replace `admin:v2` with `admin:v3` in `--features` or `--features-disabled`.
The `admin:v2` feature flag was removed with the PatternFly 6 admin console migration.

The admin console now uses PatternFly 6 React components and design tokens.
Custom admin themes that bundle their own React components should:

* Upgrade `@patternfly/react-core` and related packages to PatternFly 6.
* Replace deprecated PatternFly 5 APIs removed during the migration, including modal variants, `Chip` (use `Label`), and drag-and-drop helpers that depended on removed packages.
* Update CSS class prefixes from `pf-v5-*` to `pf-v6-*` and replace `--pf-v5-global--*` variables with the corresponding `--pf-t--global--*` tokens where applicable.

To assist with migrating an Admin UI source checkout, use:

[source,bash]
----
node misc/scripts/migrate-admin-ui-pf5-to-pf6.mjs --app-path /path/to/keycloak-admin-ui
----

Run the script in dry-run mode first, review the generated report, and then rerun with `--apply` when ready.

The built-in quick-theme generator now produces admin themes with `parent=keycloak.v3`.
Download a new quick theme after upgrading if you previously generated one for `keycloak.v2`.

See also *Migrating custom themes to PatternFly 6* in the https://www.keycloak.org/guides#migration[Migration guides].

=== OIDC identity providers accept a single issuer
// https://github.com/keycloak/keycloak/issues/54458

Expand Down
2 changes: 2 additions & 0 deletions docs/documentation/upgrading/topics/migrate_themes.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,8 @@

If you created custom themes, those themes must be migrated to the new server. Also, any changes to the built-in themes might need to be reflected in your custom themes, depending on which aspects you customized.

For the PatternFly 6 upgrade in {project_name} 27 (login, welcome, Account Console, and Admin Console), see *Migrating custom themes to PatternFly 6* in the https://www.keycloak.org/guides#migration[Migration guides] in addition to the version-specific notes in <<migration-changes,Migration Changes>>.

.Procedure

. Copy your custom themes from the old server `themes` directory to the new server `themes` directory.
Expand Down
1 change: 1 addition & 0 deletions docs/guides/attributes.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,7 @@
:quickstartRepo_dir: keycloak-quickstarts
:securing_apps_link: https://www.keycloak.org/guides#securing-apps
:upgrading_guide_link: {project_doc_base_url}/upgrading/
:upgradingguide_name: Upgrading Guide
:migrate_db: {upgrading_guide_link}#_migrate_db
:developerguide_userstoragespi_link: {developerguide_link}#_user-storage-spi
:developerguide_userstoragespi_name: User Storage SPI
Expand Down
Loading
Loading