This is an automated email from the ASF dual-hosted git repository.
jshao 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 39b213431 [Minor] improvement(docs): Fix and polish docs. (#4565)
39b213431 is described below
commit 39b213431ba83d3981f494da75f0b611cf13c5f9
Author: Qi Yu <[email protected]>
AuthorDate: Fri Aug 16 18:18:24 2024 +0800
[Minor] improvement(docs): Fix and polish docs. (#4565)
### What changes were proposed in this pull request?
Optimize docs for the security part.
### Why are the changes needed?
For a better user experience.
### Does this PR introduce _any_ user-facing change?
N/A.
### How was this patch tested?
N/A
---
docs/security/how-to-authenticate.md | 29 +++++---------
docs/security/how-to-use-https.md | 77 ++++++++++++++++--------------------
docs/security/security.md | 10 +++--
3 files changed, 51 insertions(+), 65 deletions(-)
diff --git a/docs/security/how-to-authenticate.md
b/docs/security/how-to-authenticate.md
index 9b0b380df..41b620353 100644
--- a/docs/security/how-to-authenticate.md
+++ b/docs/security/how-to-authenticate.md
@@ -8,12 +8,11 @@ license: "This software is licensed under the Apache License
version 2."
## Authentication
Apache Gravitino supports three kinds of authentication mechanisms: simple,
OAuth and Kerberos.
-If you don't enable authentication for your client and server explicitly, you
will use anonymous to access the server.
+If you don't enable authentication for your client and server explicitly, you
will use user `anonymous` to access the server.
### Simple mode
-If the client sets the simple mode, it will use the environment variable
`GRAVITINO_USER` as the user.
-
+If the client sets the simple mode, it will use the value of environment
variable `GRAVITINO_USER` as the user.
If the environment variable `GRAVITINO_USER` in the client isn't set, the
client uses the user logging in the machine that sends requests.
For the client side, users can enable `simple` mode by the following code:
@@ -27,15 +26,14 @@ GravitinoClient client = GravitinoClient.builder(uri)
### OAuth mode
-Gravitino only supports external OAuth 2.0 servers.
+Gravitino only supports external OAuth 2.0 servers. To enable OAuth mode,
users should follow the steps below.
-First, users need to guarantee that the external correctly configured OAuth
2.0 server supports Bearer JWT.
+- First, users need to guarantee that the external correctly configured OAuth
2.0 server supports Bearer JWT.
-Then, on the server side, users should set `gravitino.authenticators` as
`oauth` and give
+- Then, on the server side, users should set `gravitino.authenticators` as
`oauth` and give
`gravitino.authenticator.oauth.defaultSignKey`,
`gravitino.authenticator.oauth.serverUri` and
`gravitino.authenticator.oauth.tokenPath` a proper value.
-
-Next, for the client side, users can enable `OAuth` mode by the following code:
+- Next, for the client side, users can enable `OAuth` mode by the following
code:
```java
DefaultOAuth2TokenProvider authDataProvider =
DefaultOAuth2TokenProvider.builder()
@@ -53,12 +51,8 @@ GravitinoClient client = GravitinoClient.builder(uri)
### Kerberos mode
-Gravitino supports Kerberos mode.
-
-For the server side, users should set `gravitino.authenticators` as `kerberos`
and give
-`gravitino.authenticator.kerberos.principal` and
`gravitino.authenticator.kerberos.keytab` a proper value.
-
-For the client side, users can enable `kerberos` mode by the following code:
+To enable Kerberos mode, users need to guarantee that the server and client
have the correct Kerberos configuration. In the server side, users should set
`gravitino.authenticators` as `kerberos` and give
+`gravitino.authenticator.kerberos.principal` and
`gravitino.authenticator.kerberos.keytab` a proper value. For the client side,
users can enable `kerberos` mode by the following code:
```java
// Use keytab to create KerberosTokenProvider
@@ -125,11 +119,8 @@ You can follow the steps to set up an OAuth mode Gravitino
server.
2. Set up an external OAuth 2.0 server
- There is a sample-authorization-server based on
[spring-authorization-server](https://github.com/spring-projects/spring-authorization-server/tree/1.0.3).
-
- The image has registered client information in the external OAuth 2.0
server.
-
- Its clientId is `test`. Its secret is `test`. Its scope is `test`.
+ There is a sample-authorization-server based on
[spring-authorization-server](https://github.com/spring-projects/spring-authorization-server/tree/1.0.3).
The image has registered client information in the external OAuth 2.0 server
+ and its clientId is `test`, secret is `test`, scope is `test`.
```shell
docker run -p 8177:8177 --name sample-auth-server -d
datastrato/sample-authorization-server:0.3.0
diff --git a/docs/security/how-to-use-https.md
b/docs/security/how-to-use-https.md
index 100af836b..e489e7439 100644
--- a/docs/security/how-to-use-https.md
+++ b/docs/security/how-to-use-https.md
@@ -7,47 +7,45 @@ license: "This software is licensed under the Apache License
version 2."
## HTTPS
-Users would better use HTTPS instead of HTTP if users choose OAuth 2.0 as the
authenticator.
+For users choosing OAuth 2.0 as the authentication method, it is recommended
to use HTTPS instead of HTTP. HTTPS encrypts the request headers, offering
better protection against smuggling attacks.
-HTTPS protects the header of the request from smuggling, making it safer.
+Note that Gravitino cannot simultaneously support both HTTP and HTTPS within a
single server instance. If HTTPS is enabled, Gravitino will no longer provide
HTTP service.
-If users choose to enable HTTPS, Gravitino won't provide the ability of HTTP
service.
-
-Both the Gravitino server and Iceberg REST service can configure HTTPS.
+Currently, both the Gravitino server and Iceberg REST service can configure
and support HTTPS.
### Apache Gravitino server's configuration
-| Configuration item | Description
| Default value | Required
| Since version |
-|-----------------------------------------------------|--------------------------------------------------------------------|---------------|---------------------------------------------------|---------------|
-| `gravitino.server.webserver.enableHttps` | Enables HTTPS.
| `false` | No
| 0.3.0 |
-| `gravitino.server.webserver.httpsPort` | The HTTPS port number
of the Jetty web server. | `8433` | No
| 0.3.0 |
-| `gravitino.server.webserver.keyStorePath` | Path to the key store
file. | (none) | Yes if use HTTPS
| 0.3.0 |
-| `gravitino.server.webserver.keyStorePassword` | Password to the key
store. | (none) | Yes if use
HTTPS | 0.3.0 |
-| `gravitino.server.webserver.keyStoreType` | The type to the key
store. | `JKS` | No
| 0.3.0 |
-| `gravitino.server.webserver.managerPassword` | Manager password to
the key store. | (none) | Yes if use
HTTPS | 0.3.0 |
-| `gravitino.server.webserver.tlsProtocol` | TLS protocol to use.
The JVM must support the TLS protocol to use. | (none) | No
| 0.3.0 |
-| `gravitino.server.webserver.enableCipherAlgorithms` | The collection of
enabled cipher algorithms. | `` | No
| 0.3.0 |
-| `gravitino.server.webserver.enableClientAuth` | Enables the
authentication of the client. | `false` | No
| 0.3.0 |
-| `gravitino.server.webserver.trustStorePath` | Path to the trust
store file. | (none) | Yes if use
HTTPS and the authentication of client | 0.3.0 |
-| `gravitino.server.webserver.trustStorePassword` | Password to the trust
store. | (none) | Yes if use HTTPS
and the authentication of client | 0.3.0 |
-| `gravitino.server.webserver.trustStoreType` | The type to the trust
store. | `JKS` | No
| 0.3.0 |
+| Configuration item | Description
| Default value | Required
| Since version |
+|-----------------------------------------------------|--------------------------------------------------------------------|---------------------|---------------------------------------------------|---------------|
+| `gravitino.server.webserver.enableHttps` | Enables HTTPS.
| `false` | No
| 0.3.0 |
+| `gravitino.server.webserver.httpsPort` | The HTTPS port number
of the Jetty web server. | `8433` | No
| 0.3.0 |
+| `gravitino.server.webserver.keyStorePath` | Path to the key store
file. | (none) | Yes if use
HTTPS | 0.3.0 |
+| `gravitino.server.webserver.keyStorePassword` | Password to the key
store. | (none) | Yes if
use HTTPS | 0.3.0 |
+| `gravitino.server.webserver.keyStoreType` | The type to the key
store. | `JKS` | No
| 0.3.0 |
+| `gravitino.server.webserver.managerPassword` | Manager password to
the key store. | (none) | Yes if
use HTTPS | 0.3.0 |
+| `gravitino.server.webserver.tlsProtocol` | TLS protocol to use.
The JVM must support the TLS protocol to use. | (none) | No
| 0.3.0 |
+| `gravitino.server.webserver.enableCipherAlgorithms` | The collection of
enabled cipher algorithms. | '' (empty string) | No
| 0.3.0 |
+| `gravitino.server.webserver.enableClientAuth` | Enables the
authentication of the client. | `false` |
No | 0.3.0 |
+| `gravitino.server.webserver.trustStorePath` | Path to the trust
store file. | (none) | Yes if
use HTTPS and the authentication of client | 0.3.0 |
+| `gravitino.server.webserver.trustStorePassword` | Password to the trust
store. | (none) | Yes if use
HTTPS and the authentication of client | 0.3.0 |
+| `gravitino.server.webserver.trustStoreType` | The type to the trust
store. | `JKS` | No
| 0.3.0 |
### Apache Iceberg REST service's configuration
-| Configuration item | Description
| Default value | Required
| Since version |
-|-------------------------------------------------|--------------------------------------------------------------------|---------------|---------------------------------------------------|---------------|
-| `gravitino.iceberg-rest.enableHttps` | Enables HTTPS.
| `false` | No
| 0.3.0 |
-| `gravitino.iceberg-rest.httpsPort` | The HTTPS port number of
the Jetty web server. | `9433` | No
| 0.3.0 |
-| `gravitino.iceberg-rest.keyStorePath` | Path to the key store
file. | (none) | Yes if use HTTPS
| 0.3.0 |
-| `gravitino.iceberg-rest.keyStorePassword` | Password to the key store.
| (none) | Yes if use HTTPS
| 0.3.0 |
-| `gravitino.iceberg-rest.keyStoreType` | The type to the key store.
| `JKS` | No
| 0.3.0 |
-| `gravitino.iceberg-rest.managerPassword` | Manager password to the
key store. | (none) | Yes if use HTTPS
| 0.3.0 |
-| `gravitino.iceberg-rest.tlsProtocol` | TLS protocol to use. The
JVM must support the TLS protocol to use. | (none) | No
| 0.3.0 |
-| `gravitino.iceberg-rest.enableCipherAlgorithms` | The collection of enabled
cipher algorithms. | `` | No
| 0.3.0 |
-| `gravitino.iceberg-rest.enableClientAuth` | Enables the authentication
of the client. | `false` | No
| 0.3.0 |
-| `gravitino.iceberg-rest.trustStorePath` | Path to the trust store
file. | (none) | Yes if use HTTPS
and the authentication of client | 0.3.0 |
-| `gravitino.iceberg-rest.trustStorePassword` | Password to the trust
store. | (none) | Yes if use HTTPS
and the authentication of client | 0.3.0 |
-| `gravitino.iceberg-rest.trustStoreType` | The type to the trust
store. | `JKS` | No
| 0.3.0 |
+| Configuration item | Description
| Default value | Required
| Since version |
+|-------------------------------------------------|--------------------------------------------------------------------|-------------------|---------------------------------------------------|---------------|
+| `gravitino.iceberg-rest.enableHttps` | Enables HTTPS.
| `false` | No
| 0.3.0 |
+| `gravitino.iceberg-rest.httpsPort` | The HTTPS port number of
the Jetty web server. | `9433` | No
| 0.3.0 |
+| `gravitino.iceberg-rest.keyStorePath` | Path to the key store
file. | (none) | Yes if use
HTTPS | 0.3.0 |
+| `gravitino.iceberg-rest.keyStorePassword` | Password to the key store.
| (none) | Yes if use HTTPS
| 0.3.0 |
+| `gravitino.iceberg-rest.keyStoreType` | The type to the key store.
| `JKS` | No
| 0.3.0 |
+| `gravitino.iceberg-rest.managerPassword` | Manager password to the
key store. | (none) | Yes if use
HTTPS | 0.3.0 |
+| `gravitino.iceberg-rest.tlsProtocol` | TLS protocol to use. The
JVM must support the TLS protocol to use. | (none) | No
| 0.3.0 |
+| `gravitino.iceberg-rest.enableCipherAlgorithms` | The collection of enabled
cipher algorithms. | '' (empty string) | No
| 0.3.0 |
+| `gravitino.iceberg-rest.enableClientAuth` | Enables the authentication
of the client. | `false` | No
| 0.3.0 |
+| `gravitino.iceberg-rest.trustStorePath` | Path to the trust store
file. | (none) | Yes if use
HTTPS and the authentication of client | 0.3.0 |
+| `gravitino.iceberg-rest.trustStorePassword` | Password to the trust
store. | (none) | Yes if use
HTTPS and the authentication of client | 0.3.0 |
+| `gravitino.iceberg-rest.trustStoreType` | The type to the trust
store. | `JKS` | No
| 0.3.0 |
Refer to the "Additional JSSE Standard Names" section of the [Java security
guide](https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#jssenames)
for the list of protocols related to tlsProtocol. You can find the list of
`tlsProtocol` values for Java 8 in this document.
@@ -58,11 +56,8 @@ Refer to the "Additional JSSE Standard Names" section of the
[Java security guid
You can follow the steps to set up an HTTPS server.
1. Prerequisite
-
- You need to install the JDK8, wget, and set the environment JAVA_HOME.
-
- If you want to use the command `curl` to request the Gravitino server, you
should install openSSL.
-
+ - You need to install the JDK8, wget, and set the environment JAVA_HOME.
+ - If you want to use the command `curl` to request the Gravitino server,
you should install openSSL.
2. Generate the key store
```shell
@@ -101,9 +96,7 @@ gravitino.server.webserver.managerPassword = localhost
6. Request the Gravitino server
- If you use Java, you can follow the steps
-
- Copy the code to a file named Main.java
+- If you use Java, you can copy the code below to a file named Main.java
```java
import org.apache.gravitino.client.GravitinoClient;
@@ -119,7 +112,7 @@ public class Main {
}
```
-If you want to use the command `curl`, you can follow the commands:
+- If you want to use the command `curl`, you can follow the commands:
```shell
openssl x509 -inform der -in $JAVA_HOME/localhost.crt -out certificate.pem
diff --git a/docs/security/security.md b/docs/security/security.md
index e09aab701..62ffa268d 100644
--- a/docs/security/security.md
+++ b/docs/security/security.md
@@ -11,10 +11,12 @@ Gravitino provides features that ensure the highest levels
of security for you.
## Capabilities
-### Supports [Authentication](how-to-authenticate.md)
+Gravitino has supported the following security features:
-### Supports [HTTPS](how-to-use-https.md)
+### [Authentication](how-to-authenticate.md)
-### Supports [Access Control](access-control.md)
+### [HTTPS](how-to-use-https.md)
-### Supports [CORS](how-to-use-cors.md)
\ No newline at end of file
+### [Access Control](access-control.md)
+
+### [CORS](how-to-use-cors.md)
\ No newline at end of file
