This is an automated email from the ASF dual-hosted git repository.
dongjoon-hyun pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/spark-connect-swift.git
The following commit(s) were added to refs/heads/main by this push:
new e65e87f [SPARK-57916] Add `Security Best Practices` documentation
e65e87f is described below
commit e65e87f5deefa35379cadc36be6d4d62d7719862
Author: Dongjoon Hyun <[email protected]>
AuthorDate: Thu Jul 2 15:39:07 2026 -0700
[SPARK-57916] Add `Security Best Practices` documentation
### What changes were proposed in this pull request?
This PR aims to add a `Security Best Practices` documentation page to DocC.
### Why are the changes needed?
To document the client's security behavior for production deployments:
- The connection is plaintext unless the connection string contains
`use_ssl=true`.
- The `SPARK_CONNECT_AUTHENTICATE_TOKEN` environment variable is
recommended over the `token=` parameter.
- Server certificates are validated against the OS trust store; custom CA,
mTLS, and certificate pinning are not supported.
### Does this PR introduce _any_ user-facing change?
No. This is a documentation-only change.
### How was this patch tested?
Manually checked with `markdownlint`.
### Was this patch authored or co-authored using generative AI tooling?
Generated-by: Claude Fable 5
Closes #432 from dongjoon-hyun/SPARK-57916.
Authored-by: Dongjoon Hyun <[email protected]>
Signed-off-by: Dongjoon Hyun <[email protected]>
---
.../Documentation.docc/SecurityGuide.md | 40 ++++++++++++++++++++++
.../Documentation.docc/SparkConnect.md | 1 +
2 files changed, 41 insertions(+)
diff --git a/Sources/SparkConnect/Documentation.docc/SecurityGuide.md
b/Sources/SparkConnect/Documentation.docc/SecurityGuide.md
new file mode 100644
index 0000000..1249f1b
--- /dev/null
+++ b/Sources/SparkConnect/Documentation.docc/SecurityGuide.md
@@ -0,0 +1,40 @@
+# Security Best Practices
+
+Recommendations for connecting to Apache Spark Connect servers securely in
production.
+
+## Transport Security (TLS)
+
+Following the
+[Spark Connect connection string
specification](https://github.com/apache/spark/blob/master/sql/connect/docs/client-connection-string.md),
+the connection is **plaintext** unless the connection string contains
+`use_ssl=true`. Always set `use_ssl=true` when connecting to any server other
+than `localhost`.
+
+```swift
+let spark = try await SparkSession
+ .builder
+ .remote("sc://spark.example.com:15002/;use_ssl=true")
+ .getOrCreate()
+```
+
+## Authentication Tokens
+
+The client sends the authentication token as an `Authorization: Bearer` header
+on every request. Prefer the `SPARK_CONNECT_AUTHENTICATE_TOKEN` environment
+variable over the `token=` connection string parameter, because connection
+strings can be exposed through shell history, process listings, and logs.
+
+```bash
+export SPARK_CONNECT_AUTHENTICATE_TOKEN=...
+```
+
+The environment variable is used only when the connection string has no
+`token=` parameter. Since a bearer token sent over a plaintext connection can
+be intercepted, always combine token authentication with `use_ssl=true`.
+
+## Certificate Validation
+
+When TLS is enabled, the server certificate is validated against the operating
+system trust store. Custom CA bundles, mutual TLS (client certificates), and
+certificate pinning are not currently supported, so the server certificate
+must chain to a root CA trusted by the operating system.
diff --git a/Sources/SparkConnect/Documentation.docc/SparkConnect.md
b/Sources/SparkConnect/Documentation.docc/SparkConnect.md
index 2aff7da..092a7b0 100644
--- a/Sources/SparkConnect/Documentation.docc/SparkConnect.md
+++ b/Sources/SparkConnect/Documentation.docc/SparkConnect.md
@@ -19,6 +19,7 @@ SparkConnect is a modern Swift library that provides a native
interface to Apach
- <doc:GettingStarted>
- <doc:Examples>
+- <doc:SecurityGuide>
### Sessions
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
