folio-module-sidecar

Owned by Pavel Filippov
Last updated: Oct 03, 2024
4 min read

Overview

The Sidecar architectural pattern is a design pattern used in software engineering to enhance or extend the functionality of a main application by attaching a secondary application or service to it. This secondary application, known as the "sidecar," runs alongside the main application and provides supporting features such as monitoring, logging, configuration, or networking services.

In this pattern, the sidecar is tightly coupled with the main application, sharing the same lifecycle and always deployed together. However, the sidecar's runtime environment remains independent, allowing it to be developed and maintained separately from the main application.

The Sidecar pattern is commonly used in microservices architectures, where each microservice can have its sidecar to handle cross-cutting concerns. This allows developers to implement these concerns consistently and avoid duplicating code across services. It also simplifies the main application code by offloading auxiliary tasks to the sidecar.

folio-module-sidecar provides the following functionality:

  1. Ingress requests handling
    request from API Gateway to specific Folio module

  2. Egress requests handling
    requests from one Folio module to another Folio module

  3. Authentication
    based on x-okapi-token or Authorization header

  4. Authorization
    based on Keycloak policies and permissions

  5. Self-requests
    based on x-okapi-sidecar-signature header value

  6. User impersonation
    Consortia support and cross-tenant requests

Sidecar initializing and runtime

Bootstrap process

During startup, folio-module-sidecar calls the following modules according to the sequence diagram:

image-20241003-134839.png
Sidecar bootstrap (initialization) flow

 

@startuml title "Sidecar bootstrap flow" hide footbox autonumber skinparam sequenceMessageAlign right skinparam sequenceMessageAlign right skinparam responseMessageBelowArrow true participant "Sidecar" as sidecar #5CCCCC participant "mgr-applications" as mgrApplications #FFD073 participant "mgr-tenants" as mgrTenants #FFD073 participant "mgr-tenant-entitlements" as mgrTenantEntitlements #FFD073 sidecar -> mgrApplications ++#FFD073: GET /modules/:moduleId note left of mgrApplications //Retrieves bootstrap information for sidecar.// //This information includes set of module routing// //entries and a set of egress routing entries// //based on required and optional interfaces,// //specified in the module descriptor// end note sidecar <-- mgrApplications --: 200 Ok sidecar -> mgrTenantEntitlements ++#FFD073: GET /entitlements/modules/:moduleId note left of mgrTenantEntitlements //Retrieves tenant entitlements(tenantId + applicationId) by module id// end note sidecar <-- mgrTenantEntitlements -- : 200 Ok sidecar -> mgrTenants ++#FFD073: GET /tenants?query=id==(:tenantIds) note left of mgrTenants //Retrieves tenant information in batches based// //on data retrieved from "mgr-tenant-entitlements"// end note sidecar <-- mgrTenants -- : 200 Ok @enduml

Sidecar, as shown on the diagram, calls mgr-components to be part of the Eureka system:

  1. It calls mgr-applications to construct egress and egress request caches, that store routing entries from module descriptor by id and for other related module descriptors, defined by optional and required interface dependencies.

    1. For egress requests there is a support to call API Gateway if the egress routing entry is not matched, it is controlled via environment variables: SIDECAR_FORWARD_UNKNOWN_REQUESTS and SIDECAR_FORWARD_UNKNOWN_REQUESTS_DESTINATION which by default pointing to the Kong API Gateway.

  2. It calls mgr-tenant-entitlements and mgr-tenants to find out for which tenants sidecar is enabled, requests, containing tenant id, that is not cached in sidecar will be rejected with 400 Bad Request Application is not enabled for tenant: {{tenantName}}

Sidecar Runtime

During runtime, folio-module-sidecar receives events from the message bus (Apache Kafka) containing:

  1. Tenant entitlement, revoke, and upgrade events. This information is used to update the active tenant's cache to support the following cases:

    1. During the application uninstallation (revoke) - all related sidecars must be disabled for the affected tenant

    2. During the application upgrade process - all upgraded (new) modules must be enabled for the tenant and all deprecated modules must be disabled for the affected tenant

  2. Discovery information change information:

    1. Sidecar can update an egress request location cache if discovery information is changed in mgr-applications

  3. Sidecar also caches authorized requests for the JWT using session_state claim if present until the token is expired:

    1. If a user performs logout or logout all operations - folio-module-sidecar can clean affected caches and forbid the next request using cached JWT

Sidecar filters

The filter approach is a way to intercept and process HTTP requests and responses before they reach a point when the request must be forwarded to the underlying Folio module. In request they are responsible for all functionality and they are executed in chain.

Ingress request filters

1. SelfRequestFilte

Description

This filter is responsible for validating if a request is a module self-request. These types of requests are allowed without authentication and authorization.

Skip Conditions

Never

2. KeycloakSystemJwtFilter

Description

Retrieves and parses system token, issued by keycloak in another sidecar. This functionality was added to support module-to-module requests when the system user is not defined by the module or not all permissions are present in the existing user JWT, including tenant and module permissions.

System JWT is validated using publicly available JWKs public certificates, provided by Keycloak.

io.smallrye:smallrye-jwt provides a JWTParser that is able to retrieve public keys automatically and supports the ability to cache and refresh JWKs. It’s controlled by environment variables KC_JWKS_REFRESH_INTERVAL and KC_FORCED_JWKS_REFRESH_INTERVAL

This token is issued using client credential flow, Keycloak client is created during tenant and realm initialization in mgr-tenants and controlled by the following environment variables:

  1. KC_SERVICE_CLIENT_ID Tenant-specific client ID for authenticating module-to-module requests.

  2. service client password is stored in SecureStore: AWS Parameter Store, HashiCorp Vault or provided via an ephemeral (dev mode) store configured by system properties.

Skip conditions

  1. if a matched routing entry with interfaceType is equal to system

  2. If routing entry does not require any permission

  3. If a request does not contain a value in X-System-Token header

3. KeycloakJwtFilter

Description

Parses the JWT from x-okapi-token or Authorization headers.

User or system user JWT is validated using publicly available JWKs public certificates, provided by Keycloak.

io.smallrye:smallrye-jwt provides a JWTParser that is able to retrieve public keys automatically and supports the ability to cache and refresh JWKs. It’s controlled by environment variables KC_JWKS_REFRESH_INTERVAL and KC_FORCED_JWKS_REFRESH_INTERVAL

Also, support “dummy” token for mod-pubsub:

When a module (for example mod-circulation) registers events in mod-pubsub the request is sent without x-okapi-token (as we don't pass it during tenant install), mod-pubsub-client lib adds a default "dummy" token to such requests and therefore sidecar should be able to process such request.
Skip conditions

  1. A routing entry matched with interfaceType is equal to system, but interface id is not equal to _timer

4. KeycloakTenantFilter

Description

  1. Resolves a tenant name from system JWT and user JWT.

  2. Allows cross-tenant requests, if environment variable ALLOW_CROSS_TENANT_REQUESTS for sidecar is set to true.

  3. Validates that x-okapi-token and x-system-token are issued for the same tenant (skipped if #2 is defined)

  4. Validates that x-okapi-tenant is the same as resolved tenant id (skipped if #2 is defined)

Skip conditions

  1. an interface id is not equal to _timer

  2. interfaceType is equal to system

  3. Self request

  4. Routing entry without required permissions

5. TenantFilter

6. KeycloakImpersonationFilter

7. KeycloakAuthorizationFilter

8. SidecarSignatureFilter

9. DesiredPermissionsFilter