This is an automated email from the ASF dual-hosted git repository.
roryqi pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/gravitino.git
The following commit(s) were added to refs/heads/main by this push:
new ebf08d6659 [#12301] feat(client:client-java): Public TLS API,
documentation, and e2e (#12620)
ebf08d6659 is described below
commit ebf08d6659b111964e84665557485995e808c9f5
Author: Octavio Herrera Contreras <[email protected]>
AuthorDate: Fri Nov 6 00:41:55 2026 -0800
[#12301] feat(client:client-java): Public TLS API, documentation, and e2e
(#12620)
[Subtask] M3: Public TLS API on the client builders, documentation, and
e2e #12301
### What changes were proposed in this pull request?
Added withTlsConfigurer to the Gravitino client builder to match the M0
design doc, in order to avoid internal types in public signatures. The
docs/how-to-use-gravitino-client.md was updated to include these new
methods, as well as docs/security/how-to-use-https.md to use the new
client TLS API instead of relying on JVM-wide truststore configuration.
Added E2E tests, which were achieved by creating a real gravitino test
server and utilizing a metalake, as well as a metalake operation, to
test real user endpoints. This method is separate from the M1 server
setup, which was a lightweight server setup; however, all fixtures were
reused from the M1 test artifacts.
### Why are the changes needed?
Changes were directly requested as described in M3
Fix: #12301
### Does this PR introduce _any_ user-facing change?
Yes, added tlsConfigurer to GravitinoClientBase, GravitinoAdminClient,
and GravitinoClient as described in the included documentation file.
### How was this patch tested?
./gradlew rat
Passed
./gradlew :clients:client-java:test --tests
"org.apache.gravitino.client.TestGravitinoClientTLS"
Passed
---------
Co-authored-by: roryqi <[email protected]>
---
.../gravitino/client/GravitinoAdminClient.java | 11 +-
.../apache/gravitino/client/GravitinoClient.java | 18 +-
.../gravitino/client/GravitinoClientBase.java | 70 ++++--
.../gravitino/client/TestGravitinoClientTLS.java | 271 +++++++++++++++++++++
docs/how-to-use-gravitino-client.md | 72 +++++-
docs/security/how-to-use-https.md | 30 ++-
6 files changed, 432 insertions(+), 40 deletions(-)
diff --git
a/clients/client-java/src/main/java/org/apache/gravitino/client/GravitinoAdminClient.java
b/clients/client-java/src/main/java/org/apache/gravitino/client/GravitinoAdminClient.java
index 9272e19c86..3086434641 100644
---
a/clients/client-java/src/main/java/org/apache/gravitino/client/GravitinoAdminClient.java
+++
b/clients/client-java/src/main/java/org/apache/gravitino/client/GravitinoAdminClient.java
@@ -50,7 +50,8 @@ import
org.apache.gravitino.exceptions.NonEmptyEntityException;
public class GravitinoAdminClient extends GravitinoClientBase implements
SupportsMetalakes {
/**
- * Constructs a new GravitinoClient with the given URI, authenticator and
AuthDataProvider.
+ * Constructs a new GravitinoAdminClient with the given URI, authenticator,
AuthDataProvider, and
+ * tlsConfigurer.
*
* @param uri The base URI for the Gravitino API.
* @param authDataProvider The provider of the data which is used for
authentication.
@@ -58,14 +59,16 @@ public class GravitinoAdminClient extends
GravitinoClientBase implements Support
* support the case that the client-side version is higher than the
server-side version.
* @param headers The base header for Gravitino API.
* @param properties A map of properties (key-value pairs) used to configure
the Gravitino client.
+ * @param tlsConfigurer The configurer to apply for the underlying TLS
settings.
*/
private GravitinoAdminClient(
String uri,
AuthDataProvider authDataProvider,
boolean checkVersion,
Map<String, String> headers,
- Map<String, String> properties) {
- super(uri, authDataProvider, checkVersion, headers, properties);
+ Map<String, String> properties,
+ TLSConfigurer tlsConfigurer) {
+ super(uri, authDataProvider, checkVersion, headers, properties,
tlsConfigurer);
}
/**
@@ -259,7 +262,7 @@ public class GravitinoAdminClient extends
GravitinoClientBase implements Support
Preconditions.checkArgument(
uri != null && !uri.isEmpty(), "The argument 'uri' must be a valid
URI");
return new GravitinoAdminClient(
- uri, authDataProvider, isVersionCheckEnabled(), headers, properties);
+ uri, authDataProvider, isVersionCheckEnabled(), headers, properties,
tlsConfigurer);
}
}
}
diff --git
a/clients/client-java/src/main/java/org/apache/gravitino/client/GravitinoClient.java
b/clients/client-java/src/main/java/org/apache/gravitino/client/GravitinoClient.java
index 4fbd927712..8bebefd468 100644
---
a/clients/client-java/src/main/java/org/apache/gravitino/client/GravitinoClient.java
+++
b/clients/client-java/src/main/java/org/apache/gravitino/client/GravitinoClient.java
@@ -92,7 +92,8 @@ public class GravitinoClient extends GravitinoClientBase
private volatile GravitinoMetalake metalake;
/**
- * Constructs a new GravitinoClient with the given URI, authenticator and
AuthDataProvider.
+ * Constructs a new GravitinoClient with the given URI, authenticator,
AuthDataProvider, and
+ * tlsConfigurer.
*
* <p>The metalake is loaded lazily on first use, not in the constructor.
*
@@ -103,6 +104,8 @@ public class GravitinoClient extends GravitinoClientBase
* support the case that the client-side version is higher than the
server-side version.
* @param headers The base header for Gravitino API.
* @param properties A map of properties (key-value pairs) used to configure
the Gravitino client.
+ * @param tlsConfigurer The TLSConfigurer used to configure TLS settings for
the HTTP client.
+ * @throws NoSuchMetalakeException if the metalake with specified name does
not exist.
*/
private GravitinoClient(
String uri,
@@ -110,8 +113,9 @@ public class GravitinoClient extends GravitinoClientBase
AuthDataProvider authDataProvider,
boolean checkVersion,
Map<String, String> headers,
- Map<String, String> properties) {
- super(uri, authDataProvider, checkVersion, headers, properties);
+ Map<String, String> properties,
+ TLSConfigurer tlsConfigurer) {
+ super(uri, authDataProvider, checkVersion, headers, properties,
tlsConfigurer);
this.metalakeName = metalakeName;
}
@@ -808,7 +812,13 @@ public class GravitinoClient extends GravitinoClientBase
"The argument 'metalakeName' must be a valid name");
return new GravitinoClient(
- uri, metalakeName, authDataProvider, isVersionCheckEnabled(),
headers, properties);
+ uri,
+ metalakeName,
+ authDataProvider,
+ isVersionCheckEnabled(),
+ headers,
+ properties,
+ tlsConfigurer);
}
}
}
diff --git
a/clients/client-java/src/main/java/org/apache/gravitino/client/GravitinoClientBase.java
b/clients/client-java/src/main/java/org/apache/gravitino/client/GravitinoClientBase.java
index 07c7e9cca6..1049472e2f 100644
---
a/clients/client-java/src/main/java/org/apache/gravitino/client/GravitinoClientBase.java
+++
b/clients/client-java/src/main/java/org/apache/gravitino/client/GravitinoClientBase.java
@@ -59,7 +59,8 @@ public abstract class GravitinoClientBase implements
Closeable {
protected static final String API_METALAKES_IDENTIFIER_PATH =
API_METALAKES_LIST_PATH + "/";
/**
- * Constructs a new GravitinoClient with the given URI, authenticator and
AuthDataProvider.
+ * Constructs a new GravitinoClient with the given URI, authenticator,
AuthDataProvider, and null
+ * tlsConfigurer.
*
* @param uri The base URI for the Gravitino API.
* @param authDataProvider The provider of the data which is used for
authentication.
@@ -73,27 +74,45 @@ public abstract class GravitinoClientBase implements
Closeable {
boolean checkVersion,
Map<String, String> headers,
Map<String, String> properties) {
+ this(uri, authDataProvider, checkVersion, headers, properties, null);
+ }
+
+ /**
+ * Constructs a new GravitinoClient with the given URI, authenticator,
AuthDataProvider, and
+ * tlsConfigurer.
+ *
+ * @param uri The base URI for the Gravitino API.
+ * @param authDataProvider The provider of the data which is used for
authentication.
+ * @param checkVersion Whether to check the version of the Gravitino server.
+ * @param headers The base header of the Gravitino API.
+ * @param properties A map of properties (key-value pairs) used to configure
the Gravitino client.
+ * @param tlsConfigurer The configurer to apply for the underlying TLS
settings
+ */
+ protected GravitinoClientBase(
+ String uri,
+ AuthDataProvider authDataProvider,
+ boolean checkVersion,
+ Map<String, String> headers,
+ Map<String, String> properties,
+ TLSConfigurer tlsConfigurer) {
ObjectMapper mapper = ObjectMapperProvider.objectMapper();
+ HTTPClient.Builder httpBuilder =
+ HTTPClient.builder(properties)
+ .uri(uri)
+ .withAuthDataProvider(authDataProvider)
+ .withObjectMapper(mapper)
+ .withHeaders(headers);
+
+ if (tlsConfigurer != null) {
+ httpBuilder.withTlsConfigurer(tlsConfigurer);
+ }
+
if (checkVersion) {
- this.restClient =
- HTTPClient.builder(properties)
- .uri(uri)
- .withAuthDataProvider(authDataProvider)
- .withObjectMapper(mapper)
- .withPreConnectHandler(this::checkVersion)
- .withHeaders(headers)
- .build();
-
- } else {
- this.restClient =
- HTTPClient.builder(properties)
- .uri(uri)
- .withAuthDataProvider(authDataProvider)
- .withObjectMapper(mapper)
- .withHeaders(headers)
- .build();
+ httpBuilder.withPreConnectHandler(this::checkVersion);
}
+
+ this.restClient = httpBuilder.build();
}
/**
@@ -237,6 +256,8 @@ public abstract class GravitinoClientBase implements
Closeable {
protected Map<String, String> headers = ImmutableMap.of();
/** A map of properties (key-value pairs) used to configure the Gravitino
client. */
protected Map<String, String> properties = ImmutableMap.of();
+ /** The configurer to apply for the underlying TLS settings. */
+ protected TLSConfigurer tlsConfigurer;
/**
* The constructor for the Builder class.
@@ -393,6 +414,19 @@ public abstract class GravitinoClientBase implements
Closeable {
return this;
}
+ /**
+ * Configures TLS for the Gravitino client.
+ *
+ * @param tlsConfigurer The configurer to apply for the underlying TLS
settings
+ * @return this builder instance for method chaining
+ */
+ public Builder<T> withTlsConfigurer(TLSConfigurer tlsConfigurer) {
+ Preconditions.checkArgument(tlsConfigurer != null, "TLS configurer
cannot be null");
+
+ this.tlsConfigurer = tlsConfigurer;
+ return this;
+ }
+
/**
* Builds a new instance. Subclasses should overwrite this method.
*
diff --git
a/clients/client-java/src/test/java/org/apache/gravitino/client/TestGravitinoClientTLS.java
b/clients/client-java/src/test/java/org/apache/gravitino/client/TestGravitinoClientTLS.java
new file mode 100644
index 0000000000..9c4d5b08d6
--- /dev/null
+++
b/clients/client-java/src/test/java/org/apache/gravitino/client/TestGravitinoClientTLS.java
@@ -0,0 +1,271 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.apache.gravitino.client;
+
+import static org.apache.gravitino.Configs.ENTITY_RELATIONAL_JDBC_BACKEND_PATH;
+import static
org.apache.gravitino.server.web.TestTlsServerUtils.TEST_STORE_PASSWORD;
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+
+import com.google.common.collect.ImmutableMap;
+import java.io.IOException;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.HashMap;
+import java.util.Map;
+import org.apache.commons.io.FileUtils;
+import org.apache.gravitino.GravitinoEnv;
+import org.apache.gravitino.auxiliary.AuxiliaryServiceManager;
+import org.apache.gravitino.exceptions.RESTException;
+import org.apache.gravitino.rest.RESTUtils;
+import org.apache.gravitino.server.GravitinoServer;
+import org.apache.gravitino.server.ServerConfig;
+import org.apache.gravitino.server.web.JettyServerConfig;
+import org.apache.gravitino.server.web.TestTlsServerUtils;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.Test;
+import org.mockito.Mockito;
+
+public class TestGravitinoClientTLS {
+ private TestGravitinoServer testServer;
+ private GravitinoAdminClient adminClient;
+ private boolean cleanupMetalake = false;
+
+ @AfterEach
+ void tearDown() throws Exception {
+ try {
+ if (adminClient != null) {
+ if (cleanupMetalake) {
+ adminClient.dropMetalake("metalake", true);
+ }
+ }
+ } finally {
+ if (testServer != null) {
+ testServer.stop();
+ }
+ }
+ }
+
+ @Test
+ void testGravitinoClientmTLSConfigurer() throws Exception {
+ // set up a gravitino server with client auth enabled
+ // create a tls config, with a client cert
+ // create a metalake utilizing the admin client (must include the tls
config)
+ // create a gravitino client with the tls config
+ // make the gravitino client request to the server and verify that it
succeeds
+
+ testServer = startGravitinoServer(true, true);
+ TLSConfigurer tlsConfigurer = createTestTlsConfigurer(true);
+
+ // create an admin client with the tls config, to then create a metalake
+ adminClient =
+
GravitinoAdminClient.builder(testServer.uri()).withTlsConfigurer(tlsConfigurer).build();
+ adminClient.createMetalake("metalake", "test metalake", Map.of());
+ cleanupMetalake = true;
+
+ // Create the gravitino client to run a user request against the server,
with the tls config
+ GravitinoClient gravitinoClient =
+ createGravitinoClient(testServer.uri(), "metalake", tlsConfigurer);
+
+ String[] catalogs = gravitinoClient.listCatalogs();
+
+ // verify that the request succeeds and returns an empty list of catalogs
(expected)
+ assertEquals(0, catalogs.length);
+ }
+
+ @Test
+ void testGravitinoClientmTLSConfigurerRejectsMissingClientCert() throws
Exception {
+ // set up a gravitino server with client auth enabled
+ // create a tls config, without a client cert
+ // Create a gravitino admin client with the tls config
+ // Attempt to make a request to the server, which should fail
+
+ testServer = startGravitinoServer(true, true);
+ TLSConfigurer tlsConfigurer = createTestTlsConfigurer(false);
+
+ // Create an admin client with the tls config, to then create a metalake
+ adminClient =
+
GravitinoAdminClient.builder(testServer.uri()).withTlsConfigurer(tlsConfigurer).build();
+
+ assertThrows(
+ RESTException.class,
+ () -> adminClient.createMetalake("metalake", "test metalake",
Map.of()));
+ }
+
+ @Test
+ void testGravitinoClientTLSConfigurer() throws Exception {
+ // set up a gravitino server without client auth, but with tls config
+ // create a tls config without a client cert
+ // create a metalake utilizing the admin client (must include the tls
config)
+ // create a gravitino client with the tls config
+ // make the gravitino client request to the server and verify that it
succeeds
+
+ testServer = startGravitinoServer(false, true);
+ TLSConfigurer tlsConfigurer = createTestTlsConfigurer(false);
+
+ adminClient =
+
GravitinoAdminClient.builder(testServer.uri()).withTlsConfigurer(tlsConfigurer).build();
+ adminClient.createMetalake("metalake", "test metalake", Map.of());
+ cleanupMetalake = true;
+
+ GravitinoClient gravitinoClient =
+ createGravitinoClient(testServer.uri(), "metalake", tlsConfigurer);
+
+ String[] catalogs = gravitinoClient.listCatalogs();
+
+ // verify that the request succeeds and returns an empty list of catalogs
(expected)
+ assertEquals(0, catalogs.length);
+ }
+
+ @Test
+ void testGravitinoClientHTTP() throws Exception {
+ // set up a gravitino server without client auth or tls config (http only)
+ // create a metalake utilizing the admin client
+ // create a gravitino client
+ // make the gravitino client request to the server and verify that it
succeeds
+
+ testServer = startGravitinoServer(false, false);
+
+ adminClient = GravitinoAdminClient.builder(testServer.uri()).build();
+ adminClient.createMetalake("metalake", "test metalake", Map.of());
+ cleanupMetalake = true;
+
+ GravitinoClient gravitinoClient =
+
GravitinoClient.builder(testServer.uri()).withMetalake("metalake").build();
+
+ String[] catalogs = gravitinoClient.listCatalogs();
+
+ // verify that the request succeeds and returns an empty list of catalogs
(expected)
+ assertEquals(0, catalogs.length);
+ }
+
+ public TLSConfigurer createTestTlsConfigurer(Boolean clientAuth) throws
Exception {
+ if (clientAuth) {
+ return TLSConfigurers.builder()
+ .trustStore(
+ TestTlsServerUtils.testResource("test-client-truststore.p12"),
TEST_STORE_PASSWORD)
+ .keyStore(
+
TestTlsServerUtils.testResource("test-trusted-client-keystore.p12"),
+ TEST_STORE_PASSWORD)
+ .build();
+ } else {
+ return TLSConfigurers.builder()
+ .trustStore(
+ TestTlsServerUtils.testResource("test-client-truststore.p12"),
TEST_STORE_PASSWORD)
+ .build();
+ }
+ }
+
+ public GravitinoClient createGravitinoClient(
+ String uri, String metalake, TLSConfigurer tlsConfigurer) {
+ return GravitinoClient.builder(uri)
+ .withMetalake(metalake)
+ .withTlsConfigurer(tlsConfigurer)
+ .build();
+ }
+
+ public record TestGravitinoServer(
+ GravitinoServer server, int port, Path backendDir, boolean tlsEnabled) {
+ public void stop() throws IOException {
+ try {
+ server.stop();
+ } finally {
+ FileUtils.deleteDirectory(backendDir.toFile());
+ }
+ }
+
+ public String uri() {
+ return (tlsEnabled ? "https" : "http") + "://localhost:" + port;
+ }
+ }
+
+ public static TestGravitinoServer startGravitinoServer(boolean clientAuth,
boolean tlsEnabled)
+ throws Exception {
+ // create a temporary directory for the backend database to delete after
the test is done
+ Path backendDir = Files.createTempDirectory("gravitino-client-tls-");
+ Path backendPath = backendDir.resolve("gravitino.db");
+
+ int port = RESTUtils.findAvailablePort(6000, 7000);
+
+ Map<String, String> configs = new HashMap<>();
+
+ configs.put(ENTITY_RELATIONAL_JDBC_BACKEND_PATH.getKey(),
backendPath.toString());
+ if (tlsEnabled) {
+
+ configs.put(
+ GravitinoServer.WEBSERVER_CONF_PREFIX +
JettyServerConfig.ENABLE_HTTPS.getKey(), "true");
+
+ configs.put(
+ GravitinoServer.WEBSERVER_CONF_PREFIX +
JettyServerConfig.WEBSERVER_HTTPS_PORT.getKey(),
+ String.valueOf(port));
+
+ configs.put(
+ GravitinoServer.WEBSERVER_CONF_PREFIX +
JettyServerConfig.SSL_KEYSTORE_PATH.getKey(),
+
TestTlsServerUtils.testResource("test-server-keystore.p12").toString());
+
+ configs.put(
+ GravitinoServer.WEBSERVER_CONF_PREFIX +
JettyServerConfig.SSL_KEYSTORE_PASSWORD.getKey(),
+ TEST_STORE_PASSWORD);
+
+ configs.put(
+ GravitinoServer.WEBSERVER_CONF_PREFIX +
JettyServerConfig.SSL_MANAGER_PASSWORD.getKey(),
+ TEST_STORE_PASSWORD);
+
+ configs.put(
+ GravitinoServer.WEBSERVER_CONF_PREFIX +
JettyServerConfig.ENABLE_CLIENT_AUTH.getKey(),
+ String.valueOf(clientAuth));
+
+ if (clientAuth) {
+ configs.put(
+ GravitinoServer.WEBSERVER_CONF_PREFIX +
JettyServerConfig.SSL_TRUST_STORE_PATH.getKey(),
+
TestTlsServerUtils.testResource("test-server-truststore.p12").toString());
+
+ configs.put(
+ GravitinoServer.WEBSERVER_CONF_PREFIX
+ + JettyServerConfig.SSL_TRUST_STORE_PASSWORD.getKey(),
+ TEST_STORE_PASSWORD);
+ }
+ } else {
+ configs.put(
+ GravitinoServer.WEBSERVER_CONF_PREFIX +
JettyServerConfig.ENABLE_HTTPS.getKey(), "false");
+
+ configs.put(
+ GravitinoServer.WEBSERVER_CONF_PREFIX +
JettyServerConfig.WEBSERVER_HTTP_PORT.getKey(),
+ String.valueOf(port));
+ }
+
+ ServerConfig serverConfig = new ServerConfig();
+ serverConfig.loadFromMap(configs, t -> true);
+
+ ServerConfig spyServerConfig = Mockito.spy(serverConfig);
+
+ Mockito.when(
+ spyServerConfig.getConfigsWithPrefix(
+ AuxiliaryServiceManager.GRAVITINO_AUX_SERVICE_PREFIX))
+ .thenReturn(ImmutableMap.of(AuxiliaryServiceManager.AUX_SERVICE_NAMES,
""));
+
+ GravitinoServer server = new GravitinoServer(spyServerConfig,
GravitinoEnv.getInstance());
+
+ server.initialize();
+ server.start();
+
+ return new TestGravitinoServer(server, port, backendDir, tlsEnabled);
+ }
+}
diff --git a/docs/how-to-use-gravitino-client.md
b/docs/how-to-use-gravitino-client.md
index d0d1135f90..b774f4fcc9 100644
--- a/docs/how-to-use-gravitino-client.md
+++ b/docs/how-to-use-gravitino-client.md
@@ -20,20 +20,22 @@ install it in your local.
Customize the Gravitino Java client by using `withClientConfig` like this:
```java
- Map<String, String> properties =
+Map<String, String> properties =
ImmutableMap.of(
"gravitino.client.connectionTimeoutMs", "10",
"gravitino.client.socketTimeoutMs", "10"
);
-GravitinoClient gravitinoClient =
GravitinoClient.builder("http://localhost:8090")
-.withMetalake("metalake")
-.withClientConfig(properties) // add custom client config (optional)
-.builder();
+GravitinoClient gravitinoClient =
+ GravitinoClient.builder("http://localhost:8090")
+ .withMetalake("metalake")
+ .withClientConfig(properties) // add custom client config (optional)
+ .build();
-GravitinoAdminClient gravitinoAdminClient =
GravitinoAdminClient.builder("http://localhost:8090")
-.withClientConfig(properties) // add custom client config (optional)
-.builder();
+GravitinoAdminClient gravitinoAdminClient =
+ GravitinoAdminClient.builder("http://localhost:8090")
+ .withClientConfig(properties) // add custom client config (optional)
+ .build();
// ...
```
@@ -47,6 +49,60 @@ GravitinoAdminClient gravitinoAdminClient =
GravitinoAdminClient.builder("http:/
**Note:** Invalid configuration properties will result in exceptions.
+### Java Client TLS Configuration
+
+To connect to a Gravitino server over HTTPS using a private certificate
authority or a custom trust store, configure a `TLSConfigurer` and pass it to
the client builder:
+
+```java
+import java.nio.file.Path;
+import org.apache.gravitino.client.GravitinoAdminClient;
+import org.apache.gravitino.client.GravitinoClient;
+import org.apache.gravitino.client.TLSConfigurer;
+import org.apache.gravitino.client.TLSConfigurers;
+
+TLSConfigurer tlsConfigurer =
+ TLSConfigurers.builder()
+ .trustStore(
+ Path.of("/path/to/client-truststore.p12"),
+ "truststore-password")
+ .build();
+
+GravitinoClient gravitinoClient =
+ GravitinoClient.builder("https://localhost:8433")
+ .withMetalake("metalake")
+ .withTlsConfigurer(tlsConfigurer)
+ .build();
+
+GravitinoAdminClient gravitinoAdminClient =
+ GravitinoAdminClient.builder("https://localhost:8433")
+ .withTlsConfigurer(tlsConfigurer)
+ .build();
+```
+
+The trust store contains certificates that the client trusts when verifying
the Gravitino server.
+
+For mutual TLS (mTLS), configure both a trust store and a client key store:
+
+```java
+TLSConfigurer tlsConfigurer =
+ TLSConfigurers.builder()
+ .trustStore(
+ Path.of("/path/to/client-truststore.p12"),
+ "truststore-password")
+ .keyStore(
+ Path.of("/path/to/client-keystore.p12"),
+ "keystore-password")
+ .build();
+
+GravitinoClient gravitinoClient =
+ GravitinoClient.builder("https://localhost:8433")
+ .withMetalake("metalake")
+ .withTlsConfigurer(tlsConfigurer)
+ .build();
+```
+
+The key store contains the client certificate and private key used when the
Gravitino server requires client certificate authentication.
+
## Python Client
Customize the Gravitino Python client with config properties like this:
diff --git a/docs/security/how-to-use-https.md
b/docs/security/how-to-use-https.md
index 3be70815fa..e82d101098 100644
--- a/docs/security/how-to-use-https.md
+++ b/docs/security/how-to-use-https.md
@@ -39,7 +39,7 @@ For the values `tlsProtocol` and `enableCipherAlgorithms`
accept, see the "Addit
## Local Development Example
-The following produces a self-signed certificate so you can exercise an HTTPS
endpoint on one machine. It is not a production setup, since a self-signed
certificate trusted by editing a JVM trust store is not how certificates are
managed in a real deployment.
+The following produces a self-signed certificate so you can exercise an HTTPS
endpoint on one machine. It is not a production setup, since self-signed
certificates are generally not how certificates are managed in a real
deployment.
**1. Generate a key store.**
@@ -60,11 +60,13 @@ bin/keytool -export -alias localhost -keystore
localhost.jks \
-file localhost.crt -storepass {store_password}
```
-**3. Import it into the JVM trust store** so a local Java client will accept
it.
+**3. Import it into a client trust store** so the Gravitino Java client can
trust the server certificate without modifying the JVM-wide trust store.
```shell
-bin/keytool -import -alias localhost -keystore jre/lib/security/cacerts \
- -file localhost.crt -storepass changeit -noprompt
+bin/keytool -importcert -alias localhost \
+ -keystore client-truststore.p12 -storetype PKCS12 \
+ -file localhost.crt \
+ -storepass {truststore_password} -noprompt
```
**4. Configure the server.** Append the following to `conf/gravitino.conf`,
then start Gravitino. Configuration files do not resolve environment variables,
so write the expanded path rather than `${JAVA_HOME}`.
@@ -77,16 +79,32 @@ gravitino.server.webserver.keyStorePassword =
{store_password}
gravitino.server.webserver.managerPassword = {key_password}
```
-**5. Connect.** From Java, the client takes the HTTPS URI directly:
+**5. Connect.** From Java, configure the client to trust the server
certificate using the client trust store:
```java
+import java.nio.file.Path;
+
import org.apache.gravitino.client.GravitinoClient;
import org.apache.gravitino.client.GravitinoVersion;
+import org.apache.gravitino.client.TLSConfigurer;
+import org.apache.gravitino.client.TLSConfigurers;
public class Main {
public static void main(String[] args) {
String uri = "https://localhost:8433";
- GravitinoClient client =
GravitinoClient.builder(uri).withMetalake("metalake").build();
+ TLSConfigurer tlsConfigurer =
+ TLSConfigurers.builder()
+ .trustStore(
+ Path.of("/path/to/client-truststore.p12"),
+ "{truststore_password}")
+ .build();
+
+ GravitinoClient client =
+ GravitinoClient.builder(uri)
+ .withMetalake("metalake")
+ .withTlsConfigurer(tlsConfigurer)
+ .build();
+
GravitinoVersion gravitinoVersion = client.getVersion();
System.out.println(gravitinoVersion);
}