Skip to main content

Authentication Settings

The Authentication page (under the Iceberg menu) is where Ice Flow exposes the JVM-wide krb5.conf it is using to authenticate Kerberos catalogs. It's the single place to inspect, override, and verify the configuration that every Kerberized catalog shares.

Why a Single Page​

The JDK's java.security.krb5.conf is a process-wide singleton. Every Kerberized catalog in Ice Flow lives in the same JVM, so the file the JVM reads has to know about every realm in use at once. If two catalogs come from non-cross-realm clusters (say, an internal realm and a partner cluster's realm), neither catalog's krb5.conf alone is sufficient — the JVM needs the union.

Ice Flow handles this for you automatically (auto-merge). The Authentication page is where you watch it work and override it when needed.

Auto-Merge (Default)​

With Auto-merge enabled, Ice Flow:

  1. Reads the host krb5.conf (from /etc/krb5.conf or the path set in the JVM's java.security.krb5.conf at startup).
  2. Adds each Kerberized catalog's optional krb5.conf snippet (the Override krb5.conf content field on the catalog form).
  3. Merges them into one file: realms and KDCs from every source, default_realm from the first source that declares one, multi-value keys (kdc, admin_server, etc.) accumulated without duplicates.
  4. Writes the merged file to a managed temp location and points the JVM at it.

When you add or remove a Kerberized catalog the merged file is recomputed automatically, so dropping a misbehaving catalog actually removes its realm from the JVM — no restart needed.

The page shows:

  • A summary of where the merged content came from (host file plus the list of catalogs whose snippets contributed).
  • The full effective krb5.conf content, read-only.

Manual Override​

When auto-merge produces something you need to change directly, turn off the Auto-merge toggle. The textarea unlocks and you can paste any krb5.conf content you want. The file you save is used verbatim — the host file and per-catalog snippets are ignored until you re-enable Auto-merge.

Typical reasons to use manual:

  • The host krb5.conf has site-wide settings (encryption types, ticket lifetimes, [capaths]) you need to preserve when no per-catalog snippet declares them.
  • You need a specific default_realm or [domain_realm] mapping the auto-merge cannot infer.
  • You're debugging and want full control to bisect a problem.

The override is persisted to the iceflow_authentication KV bucket and replayed at startup. Multiple Ice Flow instances running against the same Symphony deployment converge on the same override via a bucket watcher.

Validating Before You Save​

Click Validate before saving to see:

  • Whether the content parses as krb5.conf.
  • Which realms the content declares.
  • Which realms are currently in use by Kerberized catalogs.
  • A warning for any realm that's in use but missing from your proposed content (saving would break that catalog's auth).

Validation is advisory — the Save button is not blocked. The warning is there so you don't surprise yourself.

Reverting​

Toggle Auto-merge back on at any time. The persisted override is cleared and the JVM is regenerated from the host file plus catalog snippets.

When the JVM Cannot Refresh​

Ice Flow refreshes the JDK's Kerberos configuration singleton via reflection on sun.security.krb5.Config.refresh(). On JDK 17 and later this requires the JVM to be started with:

--add-opens=java.security.jgss/sun.security.krb5=ALL-UNNAMED

The shipping RPM and Docker images include this flag. If you run Ice Flow with a custom launcher and the flag is missing, the Authentication page shows an error banner stating that the merged file was written but the JVM is still using stale realm data. Fix the launcher and restart; the file on disk is already correct.

Per-Catalog Snippets vs the Authentication Page​

Both still exist and they serve different purposes:

  • The Override krb5.conf content field on a catalog form declares the realm/KDC info that catalog needs. Operators with many catalogs prefer this — each catalog owns its own snippet, Ice Flow merges them.
  • The Authentication page shows the merged result and lets you bypass the merge entirely when you need a hand-crafted file.

Most operators only need the per-catalog field. The Authentication page is the inspection-and-escape-hatch tool.