EUREKA-733 Spike - Investigate TLS Without FIPS Compliance in FOLIO Eureka

Jira Ticket: EUREKA-733
Objective:
Enable TLS support for the FOLIO Eureka platform without requiring FIPS-compliant images, focusing on ease of deployment outside U.S. government environments.

Background

FOLIO Eureka supports TLS with FIPS compliance by using Red Hat base images and Bouncy Castle as the SSL engine. However, in most environments, standard TLS (e.g., TLSv1.2) using Java's built-in SSL capabilities is sufficient and more lightweight. This spike evaluates using the default Java embedded SSL without external dependencies.

Implementation Overview

Sidecars (Quarkus-based)

Sidecar modules support TLS. Set the following environment variables:

SC_TLS_KEYSTORE_PATH: "keystore.jks"
SC_TLS_KEYSTORE_PASSWORD: "secure123"
SC_TLS_KEYSTORE_KEY_PASSWORD: "secure123"
SC_TLS_KEY_STORE_FILE_TYPE: "PKCS12"
SC_TLS_KEY_STORE_PROVIDER: "SUN"
WEB_CLIENT_TLS_VERIFY_HOSTNAME: false
SC_CLIENT_TLS_TRUSTSTORE_PATH: "keystore.jks"
SC_CLIENT_TLS_TRUSTSTORE_PASSWORD: "secure123"
SC_CLIENT_TLS_TRUSTSTORE_FILE_TYPE: "PKCS12"
SC_CLIENT_TLS_TRUSTSTORE_PROVIDER: "SUN"
SC_CLIENT_TLS_ENABLED : true
KC_CLIENT_TLS_TRUSTSTORE_PATH: "keystore.jks"
KC_CLIENT_TLS_TRUSTSTORE_PASSWORD: "secure123"
KC_CLIENT_TLS_TRUSTSTORE_FILE_TYPE: "PKCS12"
KC_CLIENT_TLS_TRUSTSTORE_PROVIDER: "SUN"
KC_CLIENT_TLS_ENABLED : true
GW_CLIENT_TLS_TRUSTSTORE_PATH: "keystore.jks"
GW_CLIENT_TLS_TRUSTSTORE_PASSWORD: "secure123"
GW_CLIENT_TLS_TRUSTSTORE_FILE_TYPE: "PKCS12"
GW_CLIENT_TLS_TRUSTSTORE_PROVIDER: "SUN"
GW_CLIENT_TLS_ENABLED : true
QUARKUS_HTTP_SSL_PROTOCOLS : "TLSv1.2"

Edge Modules

KC_CLIENT_TLS_ENABLED=true
KC_CLIENT_TLS_TRUSTSTORE_PATH=keystore.jks
KC_CLIENT_TLS_TRUSTSTORE_PASSWORD=secure123
KC_CLIENT_TLS_TRUSTSTORE_TYPE=PKCS12

Management (MGM) Eureka Modules

KC_CLIENT_TLS_ENABLED=true
KC_CLIENT_TLS_TRUSTSTORE_PATH=keystore.jks
KC_CLIENT_TLS_TRUSTSTORE_PASSWORD=secure123
KC_CLIENT_TLS_TRUSTSTORE_TYPE=PKCS12

Keycloak TLS Configuration

Keycloak supports TLS via HTTPS listeners configured in the standalone.xml or as environment variables when running in containerized environments.

Use a Keystore in Container

Mount keystore.jks to Keycloak container.
Set environment variables:

KEYCLOAK_HTTPS_PORT=8443
KEYCLOAK_HTTPS_KEY_STORE_FILE=keystore.jks
KEYCLOAK_HTTPS_KEY_STORE_PASSWORD=secure123
KEYCLOAK_HTTPS_KEY_STORE_TYPE=PKCS12
KEYCLOAK_HTTPS_KEY_ALIAS=keycloak

Ensure port 8443 is exposed and the certificate matches the domain used in OAuth clients.

Kong TLS Configuration

Kong can be configured to terminate TLS either at the proxy layer or on specific routes/services.

1. Create a TLS certificate and key (already covered)

2. Upload the certificate to Kong (using Admin API)

curl -i -X POST http://localhost:8001/certificates \
  --data "cert=$(< keycloak.crt)" \
  --data "key=$(< keycloak.key)" \
  --data "snis=your.domain.com"

3. Enable TLS Listener ( env vars)

KONG_SSL_CERT=/path/to/keycloak.crt
KONG_SSL_CERT_KEY=/path/to/keycloak.key
KONG_PORTS=8443 ssl

4. Restart Kong and test HTTPS access

Test access on https://your.domain.com:8443 to verify termination.

How to Generate Self-Signed Certificates

openssl req -x509 -newkey rsa:4096 -nodes -keyout keycloak.key -out keycloak.crt -days 365 \
  -subj "/CN=domain_folio" -extensions EXT -config <(printf "[dn]\nCN=domain_folio\n[req]\ndistinguished_name = dn\n[EXT]\nsubjectAltName=DNS:folio_domain\nkeyUsage=digitalSignature\nextendedKeyUsage=serverAuth")

Convert to PKCS12 and import to JKS:

openssl pkcs12 -export -in keycloak.crt -inkey keycloak.key -out keycloak.p12 -name keycloak -password pass:changeit

keytool -importkeystore -deststorepass changeit -destkeypass changeit -destkeystore keycloak.jks \
  -srckeystore keycloak.p12 -srcstoretype PKCS12 -srcstorepass changeit -alias keycloak

Testing

This approach was tested locally with Eureka sidecars, edge modules, and MGM modules using the self-signed cert. Keycloak was verified to start on port 8443, and Kong accepted HTTPS connections. Integration tests on Rancher are the next step.

Conclusion

The Eureka platform can securely run in TLS mode without FIPS, using Java-native capabilities and default container images. This simplifies deployment and eliminates the overhead of FIPS-compliant configurations.

Benefits:

Reduced complexity and image size
No dependency on Bouncy Castle
Faster builds and lower memory footprint
Easy to configure and test

Next Steps:

Prepare test environments with TLS enabled
Create stories for Kitfox team and the platform teams