[
https://issues.apache.org/jira/browse/KNOX-3401?focusedWorklogId=1039855&page=com.atlassian.jira.plugin.system.issuetabpanels:worklog-tabpanel#worklog-1039855
]
ASF GitHub Bot logged work on KNOX-3401:
----------------------------------------
Author: ASF GitHub Bot
Created on: 06/Sep/26 19:58
Start Date: 06/Sep/26 19:58
Worklog Time Spent: 10m
Work Description: smolnar82 opened a new pull request, #1380:
URL: https://github.com/apache/knox/pull/1380
[KNOX-3401](https://issues.apache.org/jira/browse/KNOX-3401) - Replace the
embedded Apache Derby database with embedded H2
## What changes were proposed in this pull request?
Apache Derby is being retired, and Knox no longer wants to bundle its
driver. Knox has been using an embedded Derby database as its
zero-configuration, on-disk store for server-managed token state (and, more
recently, the KnoxIDF federation data). This PR replaces that embedded
**Derby** backend with an embedded **H2** database.
From an operator's point of view the default experience is unchanged: the
database is still provisioned automatically on first start, lives on the local
file system under the gateway security directory, requires no external setup,
and is intended for single-node (non-HA) deployments. Only the engine behind it
changes.
### Highlights:
- **Embedded H2 replaces embedded Derby** as the default token-state backend
and for the KnoxIDF federation stores. No configuration change is required for
a fresh install.
- **The Apache Derby driver is removed from the entire distribution.** The
`derbydb` database type and the Derby-backed service variants no longer exist.
Externally hosted databases (PostgreSQL, MySQL, MariaDB, Oracle, HSQL) are
unaffected.
- **Optional at-rest encryption for the embedded database.** It is off by
default and opt-in; when enabled, the encryption passphrase is read from a
credential-store alias (never the gateway master secret).
- **A supported upgrade path for existing token data.** Operators upgrading
from a Derby-shipping release can move their existing tokens into the new H2
store with a new `knoxcli.sh migrate-derby-tokens` command. Because the Derby
driver is no longer shipped, the operator temporarily drops a Derby driver jar
into the `ext/` directory for the duration of the migration. The migration
scope is tokens only: that was the only data ever persisted by Derby-shipping
releases; and the command is safe to re-run.
- **UI:** the Token Management status banner that warns when tokens are
stored in a local on-disk database (valid only for non-HA setups) now refers to
H2.
- **KnoxShell:** the built-in Derby datasource convenience helper is
removed. The KnoxShell JDBC datasource feature itself remains and works with
any user-provided driver.
- **Documentation** updated across the token configuration guide, the
KnoxCLI reference, and the KnoxIDF pages, including the new migration procedure
and the encryption options.
## How was this patch tested?
- **Automated unit tests:** the Derby-specific tests were replaced with
H2-backed equivalents, and a new test covers the Derby→H2 token migration logic
(verbatim copy of tokens and metadata, preservation of encoded passcodes and
absolute lifetime timestamps, and idempotent re-runs). The full
`gateway-server` test suite passes and checkstyle reports no violations.
- **Manual testing** against the embedded H2 backend on a local deployment:
- token generation via the Token Generation UI,
- enabling and disabling tokens,
- token revocation.
- The migration command is currently covered by its unit test; no manual
tests were executed.
### Integration Tests
The existing end-to-end suite already exercises this change. The E2E tests
spin up a fresh Knox Gateway that runs on the **default embedded backend - now
H2** - and the token-state tests (`test_knoxtoken_jwt.py`) drive the full
server-managed token lifecycle against it: minting, renewal, enable/disable,
and revocation, including verifying that disable and revoke are enforced at
federation. Because these run on the default backend, they now validate the
H2-backed token store on every run, so no new integration test was required.
I'm also adding the `test-federation` label to this PR which ensures that
recently added KnoxIDF tests are running as well (including federated tokens
from KeyCloak).
## UI changes
The only UI change is the wording of the Token Management status banner
shown when the token backend is the local embedded database: it now names H2
instead of Derby. A screenshot of the Token Management page showing that
message can be attached here.
<img width="1076" height="588" alt="image"
src="https://github.com/user-attachments/assets/0cb63b21-862e-4f6b-9307-a081e00a9650";
/>
Issue Time Tracking
-------------------
Worklog Id: (was: 1039855)
Remaining Estimate: 0h
Time Spent: 10m
> Switch OOTB JDBC-based token state service from Derby to something else
> -----------------------------------------------------------------------
>
> Key: KNOX-3401
> URL: https://issues.apache.org/jira/browse/KNOX-3401
> Project: Apache Knox
> Issue Type: Bug
> Affects Versions: 3.0.0
> Reporter: Sandor Molnar
> Assignee: Sandeep More
> Priority: Major
> Attachments: image-2026-07-30-07-34-16-369.png, screenshot-1.png
>
> Time Spent: 10m
> Remaining Estimate: 0h
>
> The community agreed to switch from alias-based TSS to JDBC-based TSS as the
> default implementation due to several reasons, details are found in [this
> e-mail
> thread|https://lists.apache.org/thread/fs9nkl6l45o330ttvgvqxj3jnxt63bcs].
> At that time (late 2023), Derby DB seemed a good choice given its wide range
> of configs and community support. However, the project os now retired, this
> is what's listed on their Apache page:
> h2. Derby Retired
> *On 2025-10-10, the Derby developers voted to retire the project into a
> read-only state. Derby development and bug-fixing have ended. No further
> releases will be published. The Derby website and wiki are frozen in place.
> Derby JIRA issues are now read-only and new bugs cannot be logged. The user
> and developer lists are disabled and can be accessed only through their
> archives.*
>
> Therefore, we need to find another DB vendor that satisfies our needs and can
> be used as Knox's default token state backend.
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
