This is an automated email from the ASF dual-hosted git repository.
hanicz pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/knox.git
The following commit(s) were added to refs/heads/master by this push:
new 51f40e751 KNOX-3367: Update Token State Service DB documentation
(#1287)
51f40e751 is described below
commit 51f40e751225fe4327d6ab1fda5eaa88833d3b21
Author: hanicz <[email protected]>
AuthorDate: Wed Jul 1 11:29:39 2026 +0200
KNOX-3367: Update Token State Service DB documentation (#1287)
* KNOX-3367: Update Token State Service DB documentation
* KNOX-3367: Removed deprecated Token State Services
---
knox-site/docs/config_knox_token.md | 29 ++++++++++++++++++++---------
1 file changed, 20 insertions(+), 9 deletions(-)
diff --git a/knox-site/docs/config_knox_token.md
b/knox-site/docs/config_knox_token.md
index 107cf1ee2..c1042e022 100644
--- a/knox-site/docs/config_knox_token.md
+++ b/knox-site/docs/config_knox_token.md
@@ -367,12 +367,8 @@ The second option involves a newly created Knox CLI
command called `generate-jwk
There was an important step the Knox team made to provide more flexibility for
our end-users: there are some internal service implementations in Knox that
were hard-coded in the Java source code. One of those services is the `Token
State` service implementation which you can change in gateway-site.xml going
forward by setting the `gateway.service.tokenstate.impl` property to any of:
1. `org.apache.knox.gateway.services.token.impl.DefaultTokenStateService` -
keeps all token information in memory, therefore all of this information is
lost when Knox is shut down
-2. `org.apache.knox.gateway.services.token.impl.AliasBasedTokenStateService`
- token information is stored in the gateway credential store. This is a
durable option, but not suitable for HA deployments
-3.
`org.apache.knox.gateway.services.token.impl.JournalBasedTokenStateService` -
token information is stored in plain files within
`$KNOX_DATA_DIR/security/token-state` folder. This option also provides a
durable persistence layer for tokens and it might be good for HA scenarios too
(in case of KNOX_DATA_DIR is on a shared drive), but the token data is written
out in plain text (i.e. not encrypted) so it's less secure.
-4. `org.apache.knox.gateway.services.token.impl.ZookeeperTokenStateService` -
this is an extension of the keystore-based approach. In this case, token
information is stored in Zookeeper using Knox aliases. The token's alias name
equals to its generated token ID.
-5. `org.apache.knox.gateway.services.token.impl.JDBCTokenStateService` -
stores token information in relational databases. It's not only durable, but
it's perfectly fine with HA deployments. Currently, PostgreSQL and MySQL
databases are supported.
-
-By default, the `AliasBasedTokenStateService` implementation is used.
+2. `org.apache.knox.gateway.services.token.impl.JDBCTokenStateService` -
stores token information in relational databases. It's not only durable, but
it's perfectly fine with HA deployments. The following database types are
supported: PostgreSQL, MySQL, MariaDB, Oracle, Derby and HSQL.
+3. `org.apache.knox.gateway.services.token.impl.DerbyDBTokenStateService` - a
specialization of `JDBCTokenStateService` backed by an embedded Apache Derby
database that Knox provisions and manages automatically under the gateway
security directory (`$KNOX_DATA_DIR/security`). It provides durable token
storage without any external database setup and is the __default__
implementation when `gateway.service.tokenstate.impl` is not set. If the
embedded Derby database cannot be initialized Kn [...]
##### Configuring the JDBC token state service
@@ -381,18 +377,33 @@ If you want to use the newly implemented database token
management, you’ve to
Now, that you have configured your token state backend, you need to configure
a valid database in _gateway-site.xml_. There are two ways to do that:
1. You either declare database connection properties one-by-one:
- `gateway.database.type` - should be set to `postgresql` or `mysql`
+ `gateway.database.type` - should be set to `postgresql`, `mysql`,
`mariadb`, `oracle`, `derbydb` or `hsql`
`gateway.database.host` - the host where your DB server is running
`gateway.database.port` - the port that your DB server is listening on
- `gateway.database.name` - the name of the database you are connecting to
+ `gateway.database.name` - the name of the database you are connecting to
(for Oracle, this is the service name)
2. Or you declare an all-in-one JDBC connection string called
`gateway.database.connection.url`. The following value will show you how to
connect to an SSL enabled PostgreSQL server:
<code>jdbc:postgresql://$myPostgresServerHost:5432/postgres?user=postgres&ssl=true&sslmode=verify-full&sslrootcert=/usr/local/var/postgresql@10/data/root.crt</code>
-
+
If your database requires user/password authentication, the following aliases
must be saved into the Knox Gateway’s credential store
(__gateway-credentials.jceks):
* `gateway_database_user` - the username
* `gateway_database_password` - the password
+###### Database SSL
+
+SSL connections to the database are supported for PostgreSQL, MySQL and
Oracle. MariaDB, Derby and HSQL do not honor the `gateway.database.ssl.*`
properties. SSL is enabled per gateway by setting:
+
+* `gateway.database.ssl.enabled` - set to `true` to enable SSL
+* `gateway.database.ssl.verify.server.cert` - set to `true` to verify the
server certificate against a local truststore
+* `gateway.database.ssl.truststore.file` - path to the truststore (for
PostgreSQL this is the PEM-encoded SSL root certificate file)
+* `gateway.database.ssl.truststore.type` - truststore type, used by MySQL
and Oracle. Defaults to `JKS`; other supported values include `PKCS12`.
PostgreSQL ignores this property because it reads the root cert as PEM.
+
+If the truststore is password-protected, store the password in the Knox
Gateway's credential store under the `gateway_database_ssl_truststore_password`
alias.
+
+###### Provided JDBC drivers
+
+The MySQL and Oracle JDBC drivers are declared as __provided__ Maven
dependencies and are __not__ shipped with the Knox distribution (due to
licensing). To enable MySQL or Oracle support, download the matching driver jar
(`mysql-connector-java*.jar` or `ojdbc11.jar`) and drop it into the
`$KNOX_HOME/ext` directory before starting the gateway. PostgreSQL, MariaDB,
Derby and HSQL drivers are bundled with Knox and require no extra steps.
+
###### Database design
