/
Sunflower (R1 2025) Platform Changes

Sunflower (R1 2025) Platform Changes

General

The Sunflower release is the first official Folio release utilizing the Eureka platform. The purpose of this page is to highlight the noteworthy changes associated with this. For more information on the Eureka platform, please see https://folio-org.atlassian.net/wiki/spaces/PLATFORM/pages/193134643.

User-facing Changes

Users must reset their passwords

Because user credentials are now being stored in Keycloak, and these cannot be copied over from mod-login, where they were previously stored, it's necessary for all users to set their credentials prior to their first login after the upgrade to Sunflower.  This only applies to users who are using "native" folio login; it does not apply to SSO.  In most cases, the easiest way to do this is to instruct users to use the "Forgot password" link on the login screen.  Users will be allowed to use the same password that they had in Ramsons.

image-20250516-170207.png

Contact Person:  @Craig McNally

External integrations

External integrations with Folio (Scripts/tools/webapp/automation/etc.) are for the most part unaffected by the adoption of the Eureka platform. Broadly, these integrations happen in one of two ways:

  1. Via edge modules

    1. Edge modules need to be configured to point to Kong (the new API gateway) rather than Okapi. This is achieved via the “okapi_url” system property. See https://github.com/folio-org/edge-common.

    2. One option you may consider is to handle this via DNS, e.g. point the existing “okapi” URL to Kong and restart your edge modules.

    3. You might also consider adopting a more generic hostname prefix such as “api-” instead of “okapi-” or “kong-”.

  2. Via directly calling Folio backend APIs

    1. Similar to above, the only change required here is to point your integrations at the new API gateway (kong) instead of Okapi. The same (DNS) considerations above apply here as well.

    2. Request headers like x-okapi-* are still supported in Eureka, so no changes are required related to these.

    3. The same login APIs are supported in Eureka, e.g. POST /authn/login-with-expiry

      1. The POST /bl-users/login-with-expiry is technically still supported on Eureka, but the permissions section of the response is misleading. This endpoint still retreives information from mod-permissions, which will not reflect the user’s actual privileges, which is now managed by mod-roles-keycloak. The suggestion is to use POST /authn/login-with-expiry in conjunction with GET /users-keycloak/_self. The bl-users endpoint will either be updated to retrieve information from mod-roles-keycloak, or deprecated in Trillium.

Contact Person: @Craig McNally

Roles and capabilities

Please review FOLIO help documentation for information on roles and capabilities management.

AuthUser promotion

With the introduction of Keycloak, some user information needs to reside in Folio, and some in Keycloak. The term AuthUser refers to user records in Keycloak, composed primarily of data required for authentication and authorization, but also of some ancillary data to identify the user and facilitate administration / user mgmt. However, AuthUser records are not required for all users in the system. In fact, the vast majority of users in Folio represent patrons or other people who are users in the system, but not users of the system. When creating users in Folio, a user record will be created in mod-users as usual. An AuthUser record will not be created until needed. Specifically, when a role is assigned to the user, or when credentials are assigned to the user. When performing these actions you may be prompted to raise awareness. The confirmation dialog will look similar to this:

image-20250516-183654.png

NOTE: Removing all roles and/or credentials from a user in Folio will not result in their AuthUser record being removed. However, deleting a user in Folio will remove the corresponding AuthUser record if one exists.

Contact Person:  @Craig McNally

Login page URL

Prior to Sunflower the login page was provided by stripes. Starting with Sunflower and going forward, the login page is now provided by Keycloak. The page should have the same familiar look and feel, but the URL will look different than it has in previous releases. E.g. If you navigate to https://bugfest-sunflower.int.aws.folio.org, you will land on a login page with a URL that looks something like: https://keycloak-sebf.int.aws.folio.org/realms/fs09000000/protocol/openid-connect/auth?client_id=fs09000000-application&response_type=code&redirect_uri=https://bugfest-sunflower.int.aws.folio.org/oidc-landing&scope=openid

Contact Person:  @Craig McNally

Idle session timeouts

A new “idle session timeout” feature has been introduced in Sunflower. The purpose of this feature is to prevent security/privacy breaches which stem from someone who is logged into Folio stepping away from their computer w/o locking their screen. After some configurable period of inactivity (mouse clicks, keystrokes, etc.), a warning dialog will be shown to the user indicating that their session will be ended (along with a countdown) due to inactivity. If the dialog is dismissed, the session will remain active, and the idle timer will be reset. See the corresponding section in the “System Operator-facing Changes” part of this document below for more information.

image-20250516-202336.png

Contact Person:  @Craig McNally

System Operator-facing Changes

MinIO

If using MinIO upgrade it as MinIO supports the latest version only (support policy).

Contact person: @Julian Ladisch

Kafka

FOLIO works with any supported Kafka version:

Apache Kafka publishes three minor versions per year and supports the latest three minor versions (end-of-life policy) resulting in about a year of support for a minor version. As of 2025-09-02 Apache Kafka supports 3.9.*, 4.0.*, and 4.1.*.

Amazon Managed Streaming for Apache Kafka (Amazon MSK) supports a minor version for about two years (supported versions). As of 2025-09-02 Amazon MSK supports 3.6.0, 3.7.*, 3.8.*, 3.9.*, 4.0.*.

FOLIO’s snapshot reference environments always use the latest Apache Kafka version (docker-compose).

Contact person: @Julian Ladisch

New technology stack/architecture

With Sunflower, and the adoption of the Eureka platform come significant changes to the Folio architecture and technology stack. Several components have been removed and their responsibilities distributed to new components.

Contact Person:  @Craig McNally

Configuration of RTR on Eureka

Refresh Token Rotation (RTR) was introduced in a previous release, but how it’s configured changes with the adoption of Eureka. Parts of this remain in stripes-config.js and other parts have moved to Keycloak. For full details see https://folio-org.atlassian.net/wiki/spaces/FOLIJET/pages/542670880.

Contact Person:  @Craig McNally

Configuration of SSO on Eureka

In prior releases SSO was handled via the mod-login-saml module. Going forward with Eureka, this is now handled by Keycloak. As such, the configuration has changed. At this moment, SSO configuration directly in Folio (e.g. via Settings → Tenant → SSO Settings) is no longer available. For full details see https://folio-org.atlassian.net/wiki/spaces/FOLIJET/pages/1408263.

N.B. Not all users in Folio will exist in Keycloak. This means unless a user is assigned one or more roles, they will not be able to login via SSO. See the AuthUser Promotion section above for additional information on AuthUsers (User records in Keycloak) and when they’re created.

Contact Person:  @Craig McNally

Enhanced SSO support/functionality

As mentioned above, SSO is now handled by Keycloak. One benefit of this is greater flexibility and functionality, including:

  • Support for multiple SSO identity providers for a given tenant. Setting up a second, third, fourth SSO identity provider is the same as repeating the process documented at https://folio-org.atlassian.net/wiki/spaces/FOLIJET/pages/1408263.

  • Single Logout (SLO) support. This is configured on a per-IdP basis and managed directly in they Keycloak Admin Console:

    image-20250516-173231.png

  • Numerous options related to signing, encryption, validation, etc. These can be configured on a per-IdP basis and managed directly in they Keycloak Admin Console:

    image-20250516-173114.png

Contact Person:  @Craig McNally

Role based access controls

Eureka replaces the permission-based access controls used in previous releases with role-based access controls. This impacts both system operators as well as library administrators responsible for managing roles and their assignments. For additional details see https://folio-org.atlassian.net/wiki/spaces/UM/pages/789807108

Contact Person:  @Craig McNally

Migration from Okapi-based Folio to Eureka-based Folio

TODO Kitfox/@Lee Braginsky - Link to Migration APIs docs, relevant sections of deployment and roles mgmt docs, etc.

Formalized applications

One of the core concepts in Eureka is formalized applications. In simplest terms an application is a logical grouping of modules (spanning all module types - front-end, back-end, edge, etc). Much of the provisioning and management of Eureka-based Folio happens at the application-level, as opposed to the module level as it was in previous releases. For additional details see https://folio-org.atlassian.net/wiki/spaces/TC/pages/349765637.

Contact Person:  @Craig McNally

Idle session timeouts

The idle session timeout feature described in the user-facing changes section above is configured in stripes-config.js. The default values here may be more strict than what some libraries would prefer, so system administrators should be aware of this, and how to make the necessary adjustments. See https://folio-org.atlassian.net/wiki/spaces/DEV/pages/46858271 for additional details.

Contact Person: @Zak_Burke