The Folio Eureka Platform (henceforth referred to as Eureka for brevity) represents the next generation of Folio’s architecture which allows the project to operate at enterprise scale and expand its solution space. It seeks to replace custom-developed core components found in the original Folio architecture, with feature-rich, best-of-class, specialized open-source components. The need for this has become critical as Folio has become widely adopted, and particularly in ever increasing numbers in complex configurations such as consortia and national libraries.

The new components functionality in the following areas of single responsibility:

• Authentication (Keycloak)

• Authorization (Keycloak)

• Sidecars (Quarkus)

• Routing (Kong)

Additionally, Eureka fully embraces Application formalization. Applications being a formal structure that groups together existing modules and allows for their management as a set.

Open

Assumptions

A primary requirement for Eureka is that it be backward compatible with the existing set of Folio modules. In other words, the existing Folio modules could be used in their current form with the new platform. 

This includes the notion that Folio backend modules are agnostic to security enforcement. Modules will respond to requests with the assumption that the required permissions specified for any request will have been evaluated and enforced prior to calling the module’s API services.

Support for Application formalization further brings the requirement to include Application structures (e.g. application descriptors) and Manager Services.

Authentication

Eureka implements authentication with Keycloak. Keycloak provides full functionality with regards to Login forms, authenticating users, storing users and much more. Furthermore, keycloak supports different IdPs (Id Providers) and SSO protocols, including the simultaneous use of multiple IdPs

Keycloak

Keycloak is an open source (Apache v.2) Identity and Management solution. As such it provides the Folio Eureka platform with all its authentication needs, whether the need to authenticate within Folio or the needs of external single sign-on (SSO). Keycloak has built in broad support for most of the common authentication mechanisms and is extensible to allow connectors for more. 

User Management

With integration to Folio, Keycloak handles all the needs of user management for the purposes of authentication and authorization - i.e. the AuthUser. It leaves to Folio the responsibility to manage any metadata related to persons associated with users - i.e. the PersonUser. Practically speaking that means that Keycloak manages properties such as usernames, userids, passwords, and Folio manages the details such as first names, last names, email addresses, etc… 

The existing Folio User object currently combines both the AuthUser and PersonUser. With the Folio Eureka platform, the AuthUser portion of the existing User record is not used, only the PersonUser metadata is relevant. The Eureka Folio platform provides backwards compatibility with existing Folio modules and that includes the Users applications. Users continue to be managed within Folio, but relevant authentication data (AuthUsers) is provided through Keycloak.

Eureka introduces a new backend module: mod-users-keycloak. Its purpose is to provide a wrapper around mod-users and mod-users-bl so as to direct AuthUser concerns to Keycloak and PersonUser concerns to the existing mod-users module. It does this by providing equivalent API interfaces to those provided by mod-users. 

User Migration

The new mod-users-keycloak module also contains APIs to migrate users from the classic Folio installation to a Eureka Folio by configuring the required AuthUser data from mod-users storage to Keycloak storage . (Note that passwords are not migrated but will need to be reset since Eureka manages those in Keycloak.)

It should be noted that Eureka represents the opportunity to correct one of Folio long-standing flaws. Although patron and staff user records remain commingled in Eureka, only PersonUser records are commingled. Only those users who are meant to login to Folio itself (i.e. staff) will have AuthUser records maintained in Keycloak. Patron users will remain without a corresponding AuthUser record in Keycloak.

Login

When running on Eureka, Folio’s mod-login and mod-login-saml are no longer needed. The responsibility for authenticating users falls to Keycloak which provides its own login screen that is generated dynamically. (This is typical of any IdP.) Through the theming capabilities of Keycloak, the login screen has been configured to resemble the native Folio login screen and maintain a seamless user experience. 

Mod-login-keycloak

An additional Folio backend module has also been provided to replace mod-login for the Eureka platform: mod-login-keycloak. It provides an alternative implementation for the mod-login interfaces which are compatible with Keycloak and is responsible for providing authentication tokens. Similarly, it provides backward compatibility to mod-login interfaces for external integrations.

Authorization

Authorization Models

The authorization model found in Keycloak is significantly different from the bespoke authorization model developed in Folio. 

Classic Folio implements an API endpoint (interface) permission model for which the permissions are defined by the individual backend modules in a semi-consistent manner. The Folio model also allows for infinitely composable permissions in the form of permission sets, including UI permission sets which may be Folio (admin) user defined.

Keycloak provides a rigorous authorization model which is focused on resources. Upon this authorization model, different established access control models may be configured, such as: RBAC (role-based access control); ABAC (attributed-based access control); UBAC (user-based access control); and others.

The mismatch between Folio’s original and Eureka’s authorization models poses a challenge for maintaining backward compatibility with all existing Folio. An access control model is needed to provide the conciliation between the two authorization models. To this end an RBAC model, with elements of UBAC, was selected as best suited for this purpose. More on Roles and Capabilities below.

Folio Module Permissions

The authorization model in Folio is API centric. Each backend module in Folio is responsible for defining permissions and those are then enforced by the platform’s authorization components.

Users are directly assigned Folio Permissions either as singletons or as part of a nested Folio Permission Set. The management of such assignments can be challenging as it is not always apparent what access is being granted with many levels of nesting. Although an API interface may be RESTful, the specific resource and scope granted by a related permission can only be inferred from the permission declaration.

Open

While very flexible and optimally developer friendly, this approach comes with some problems.

• The permission naming conventions are only recommendations and not strictly enforced. 

• Folio provides many non-RESTful APIs (RPC a.k.a “action” APIs)

• Different modules will implement permissions with different levels of granularity (sometimes excessively)

• Folio PermissionSets may be nested to unlimited degrees, which results in: complex evaluation chains; duplicate permissions; reused permissions; difficulty in assessing the level of access actually granted to individual users.

Eureka Roles and Capabilities

Eureka implements Roles and Capabilities which are a good match for the permission model maintained internally by Keycloak, which is resource centric.

Keycloak Permissions are a mechanism to associate a Resource with a Scope and a User. Furthermore, Keycloak also supports Policies which dictate the conditions under which the Permission must be met. In order to avoid confusion with the overuse of the term “permissions”, Folio refers to Keycloak Permissions as “Capabilities” to avoid confusion with Folio Permissions.

A Keycloak Permission/Capability effectively has Users (indirectly via a User Policy). Conceptually the inverse of Folio’s model.

Roles are native structures in Keycloak. Keycloak users may be assigned Keycloak Roles Unlike classic Folio PermissionSets, membership in a Keycloak Role does not convey permanent permission assignments. Rather, Keycloak Roles are first class objects and are associated with Role Policies. These and other policies are evaluated during authorization as conditions to allow the capability provided by a Keycloak Permission/Capability. Specifically, if a Keycloak Permission contains a required Role Policy, authorization will only be granted to the associated User if the user possesses the requested role.

Roles and Capabilities are intended to be supported by Folio regardless of the choice of platform (Eureka or Classic/Okapi). Since those concepts are closely related to the authentication and authorization models, Eureka supplies alternate versions for the key modules involved.

• mod-roles-keycloak adds role management to Eureka
  (mod-roles would need to be developed for Okapi-based platforms)

• mod-consortia-keycloak is the Eureka version of mod-consortia.

Keycloak supports a number of different Policies including: Role Policies; User Policies; Time-based Policies. 

The assignment of Roles and Capabilities is managed entirely from within Folio by administrators. The equivalent Folio structures are automatically synchronized with their Keycloak counterparts. In particular, Role and User Policies in Keycloak are managed by the system in response to Capabilities being assigned to Roles, or directly to Users, within Folio. Capabilities (and CapabilitySets) are managed by the platform according to what the modules in Applications support. Roles may be created by Folio administrators.

The implementation of Keycloak in Eureka is not a pure RBAC (Role Based Access Control) model. Eureka Folio supports the direct assignment of Capabilities to Users.

Sidecars

A sidecar is an architectural pattern by which a component is deployed into a separate process or container to extend the capabilities of another component. It is closely connected to the component to which it is paired, thus leading to the motorcycle sidecar metaphor.

In the case of Eureka, sidecars are used to provide authorization functionality for modules. In Folio, modules do not normally implement authorization, rather it is expected that this will be enforced by the platform prior to the module receiving the request. In effect the authorization barrier sits outside and in front of the module. Eureka uses the Quarkus framework (Apache v.2) to implement sidecars.

In a classic Okapi-based platform, it is Okapi which acts as the authorization barrier. It is responsible for contacting the authorization components (mod-authtoken, mod-permissions) to validate a request prior to proxying the request to the module which provides the desired API endpoint. 

In Eureka, there is a clearer separation of concerns. The API gateway (Kong) is only an API gateway. The authorization barrier is provided by the sidecars which are closely coupled to the modules they support.

Moving the authorization barrier closer to the modules (i.e. in the sidecars) allows for a more decentralized traffic flow within Folio, since an API call must begin at the authorization barrier. If a module needs to make a secondary call to another module’s API then it is possible to directly call from sidecar to sidecar. Whereas in a classic Folio platform, all such calls must be routed through the authorization barrier located in Okapi. 

API Gateway

The Eureka platform selected Kong Gateway as its API gateway. It is a lightweight, fast, and flexible cloud-native API gateway written in Lua. Kong Gateway is a reverse proxy that lets manage, configure, and route requests to APIs. It runs in front of any RESTful API and can be extended through modules and plugins. It’s designed to run on decentralized architectures, including hybrid-cloud and multi-cloud deployments.

Specifically, Eureka uses Kong Gateway (OSS), the Free version, not to be confused with Plus or Enterprise modes/versions. It provides basic API gateway functionality and open-source plugins. It can be managed with the Kong Manager UI bundled with the Kong distribution. Eureka’s Manager Services dynamically configures the open-source Gateway using Kong’s Admin API.

Kong Gateway only provides API Gateway functionality which reinforces the separation of concerns philosophy of the Eureka design.

The Big Picture

Authorization Flows

The following two diagrams provide a visual comparison of the authorization flows found in Eureka and Okapi based Folio platforms. They describe the components involved and the chain of calls required for a user to make a typical API access from the Folio UI.

Administration

Provisioning a Eureka Folio Deployment

Hosting a Eureka deployment requires its own set of steps to make the system available to tenants.

New 3rd Party Components

In addition to 3rd party components required for all Folio deployments (PostgreSQL, Kafka, Opensearch) Eureka requires the preliminary deployment of the new components

• Keycloak: for AuthN/Z functionality

• Kong Gateway: as the API Gateway

Eureka Manager Services

After the deployment of actual components (including Applications) for a Folio System, it is necessary to provision the system to make it functional for tenants to use. At the most basic level this reduces to managing the following: registering Application, registering Tenants; and enabling specific Applications for each Tenant. Provisioning is achieved with the Eureka Manager Services. 

A Folio system must be made aware of available applications. This is the responsibility of the Application Manager service. This is done once for the entire system, to potentially be enabled for any Tenants that may reside in that system.

At this time the Application Manager will create a “Service” in Kong to represent the Application that has been registered.

The system must be told of the Tenants which will reside within it. This is the responsibility of Tenant Manager service. It will register the tenant, and also create a “Realm” and “Client” for the tenant in Keycloak which will provide the context for any authN/Z settings for that tenant going forward.

Once Applications and Tenants have been defined in the Folio system, it is possible to use the Tenant Entitlement Manager service (Entitlement Manager for short) to enable specific Applications for each Tenant.

Eureka is a late-binding system, where the last elements of authN/Z infrastructure for a Tenant are only created at the time that an Application has been enabled for that Tenant.

Provisioning: Putting it All Together

The following diagram illustrates how all the different pieces participate in tenant provisioning.

Adding Applications into Eureka

Adding Applications is accomplished through the Application Manager. This dedicated component is accessible only via API and used by the hosting organization to make the system aware of a new application, or a new version of an existing application, in the system.

Two distinct sets of artifacts are consumed by the Application Manager.

1. Application Descriptors (and their nested Module Descriptors). These are captured and stored by the Application Manager for further use. An Application Descriptor contains only general (static) metadata describing the Application but does not contain deployment specific metadata. 

2. Discovery information. These are deployment specific metadata relating to the applications and their modules. In particular they must contain the URL path for accessing APIs. 

With these two sets of artifacts, the Application Manager will create (or update) a Service in Kong Gateway. A “Service” is Kong’s abstraction of an Application. Actual Routes to APIs will be added subsequently by the (Tenant) Entitlement Manager.

Adding Tenants to Eureka

Folio tenants are defined and maintained in the Tenant Manager. This dedicated component is also accessible only via API and used by the hosting organization. It is not a Folio user-facing component. 

The Tenant Manager allows Eureka to be aware of the Tenants that exist in the system. The tenant details are stored by the Tenant Manager in its dedicated storage. The Tenant Manager uses the tenant details to create a Realm in Keycloak which will be dedicated to that tenant.

Making Applications Available to Tenants

The final manager is the Tenant Entitlement Manager (or Entitlement Manager for short). Its role is to enable (or disable), for a specific tenant, Applications that have been defined in the system. Furthermore, it also completes the tenant-specific configuration of an Application. The Entitlement Manager is only accessible via API.

1. The Entitlement Manager retrieves the Module Descriptors from the Application Manager and uses the information they contain to create equivalent Resources and Scopes (i.e. actions) - in the appropriate Keycloak Client -  in the Realm for that tenant.

2. Then the Entitlement Manager adds the specific routes in Kong Gateway’s Service for the Application. Routes are created with an X-Okapi-Tenant attribute for each tenant (multi-tenancy.support).

3. The entitlement configuration is stored locally in the Entitlement Manager

4. The Entitlement Manager posts messages to Kafka to be consumed by Folio to synchronize the equivalent data structures there. In particular Folio will create suitable Capabilities, which can be bundled into Roles for later assignment to Folio users by Library Administrators.

5. Messages posted to Kafka are also used to update Sidecars of entitlement changes.

Adding Users to Tenants

Keycloak is responsible for Eureka’s authentication and authorization functionality. For this purpose, it needs to maintain a user record within itself. 

As always, Folio users are managed within Folio’s Users Application. When used in Eureka that application includes an additional module that is responsible for coordination with Keycloak. It provides those user record fields relevant to authentication and authorization (i.e. “AuthUser” data) to Keycloak and brokers other calls to the existing mod-users module.

Further Reading

The following documentation may be of interest.

• Keycloak Documentation

• Kong Gateway Documentation

• Application Descriptor Repo on GitHub

• WOLFcon23: Folio Platforms

• WOLFcon23: Folio And Next Level AuthN/Z