This is an automated email from the ASF dual-hosted git repository.
jshao pushed a commit to branch branch-0.6
in repository https://gitbox.apache.org/repos/asf/gravitino.git
The following commit(s) were added to refs/heads/branch-0.6 by this push:
new 2bab1d2b7 [#4467] improve(docs): Refactor the security document and
add access control page (#4538)
2bab1d2b7 is described below
commit 2bab1d2b756fa0aae745ef5684941c889fb3b38b
Author: roryqi <[email protected]>
AuthorDate: Thu Aug 15 17:44:01 2024 +0800
[#4467] improve(docs): Refactor the security document and add access
control page (#4538)
### What changes were proposed in this pull request?
Refactor the security document and add access control page.
### Why are the changes needed?
Fix: #4467
### Does this PR introduce _any_ user-facing change?
No.
### How was this patch tested?
Just docs.
---
docs/assets/object.png | Bin 0 -> 97593 bytes
docs/assets/privilege.png | Bin 0 -> 73113 bytes
docs/assets/role.png | Bin 0 -> 137049 bytes
docs/assets/user-group.png | Bin 0 -> 138859 bytes
docs/assets/workflow.png | Bin 0 -> 227766 bytes
docs/gravitino-server-config.md | 2 +-
docs/how-to-use-gvfs.md | 4 +-
docs/iceberg-rest-service.md | 2 +-
docs/index.md | 11 +-
docs/security.md | 327 ------------------
docs/security/access-control.md | 640 +++++++++++++++++++++++++++++++++++
docs/security/how-to-authenticate.md | 174 ++++++++++
docs/security/how-to-use-cors.md | 36 ++
docs/security/how-to-use-https.md | 127 +++++++
docs/security/security.md | 20 ++
docs/webui.md | 6 +-
16 files changed, 1013 insertions(+), 336 deletions(-)
diff --git a/docs/assets/object.png b/docs/assets/object.png
new file mode 100644
index 000000000..9eafcc2fe
Binary files /dev/null and b/docs/assets/object.png differ
diff --git a/docs/assets/privilege.png b/docs/assets/privilege.png
new file mode 100644
index 000000000..cef89e271
Binary files /dev/null and b/docs/assets/privilege.png differ
diff --git a/docs/assets/role.png b/docs/assets/role.png
new file mode 100644
index 000000000..4345dd8f2
Binary files /dev/null and b/docs/assets/role.png differ
diff --git a/docs/assets/user-group.png b/docs/assets/user-group.png
new file mode 100644
index 000000000..b26773e3e
Binary files /dev/null and b/docs/assets/user-group.png differ
diff --git a/docs/assets/workflow.png b/docs/assets/workflow.png
new file mode 100644
index 000000000..83a4bae24
Binary files /dev/null and b/docs/assets/workflow.png differ
diff --git a/docs/gravitino-server-config.md b/docs/gravitino-server-config.md
index 4f3fba6c7..785269024 100644
--- a/docs/gravitino-server-config.md
+++ b/docs/gravitino-server-config.md
@@ -140,7 +140,7 @@ For more details, please refer to the definition of the
plugin.
### Security configuration
-Refer to [security](security.md) for HTTPS and authentication configurations.
+Refer to [security](security/security.md) for HTTPS and authentication
configurations.
### Metrics configuration
diff --git a/docs/how-to-use-gvfs.md b/docs/how-to-use-gvfs.md
index 579bd981e..ec3dd6ccd 100644
--- a/docs/how-to-use-gvfs.md
+++ b/docs/how-to-use-gvfs.md
@@ -274,7 +274,7 @@ FileSystem fs = filesetPath.getFileSystem(conf);
##### Using `OAuth` authentication
If you want to use `oauth2` authentication for the Gravitino client in the
Gravitino Virtual File System,
-please refer to this document to complete the configuration of the Gravitino
server and the OAuth server: [Security](./security.md).
+please refer to this document to complete the configuration of the Gravitino
server and the OAuth server: [Security](security/security.md).
Then, you can configure the Hadoop configuration like this:
@@ -298,7 +298,7 @@ FileSystem fs = filesetPath.getFileSystem(conf);
##### Using `Kerberos` authentication
If you want to use `kerberos` authentication for the Gravitino client in the
Gravitino Virtual File System,
-please refer to this document to complete the configuration of the Gravitino
server: [Security](./security.md).
+please refer to this document to complete the configuration of the Gravitino
server: [Security](security/security.md).
Then, you can configure the Hadoop configuration like this:
diff --git a/docs/iceberg-rest-service.md b/docs/iceberg-rest-service.md
index e0e790b5e..3b2c239b3 100644
--- a/docs/iceberg-rest-service.md
+++ b/docs/iceberg-rest-service.md
@@ -81,7 +81,7 @@ You can also specify filter parameters by setting
configuration entries in the s
### Security
-Gravitino Iceberg REST server supports OAuth2 and HTTPS, please refer to
[Security](./security.md) for more details.
+Gravitino Iceberg REST server supports OAuth2 and HTTPS, please refer to
[Security](security/security.md) for more details.
### Storage
diff --git a/docs/index.md b/docs/index.md
index 4909cf34a..7eca72edc 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -144,11 +144,18 @@ Gravitino provides a Flink connector to manage metadata
in a unified way. To use
Gravitino provides several ways to configure and manage the Gravitino server.
See:
-* [Security](./security.md): provides security configurations for Gravitino,
including HTTPS
- and OAuth2 configurations.
* [Gravitino metrics](./metrics.md): provides metrics configurations and
detailed a metrics list
of the Gravitino server.
+### Security
+
+Gravitino provides security configurations for Gravitino, including HTTPS,
authentication and access control configurations.
+
+* [HTTPS](./security/how-to-use-https.md): provides HTTPS configurations.
+* [Authentication](./security/how-to-authenticate.md): provides authentication
configurations including simple, OAuth, Kerberos.
+* [Access Control](./security/access-control.md): provides access control
configurations.
+* [CORS](./security/how-to-use-cors.md): provides CORS configurations.
+
### Programming guides
* [Gravitino Open API](./api/rest/gravitino-rest-api): provides the complete
Open API definition of
diff --git a/docs/security.md b/docs/security.md
deleted file mode 100644
index 87aaeed6f..000000000
--- a/docs/security.md
+++ /dev/null
@@ -1,327 +0,0 @@
----
-title: "Security"
-slug: /security
-keyword: security
-license: "This software is licensed under the Apache License version 2."
----
-
-## Authentication
-
-Apache Gravitino supports three kinds of authentication mechanisms: simple,
OAuth and Kerberos.
-
-### Simple mode
-
-Simple mode is the default authentication option of the server.
-
-For the client side, if it doesn't set the authentication explicitly, it will
use anonymous to access the server.
-
-If the client sets the simple mode, it will use the environment variable
`GRAVITINO_USER` as the user.
-
-If the environment variable `GRAVITINO_USER` isn't set, the client uses the
user of the machine that sends requests.
-
-For the client side, users can enable `simple` mode by the following code:
-
-```java
-GravitinoClient client = GravitinoClient.builder(uri)
- .withMetalake("metalake")
- .withSimpleAuth()
- .build();
-```
-
-### OAuth mode
-
-Gravitino only supports external OAuth 2.0 servers.
-
-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
-`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:
-
-```java
-DefaultOAuth2TokenProvider authDataProvider =
DefaultOAuth2TokenProvider.builder()
- .withUri("oauth server uri")
- .withCredential("yy:xx")
- .withPath("oauth/token")
- .withScope("test")
- .build();
-
-GravitinoClient client = GravitinoClient.builder(uri)
- .withMetalake("metalake")
- .withOAuth(authDataProvider)
- .build();
-```
-
-### 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:
-
-```java
-// Use keytab to create KerberosTokenProvider
-KerberosTokenProvider provider = KerberosTokenProvider.builder()
- .withClientPrincipal(clientPrincipal)
- .withKeyTabFile(new File(keytabFile))
- .build();
-
-// Use ticketCache to create KerberosTokenProvider
-KerberosTokenProvider provider = KerberosTokenProvider.builder()
- .withClientPrincipal(clientPrincipal)
- .build();
-
-GravitinoClient client = GravitinoClient.builder(uri)
- .withMetalake("metalake")
- .withKerberosAuth(provider)
- .build();
-```
-
-:::info
-Now Iceberg REST service doesn't support Kerberos authentication.
-The URI must use the hostname of server instead of IP.
-:::
-
-### Server configuration
-
-| Configuration item | Description
| Default
value | Required | Since version |
-|---------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------|--------------------------------------------|---------------|
-| `gravitino.authenticator` | It is deprecated since
Gravitino 0.6.0. Please use `gravitino.authenticators` instead.
| `simple`
| No | 0.3.0 |
-| `gravitino.authenticators` | The authenticators which
Gravitino uses, setting as `simple`,`oauth` or `kerberos`. Multiple
authenticators are separated by commas. If a request is supported by multiple
authenticators simultaneously, the first authenticator will be used by default
| `simple` | No | 0.6.0
|
-| `gravitino.authenticator.oauth.serviceAudience` | The audience name when
Gravitino uses OAuth as the authenticator.
|
`GravitinoServer` | No | 0.3.0 |
-| `gravitino.authenticator.oauth.allowSkewSecs` | The JWT allows skew
seconds when Gravitino uses OAuth as the authenticator.
| `0`
| No | 0.3.0 |
-| `gravitino.authenticator.oauth.defaultSignKey` | The signing key of JWT
when Gravitino uses OAuth as the authenticator.
| (none)
| Yes if use `oauth` as the authenticator | 0.3.0 |
-| `gravitino.authenticator.oauth.signAlgorithmType` | The signature algorithm
when Gravitino uses OAuth as the authenticator.
| `RS256`
| No | 0.3.0 |
-| `gravitino.authenticator.oauth.serverUri` | The URI of the default
OAuth server.
| (none)
| Yes if use `oauth` as the authenticator | 0.3.0 |
-| `gravitino.authenticator.oauth.tokenPath` | The path for token of
the default OAuth server.
| (none)
| Yes if use `oauth` as the authenticator | 0.3.0 |
-| `gravitino.authenticator.kerberos.principal` | Indicates the Kerberos
principal to be used for HTTP endpoint. Principal should start with `HTTP/`.
| (none)
| Yes if use `kerberos` as the authenticator | 0.4.0 |
-| `gravitino.authenticator.kerberos.keytab` | Location of the keytab
file with the credentials for the principal.
| (none)
| Yes if use `kerberos` as the authenticator | 0.4.0 |
-
-The signature algorithms that Gravitino supports follows:
-
-| Name | Description |
-|-------|------------------------------------------------|
-| HS256 | HMAC using SHA-25A |
-| HS384 | HMAC using SHA-384 |
-| HS512 | HMAC using SHA-51 |
-| RS256 | RSASSA-PKCS-v1_5 using SHA-256 |
-| RS384 | RSASSA-PKCS-v1_5 using SHA-384 |
-| RS512 | RSASSA-PKCS-v1_5 using SHA-512 |
-| ES256 | ECDSA using P-256 and SHA-256 |
-| ES384 | ECDSA using P-384 and SHA-384 |
-| ES512 | ECDSA using P-521 and SHA-512 |
-| PS256 | RSASSA-PSS using SHA-256 and MGF1 with SHA-256 |
-| PS384 | RSASSA-PSS using SHA-384 and MGF1 with SHA-384 |
-| PS512 | RSASSA-PSS using SHA-512 and MGF1 with SHA-512 |
-
-### Example
-
-You can follow the steps to set up an OAuth mode Gravitino server.
-
-1. Prerequisite
-
- You need to install the JDK8 and Docker.
-
-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`.
-
-```shell
- docker run -p 8177:8177 --name sample-auth-server -d
datastrato/sample-authorization-server:0.3.0
-```
-
-3. Open [the JWK URL of the Authorization
server](http://localhost:8177/oauth2/jwks) in the browser and you can get the
JWK.
-
- 
-
-4. Convert the JWK to PEM. You can use the [online
tool](https://8gwifi.org/jwkconvertfunctions.jsp#google_vignette) or other
tools.
-
- 
-
-5. Copy the public key and remove the character `\n` and you can get the
default signing key of Gravitino server.
-
-6. You can refer to the [Configurations](gravitino-server-config.md) and
append the configurations to the conf/gravitino.conf.
-
-```text
-gravitino.authenticators = oauth
-gravitino.authenticator.oauth.serviceAudience = test
-gravitino.authenticator.oauth.defaultSignKey = <the default signing key>
-gravitino.authenticator.oauth.tokenPath = /oauth2/token
-gravitino.authenticator.oauth.serverUri = http://localhost:8177
-```
-
-7. Open [the URL of Gravitino server](http://localhost:8090) and login in with
clientId `test`, clientSecret `test`, and scope `test`.
-
- 
-
-8. You can also use the curl command to access Gravitino.
-
-Get access token
-
-```shell
-curl --location --request POST
'http://127.0.0.1:8177/oauth2/token?grant_type=client_credentials&client_id=test&client_secret=test&scope=test'
-```
-
-Use the access token to request the Gravitino
-
-```shell
-curl -v -X GET -H "Accept: application/vnd.gravitino.v1+json" -H
"Content-Type: application/json" -H "Authorization: Bearer <access_token>"
http://localhost:8090/api/version
-```
-
-## HTTPS
-
-Users would better use HTTPS instead of HTTP if users choose OAuth 2.0 as the
authenticator.
-
-HTTPS protects the header of the request from smuggling, making it safer.
-
-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.
-
-### 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 |
-
-### 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 |
-
-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.
-
-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#ciphersuites)
for the list of protocols related to tlsProtocol. You can find the list of
`enableCipherAlgorithms` values for Java 8 in this document.
-
-### Example
-
-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.
-
-2. Generate the key store
-
-```shell
-cd $JAVA_HOME
-bin/keytool -genkeypair -alias localhost \
--keyalg RSA -keysize 4096 -keypass localhost \
--sigalg SHA256withRSA \
--keystore localhost.jks -storetype JKS -storepass localhost \
--dname "cn=localhost,ou=localhost,o=localhost,l=beijing,st=beijing,c=cn" \
--validity 36500
-```
-
-3. Generate the certificate
-
-```shell
-bin/keytool -export -alias localhost -keystore localhost.jks -file
localhost.crt -storepass localhost
-```
-
-4. Import the certificate
-
-```shell
-bin/keytool -import -alias localhost -keystore jre/lib/security/cacerts -file
localhost.crt -storepass changeit -noprompt
-```
-
-5. You can refer to the [Configurations](gravitino-server-config.md) and
append the configuration to the conf/gravitino.conf.
-Configuration doesn't support resolving environment variables, so you should
replace `${JAVA_HOME}` with the actual value.
-Then, You can start the Gravitino server.
-
-```text
-gravitino.server.webserver.host = localhost
-gravitino.server.webserver.enableHttps = true
-gravitino.server.webserver.keyStorePath = ${JAVA_HOME}/localhost.jks
-gravitino.server.webserver.keyStorePassword = localhost
-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
-
-```java
-import org.apache.gravitino.client.GravitinoClient;
-import org.apache.gravitino.client.GravitinoVersion;
-
-public class Main {
- public static void main(String[] args) {
- String uri = "https://localhost:8433";;
- GravitinoClient client =
GravitinoClient.builder(uri).withMetalake("metalake").build();
- GravitinoVersion gravitinoVersion = client.getVersion();
- System.out.println(gravitinoVersion);
- }
-}
-```
-
-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
-curl -v -X GET --cacert ./certificate.pem -H "Accept:
application/vnd.gravitino.v1+json" -H "Content-Type: application/json"
https://localhost:8433/api/version
-```
-## Cross-origin resource filter
-
-### Server configuration
-
-| Configuration item | Description
| Default value
| Required | Since version |
-|----------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------|----------|---------------|
-| `gravitino.server.webserver.enableCorsFilter` | Enable cross-origin
resource share filter.
| false
| No | 0.4.0 |
-| `gravitino.server.webserver.allowedOrigins` | A comma separated list
of allowed origins to access the resources. The default value is *, which means
all origins.
| `*`
| No | 0.4.0 |
-| `gravitino.server.webserver.allowedTimingOrigins` | A comma separated list
of allowed origins to time the resource. The default value is the empty string,
which means no origins.
| ``
| No | 0.4.0 |
-| `gravitino.server.webserver.allowedMethods` | A comma separated list
of allowed HTTP methods used when accessing the resources. The default values
are GET, POST, HEAD, and DELETE.
| `GET,POST,HEAD,DELETE,PUT`
| No | 0.4.0 |
-| `gravitino.server.webserver.allowedHeaders` | A comma separated list
of allowed HTTP headers specified when accessing the resources. The default
value is X-Requested-With,Content-Type,Accept,Origin. If the value is a single
*, it accepts all headers. |
`X-Requested-With,Content-Type,Accept,Origin` | No | 0.4.0 |
-| `gravitino.server.webserver.preflightMaxAgeInSecs` | The number of seconds
to cache preflight requests by the client. The default value is 1800 seconds or
30 minutes.
| `1800`
| No | 0.4.0 |
-| `gravitino.server.webserver.allowCredentials` | A boolean indicating if
the resource allows requests with credentials. The default value is true.
| `true`
| No | 0.4.0 |
-| `gravitino.server.webserver.exposedHeaders` | A comma separated list
of allowed HTTP headers exposed on the client. The default value is the empty
list.
| ``
| No | 0.4.0 |
-| `gravitino.server.webserver.chainPreflight` | If true chained
preflight requests for normal handling (as an OPTION request). Otherwise, the
filter responds to the preflight. The default is true.
| `true`
| No | 0.4.0 |
-
-### Apache Iceberg REST service's configuration
-
-| Configuration item | Description
| Default value | Required |
Since version |
-|------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------|----------|---------------|
-| `gravitino.iceberg-rest.enableCorsFilter` | Enable cross-origin
resource share filter.
| false | No
| 0.4.0 |
-| `gravitino.iceberg-rest.allowedOrigins` | A comma separated list of
allowed origins that access the resources. The default value is *, which means
all origins.
| `*` | No
| 0.4.0 |
-| `gravitino.iceberg-rest.allowedTimingOrigins` | A comma separated list of
allowed origins that time the resource. The default value is the empty string,
which means no origins.
| `` | No
| 0.4.0 |
-| `gravitino.iceberg-rest.allowedMethods` | A comma separated list of
allowed HTTP methods used when accessing the resources. The default values are
GET, POST, HEAD, and DELETE.
| `GET,POST,HEAD,DELETE,PUT` | No
| 0.4.0 |
-| `gravitino.iceberg-rest.allowedHeaders` | A comma separated list of
HTTP allowed headers specified when accessing the resources. The default value
is X-Requested-With,Content-Type,Accept,Origin. If the value is a single *, it
accepts all headers. | `X-Requested-With,Content-Type,Accept,Origin` | No
| 0.4.0 |
-| `gravitino.iceberg-rest.preflightMaxAgeInSecs` | The number of seconds to
cache preflight requests by the client. The default value is 1800 seconds or 30
minutes.
| `1800` | No
| 0.4.0 |
-| `gravitino.iceberg-rest.allowCredentials` | A boolean indicating if the
resource allows requests with credentials. The default value is true.
| `true` | No |
0.4.0 |
-| `gravitino.iceberg-rest.exposedHeaders` | A comma separated list of
allowed HTTP headers exposed on the client. The default value is the empty
list.
| `` | No
| 0.4.0 |
-| `gravitino.iceberg-rest.chainPreflight` | If true chained preflight
requests for normal handling (as an OPTION request). Otherwise, the filter
responds to the preflight. The default is true.
| `true` | No
| 0.4.0 |
diff --git a/docs/security/access-control.md b/docs/security/access-control.md
new file mode 100644
index 000000000..902fc0591
--- /dev/null
+++ b/docs/security/access-control.md
@@ -0,0 +1,640 @@
+---
+title: "Access Control"
+slug: /security/access-control
+keyword: security
+license: "This software is licensed under the Apache License version 2."
+---
+
+## Overview
+
+Gravitino adopts RBAC and DAC.
+
+Role-based Access Control (RBAC): Access privileges are assigned to roles,
which are in turn assigned to users or groups.
+
+Discretionary Access Control(DAC): Each metadata object has an owner, who can
in turn grant access to that object.
+
+:::info
+
+Gravitino only supports authorization for securable objects, when Gravitino
supports to pass the privileges to underlying authorization plugin.
+Gravitino doesn't support metadata authentication. It means that Gravitino
won't check the privileges when Gravitino receives the requests.
+
+:::
+
+
+## Concept
+
+### Role
+
+A metadata object to which privileges can be granted. Roles are in turn
assigned to users or groups.
+
+### Privilege
+
+A defined level of access to an object. Multiple distinct privileges may be
used to control the granularity of access granted.
+
+### User
+
+A user identity recognized by Gravitino. External user system instead of
Gravitino manages users.
+
+### Group
+
+A group identity recognized by Gravitino. External user system instead of
Gravitino manages groups.
+
+### Metadata objects
+
+Metadata objects are managed in Gravitino, such as `CATALOG`, `SCHEMA`,
`TABLE`,
+`COLUMN`, `FILESET`, `TOPIC`, `COLUMN`, `ROLE`, `METALAKE`. A metadata object
is combined by a `type` and a
+comma-separated `name`. For example, a `CATAGLOG` object has a name "catalog1"
with type
+"CATALOG", a `SCHEMA` object has a name "catalog1.schema1" with type "SCHEMA",
a `TABLE`
+object has a name "catalog1.schema1.table1" with type "TABLE". A `METALAKE`
object has a name "metalake1".
+
+### Securable objects
+
+A metadata object to which access can be granted. Unless allowed by a grant,
access is denied.
+Every securable object resides within a logical container in a hierarchy of
containers.
+The top container is the metalake.
+Catalogs are under the metalake. Catalogs represent different kinds of data
sources.
+Schemas are under the catalog. There are tables, topics, or filesets under the
schema.
+
+
+
+The relationship of the concepts is as below.
+
+
+
+
+### Ownership
+
+Every metadata object has an owner. The owner could be a user or group, and
has all the privileges of the metadata object.
+Meanwhile, you can transfer the ownership of securable object to another user
or group.
+
+## The types of roles
+
+### Service Admin
+
+Service admin is only used for managing the metalakes. Usually, this role is
for the maintainer of the service.
+
+### Custom Roles
+
+You can also create a dedicated role for your business by API or the client.
+
+## The types of privileges
+
+### User privileges
+
+| Name | Supports Securable Object | Operation |
+|-------------|---------------------------|---------------------|
+| ManageUsers | Metalake | Add or remove users |
+
+### Group privileges
+
+| Name | Supports Securable Object | Operation |
+|--------------|---------------------------|----------------------|
+| ManageGroups | Metalake | Add or remove groups |
+
+### Role privileges
+
+| Name | Supports Securable Object | Operation |
+|------------|---------------------------|---------------|
+| CreateRole | Metalake | Create a role |
+
+### Permission privileges
+
+| Name | Supports Securable Object | Operation |
+|--------------|---------------------------|------------------------|
+| ManageGrants | Metalake | grant or revoke a role |
+
+### Catalog privileges
+
+| Name | Supports Securable Object | Operation |
+|---------------|---------------------------|------------------|
+| CreateCatalog | Metalake | Create a catalog |
+| UseCatalog | Metalake, Catalog | |
+
+:::info
+
+`USE_CATALOG` is needed for a user to interact with any object within the
catalog.
+
+For example, to select data from a table, users need to have the SELECT_TABLE
privilege on that table and
+`USE CATALOG` privileges on its parent catalog as well as `USE SCHEMA`
privileges on its parent schema.
+
+:::
+
+### Schema privileges
+
+| Name | Supports Securable Object | Operation |
+|--------------|---------------------------|-----------------|
+| CreateSchema | Metalake, Catalog | Create a schema |
+| UseSchema | Metalake, Catalog, Schema | Use a schema |
+
+:::info
+
+`UseSchema`is needed for a user to interact with any object within the schema.
+
+For example, to select data from a table, users need to have the
`SELECT_TABLE` privilege on that table
+and `USE SCHEMA` privileges on its parent schema.
+
+:::
+
+### Table privileges
+
+| Name | Supports Securable Object | Operation
|
+|-------------|-----------------------------------|------------------------------------------------|
+| CreateTable | Metalake, Catalog, Schema | Create a table
|
+| ModifyTable | Metalake, Catalog, Schema, Table | Use the SQL
`UPDATE`,`DELETE`,`INSERT` a table |
+| SelectTable | Metalake, Catalog, Schema, Table | Use the SQL `SELECT` data
from a table |
+
+### Topic privileges
+
+| Name | Supports Securable Object | Operation
|
+|--------------|----------------------------------|-------------------------------------------|
+| CreateTopic | Metalake, Catalog, Schema | Create a topic
|
+| ProduceTopic | Metalake, Catalog, Schema, Topic | Produce a topic (including
alter a topic) |
+| ConsumeTopic | Metalake, Catalog, Schema, Topic | Consume a topic
|
+
+### Fileset privileges
+
+| Name | Supports Securable Object | Operation
|
+|---------------|------------------------------------|---------------------------------------------|
+| CreateFileset | Metalake, Catalog, Schema | Create a fileset
|
+| WriteFileset | Metalake, Catalog, Schema, Fileset | Write a fileset
(including alter a fileset) |
+| ReadFileset | Metalake, Catalog, Schema, Fileset | read a fileset
|
+
+## Inheritance Model
+
+Securable objects in Gravitino are hierarchical and privileges are inherited
downward.
+
+This means that granting a privilege on a metalake, catalog or schema
automatically grants
+the privilege to all current and future objects within the metalake, catalog
or schema.
+
+For example, if you give a use that `SELECT_TABLE` privilege on a catalog,
then that the user
+will be able to select(read) all tables in that catalog.
+
+## Privilege Condition
+
+The privilege supports two condition: `allow` and `deny`. `allow` means that
you are able to use the privilege,
+`deny` means that you aren't able to use the privilege.
+`deny` condition is prior to `allow` condition. If a role has the `allow`
condition and `deny` condition at the same time.
+The user won't be able to use the privilege.
+
+If parent securable object has the same privilege name with different
condition, the securable object won't override the parent object privilege.
+For example, securable metalake object allows to use the catalog, but
securable catalog denies to use the catalog, the user isn't able to use the
catalog.
+If securable metalake object denies to use the catalog, but securable catalog
allows to use the catalog, the user isn't able to use the catalog, too.
+
+
+
+## Server Configuration
+
+If you want to enable the access control, you should enable the authorization.
+
+The related configuration is as follows.
+
+| Configuration item | Description
| Default value | Required
| Since Version |
+|------------------------------------------|------------------------------------------------------------------------|---------------|----------------------------------|---------------|
+| `gravitino.authorization.enable` | Whether Gravitino enable
authorization or not. | false | No
| 0.5.0 |
+| `gravitino.authorization.serviceAdmins` | The admins of Gravitino service,
Multiple admins are spitted by comma. | (none) | Yes if enables the
authorization | 0.5.0 |
+
+
+## User Operation
+
+### Add a user
+
+You should add the user to your metalake before you use the authorization.
+
+<Tabs groupId='language' queryString>
+<TabItem value="shell" label="Shell">
+
+```shell
+curl -X POST -H "Accept: application/vnd.gravitino.v1+json" \
+-H "Content-Type: application/json" -d '{
+ "name": "user1",
+}' http://localhost:8090/api/metalakes/test/users
+```
+
+</TabItem>
+<TabItem value="java" label="Java">
+
+```java
+GravitinoClient client = ...
+User user =
+ client.addUser("user1");
+```
+
+</TabItem>
+</Tabs>
+
+### Get a user
+
+You can get a user by its name.
+
+<Tabs groupId='language' queryString>
+<TabItem value="shell" label="Shell">
+
+```shell
+curl -X GET -H "Accept: application/vnd.gravitino.v1+json" \
+-H "Content-Type: application/json"
http://localhost:8090/api/metalakes/test/users/user1
+```
+
+</TabItem>
+<TabItem value="java" label="Java">
+
+```java
+GravitinoClient client = ...
+User user =
+ client.getUser("user1");
+```
+
+</TabItem>
+</Tabs>
+
+### Delete a user
+
+You can delete a user by its name.
+
+<Tabs groupId='language' queryString>
+<TabItem value="shell" label="Shell">
+
+```shell
+curl -X DELETE -H "Accept: application/vnd.gravitino.v1+json" \
+-H "Content-Type: application/json"
http://localhost:8090/api/metalakes/test/users/user1
+```
+
+</TabItem>
+<TabItem value="java" label="Java">
+
+```java
+GravitinoClient client = ...
+boolean deleted =
+ client.deleteUser("user1");
+```
+
+</TabItem>
+</Tabs>
+
+## Group Operation
+
+### Add a Group
+
+You should add the group to your metalake before you use the authorization.
+
+<Tabs groupId='language' queryString>
+<TabItem value="shell" label="Shell">
+
+```shell
+curl -X POST -H "Accept: application/vnd.gravitino.v1+json" \
+-H "Content-Type: application/json" -d '{
+ "name": "group1",
+}' http://localhost:8090/api/metalakes/test/groups
+```
+
+</TabItem>
+<TabItem value="java" label="Java">
+
+```java
+GravitinoClient client = ...
+Group group =
+ client.addGroup("group1");
+```
+
+</TabItem>
+</Tabs>
+
+### Get a group
+
+You can get a group by its name.
+
+<Tabs groupId='language' queryString>
+<TabItem value="shell" label="Shell">
+
+```shell
+curl -X GET -H "Accept: application/vnd.gravitino.v1+json" \
+-H "Content-Type: application/json"
http://localhost:8090/api/metalakes/test/groups/group1
+```
+
+</TabItem>
+<TabItem value="java" label="Java">
+
+```java
+GravitinoClient client = ...
+Group group =
+ client.getGroup("group1");
+```
+
+</TabItem>
+</Tabs>
+
+### Delete a group
+
+You can delete a group by its name.
+
+<Tabs groupId='language' queryString>
+<TabItem value="shell" label="Shell">
+
+```shell
+curl -X DELETE -H "Accept: application/vnd.gravitino.v1+json" \
+-H "Content-Type: application/json"
http://localhost:8090/api/metalakes/test/groups/group1
+```
+
+</TabItem>
+<TabItem value="java" label="Java">
+
+```java
+GravitinoClient client = ...
+boolean deleted =
+ client.deleteGroup("group1");
+```
+
+</TabItem>
+</Tabs>
+
+## Role Operation
+
+### Create a role
+
+You can create a role by given properties.
+
+<Tabs groupId='language' queryString>
+<TabItem value="shell" label="Shell">
+
+```shell
+curl -X POST -H "Accept: application/vnd.gravitino.v1+json" \
+-H "Content-Type: application/json" -d '{
+ "name": "role1",
+ "properties": {"k1", "v1"}
+ "securableObjects": [
+ {
+ "fullName": "catalog1.schema1.table1",
+ "type": "TABLE",
+ "privileges": [
+ {
+ "name": "SELECT_TABLE",
+ "condition": "ALLOW"
+ }
+ ]
+ }
+ ]
+}' http://localhost:8090/api/metalakes/test/roles
+```
+
+</TabItem>
+<TabItem value="java" label="Java">
+
+```java
+GravitinoClient client = ...
+
+SecurableObject securableObject =
+ SecurableObjects.ofTable(
+ SecurableObjects.ofSchema(
+ SecurableObjects.ofCatalog("catalog1", Collections.emptyList()),
+ "schema1",
+ Collections.emptyList()),
+ "table1",
+ Lists.newArrayList(Privileges.SelectTable.allow()));
+
+Role role =
+ client.createRole("role1", ImmutableMap.of("k1", "v1"),
Lists.newArrayList(securableObject));
+```
+
+</TabItem>
+</Tabs>
+
+### Get a role
+
+You can get a role by its name.
+
+<Tabs groupId='language' queryString>
+<TabItem value="shell" label="Shell">
+
+```shell
+curl -X GET -H "Accept: application/vnd.gravitino.v1+json" \
+-H "Content-Type: application/json" -d
http://localhost:8090/api/metalakes/test/roles/role1
+```
+
+</TabItem>
+<TabItem value="java" label="Java">
+
+```java
+GravitinoClient client = ...
+Role role =
+ client.getRole("role1");
+```
+
+</TabItem>
+</Tabs>
+
+### Delete a role
+
+You can delete a role by its name.
+
+<Tabs groupId='language' queryString>
+<TabItem value="shell" label="Shell">
+
+```shell
+curl -X DELETE -H "Accept: application/vnd.gravitino.v1+json" \
+-H "Content-Type: application/json"
http://localhost:8090/api/metalakes/test/roles/role1
+```
+
+</TabItem>
+<TabItem value="java" label="Java">
+
+```java
+GravitinoClient client = ...
+boolean deleted =
+ client.deleteRole("role1");
+```
+
+</TabItem>
+</Tabs>
+
+## Permission Operation
+
+### Grant roles to a user
+
+You can grant specific roles to a user.
+
+<Tabs groupId='language' queryString>
+<TabItem value="shell" label="Shell">
+
+```shell
+curl -X PUT -H "Accept: application/vnd.gravitino.v1+json" \
+-H "Content-Type: application/json" -d '{
+ "roleNames": ["role1"]
+}'http://localhost:8090/api/metalakes/test/permissions/users/user1/grant
+```
+
+</TabItem>
+<TabItem value="java" label="Java">
+
+```java
+GravitinoClient client = ...
+User user = client.grantRolesToUser(Lists.newList("role1"), "user1");
+```
+
+</TabItem>
+</Tabs>
+
+### Revoke roles from a user
+
+You can revoke specific roles from a user.
+
+<Tabs groupId='language' queryString>
+<TabItem value="shell" label="Shell">
+
+```shell
+curl -X PUT -H "Accept: application/vnd.gravitino.v1+json" \
+-H "Content-Type: application/json" -d '{
+ "roleNames": ["role1"]
+}'http://localhost:8090/api/metalakes/test/permissions/users/user1/revoke
+```
+
+</TabItem>
+<TabItem value="java" label="Java">
+
+```java
+GravitinoClient client = ...
+User user = client.revokeRolesFromUser(Lists.newList("role1"), "user1");
+```
+
+</TabItem>
+</Tabs>
+
+
+### Grant roles to a group
+
+You can grant specific roles to a group.
+
+<Tabs groupId='language' queryString>
+<TabItem value="shell" label="Shell">
+
+```shell
+curl -X PUT -H "Accept: application/vnd.gravitino.v1+json" \
+-H "Content-Type: application/json" -d '{
+ "roleNames": ["role1"]
+}'http://localhost:8090/api/metalakes/test/permissions/groups/group1/grant
+```
+
+</TabItem>
+<TabItem value="java" label="Java">
+
+```java
+GravitinoClient client = ...
+Group group = client.grantRolesToGroup(Lists.newList("role1"), "group1");
+```
+
+</TabItem>
+</Tabs>
+
+### Revoke roles from a group
+
+You can revoke specific roles from a group.
+
+<Tabs groupId='language' queryString>
+<TabItem value="shell" label="Shell">
+
+```shell
+curl -X PUT -H "Accept: application/vnd.gravitino.v1+json" \
+-H "Content-Type: application/json" -d '{
+ "roleNames": ["role1"]
+}'http://localhost:8090/api/metalakes/test/permissions/groups/group1/revoke
+```
+
+</TabItem>
+<TabItem value="java" label="Java">
+
+```java
+GravitinoClient client = ...
+Group group = client.grantRolesToGroup(Lists.newList("role1"), "group1");
+```
+
+</TabItem>
+</Tabs>
+
+## Ownership Operation
+
+### get the owner
+
+You can get the owner of a metadata object.
+
+<Tabs groupId='language' queryString>
+<TabItem value="shell" label="Shell">
+
+```shell
+curl -X GET -H "Accept: application/vnd.gravitino.v1+json" \
+-H "Content-Type: application/json"
http://localhost:8090/api/metalakes/test/owners/table/catalog1.schema1.table1
+```
+
+</TabItem>
+<TabItem value="java" label="Java">
+
+```java
+GravitinoClient client = ...
+
+MetadataObject table =
+ MetadataObjects.of(Lists.newArrayList("catalog1", "schema1",
"table1"), MetadataObject.Type.TABLE);
+
+Owner owner = client.getOwner(table);
+```
+
+</TabItem>
+</Tabs>
+
+### set the owner
+
+You can set the owner of a metadata object.
+
+<Tabs groupId='language' queryString>
+<TabItem value="shell" label="Shell">
+
+```shell
+curl -X PUT -H "Accept: application/vnd.gravitino.v1+json" \
+-H "Content-Type: application/json" -d '{
+ "name": "user1",
+ "type": "USER"
+}'http://localhost:8090/api/metalakes/test/owners/table/catalog1.schema1.table1
+```
+
+</TabItem>
+<TabItem value="java" label="Java">
+
+```java
+GravitinoClient client = ...
+
+MetadataObject table =
+ MetadataObjects.of(Lists.newArrayList("catalog1", "schema1",
"table1"), MetadataObject.Type.TABLE);
+
+client.setOwner(table, "user1", "USER");
+```
+
+</TabItem>
+</Tabs>
+
+## Example
+
+You can follow the steps to achieve the authorization of Gravitino.
+
+
+
+1. Service admin configures the Gravitino server to enable authorization and
creates a metalake.
+
+2. Service admin adds the user `Manager` to the metalake.
+
+3. Service admin sets the `Manager` as the owner of the metalake.
+
+4. `Manager` adds the user `Staff`.
+
+5. `Manager` creates a specific role `catalog_manager` with `CREATE_CATALOG`
privilege.
+
+6. `Manager` grants the role `catalog_manager` to the user `Staff`.
+
+7. `Staff` creates a Hive type catalog.
+
+8. `Staff` creates a schema `hive_db` for Hive catalog.
+
+9. `Staff` creates a table `hive_table` under the schema `hive_db`.
+
+10. `Staff` creates a MySQL type catalog.
+
+11. `Staff` creates a schema `mysql_db` for MySQL catalog.
+
+12. `Staff` creates a table `mysql_table` under the schema `mysql_db`.
+
+13. `Staff` can use Gravitino connector to query the tables from different
catalogs.
diff --git a/docs/security/how-to-authenticate.md
b/docs/security/how-to-authenticate.md
new file mode 100644
index 000000000..a18421807
--- /dev/null
+++ b/docs/security/how-to-authenticate.md
@@ -0,0 +1,174 @@
+---
+title: "How to authenticate"
+slug: /security/how-to-authenticate
+keyword: security authentication oauth kerberos
+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.
+
+### Simple mode
+
+If the client sets the simple mode, it will use the 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:
+
+```java
+GravitinoClient client = GravitinoClient.builder(uri)
+ .withMetalake("metalake")
+ .withSimpleAuth()
+ .build();
+```
+
+### OAuth mode
+
+Gravitino only supports external OAuth 2.0 servers.
+
+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
+`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:
+
+```java
+DefaultOAuth2TokenProvider authDataProvider =
DefaultOAuth2TokenProvider.builder()
+ .withUri("oauth server uri")
+ .withCredential("yy:xx")
+ .withPath("oauth/token")
+ .withScope("test")
+ .build();
+
+GravitinoClient client = GravitinoClient.builder(uri)
+ .withMetalake("metalake")
+ .withOAuth(authDataProvider)
+ .build();
+```
+
+### 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:
+
+```java
+// Use keytab to create KerberosTokenProvider
+KerberosTokenProvider provider = KerberosTokenProvider.builder()
+ .withClientPrincipal(clientPrincipal)
+ .withKeyTabFile(new File(keytabFile))
+ .build();
+
+// Use ticketCache to create KerberosTokenProvider
+KerberosTokenProvider provider = KerberosTokenProvider.builder()
+ .withClientPrincipal(clientPrincipal)
+ .build();
+
+GravitinoClient client = GravitinoClient.builder(uri)
+ .withMetalake("metalake")
+ .withKerberosAuth(provider)
+ .build();
+```
+
+:::info
+Now Iceberg REST service doesn't support Kerberos authentication.
+The URI must use the hostname of server instead of IP.
+:::
+
+### Server configuration
+
+| Configuration item | Description
| Default
value | Required | Since version |
+|---------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------|--------------------------------------------|---------------|
+| `gravitino.authenticator` | It is deprecated since
Gravitino 0.6.0. Please use `gravitino.authenticators` instead.
| `simple`
| No | 0.3.0 |
+| `gravitino.authenticators` | The authenticators which
Gravitino uses, setting as `simple`,`oauth` or `kerberos`. Multiple
authenticators are separated by commas. If a request is supported by multiple
authenticators simultaneously, the first authenticator will be used by default.
| `simple` | No | 0.6.0
|
+| `gravitino.authenticator.oauth.serviceAudience` | The audience name when
Gravitino uses OAuth as the authenticator.
|
`GravitinoServer` | No | 0.3.0 |
+| `gravitino.authenticator.oauth.allowSkewSecs` | The JWT allows skew
seconds when Gravitino uses OAuth as the authenticator.
| `0`
| No | 0.3.0 |
+| `gravitino.authenticator.oauth.defaultSignKey` | The signing key of JWT
when Gravitino uses OAuth as the authenticator.
| (none)
| Yes if use `oauth` as the authenticator | 0.3.0 |
+| `gravitino.authenticator.oauth.signAlgorithmType` | The signature algorithm
when Gravitino uses OAuth as the authenticator.
| `RS256`
| No | 0.3.0 |
+| `gravitino.authenticator.oauth.serverUri` | The URI of the default
OAuth server.
| (none)
| Yes if use `oauth` as the authenticator | 0.3.0 |
+| `gravitino.authenticator.oauth.tokenPath` | The path for token of
the default OAuth server.
| (none)
| Yes if use `oauth` as the authenticator | 0.3.0 |
+| `gravitino.authenticator.kerberos.principal` | Indicates the Kerberos
principal to be used for HTTP endpoint. Principal should start with `HTTP/`.
| (none)
| Yes if use `kerberos` as the authenticator | 0.4.0 |
+| `gravitino.authenticator.kerberos.keytab` | Location of the keytab
file with the credentials for the principal.
| (none)
| Yes if use `kerberos` as the authenticator | 0.4.0 |
+
+The signature algorithms that Gravitino supports follows:
+
+| Name | Description |
+|-------|------------------------------------------------|
+| HS256 | HMAC using SHA-25A |
+| HS384 | HMAC using SHA-384 |
+| HS512 | HMAC using SHA-51 |
+| RS256 | RSASSA-PKCS-v1_5 using SHA-256 |
+| RS384 | RSASSA-PKCS-v1_5 using SHA-384 |
+| RS512 | RSASSA-PKCS-v1_5 using SHA-512 |
+| ES256 | ECDSA using P-256 and SHA-256 |
+| ES384 | ECDSA using P-384 and SHA-384 |
+| ES512 | ECDSA using P-521 and SHA-512 |
+| PS256 | RSASSA-PSS using SHA-256 and MGF1 with SHA-256 |
+| PS384 | RSASSA-PSS using SHA-384 and MGF1 with SHA-384 |
+| PS512 | RSASSA-PSS using SHA-512 and MGF1 with SHA-512 |
+
+### Example
+
+You can follow the steps to set up an OAuth mode Gravitino server.
+
+1. Prerequisite
+
+ You need to install the JDK8 and Docker.
+
+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`.
+
+```shell
+ docker run -p 8177:8177 --name sample-auth-server -d
datastrato/sample-authorization-server:0.3.0
+```
+
+3. Open [the JWK URL of the Authorization
server](http://localhost:8177/oauth2/jwks) in the browser and you can get the
JWK.
+
+ 
+
+4. Convert the JWK to PEM. You can use the [online
tool](https://8gwifi.org/jwkconvertfunctions.jsp#google_vignette) or other
tools.
+
+ 
+
+5. Copy the public key and remove the character `\n` and you can get the
default signing key of Gravitino server.
+
+6. You can refer to the [Configurations](gravitino-server-config.md) and
append the configurations to the conf/gravitino.conf.
+
+```text
+gravitino.authenticators = oauth
+gravitino.authenticator.oauth.serviceAudience = test
+gravitino.authenticator.oauth.defaultSignKey = <the default signing key>
+gravitino.authenticator.oauth.tokenPath = /oauth2/token
+gravitino.authenticator.oauth.serverUri = http://localhost:8177
+```
+
+7. Open [the URL of Gravitino server](http://localhost:8090) and login in with
clientId `test`, clientSecret `test`, and scope `test`.
+
+ 
+
+8. You can also use the curl command to access Gravitino.
+
+Get access token
+
+```shell
+curl --location --request POST
'http://127.0.0.1:8177/oauth2/token?grant_type=client_credentials&client_id=test&client_secret=test&scope=test'
+```
+
+Use the access token to request the Gravitino
+
+```shell
+curl -v -X GET -H "Accept: application/vnd.gravitino.v1+json" -H
"Content-Type: application/json" -H "Authorization: Bearer <access_token>"
http://localhost:8090/api/version
+```
\ No newline at end of file
diff --git a/docs/security/how-to-use-cors.md b/docs/security/how-to-use-cors.md
new file mode 100644
index 000000000..c124a021e
--- /dev/null
+++ b/docs/security/how-to-use-cors.md
@@ -0,0 +1,36 @@
+---
+title: "How to use CORS"
+slug: /security/how-use-cors
+keyword: security cors
+license: "This software is licensed under the Apache License version 2."
+---
+
+## Cross-origin resource filter
+
+### Server configuration
+
+| Configuration item | Description
| Default value
| Required | Since version |
+|----------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------|----------|---------------|
+| `gravitino.server.webserver.enableCorsFilter` | Enable cross-origin
resource share filter.
| false
| No | 0.4.0 |
+| `gravitino.server.webserver.allowedOrigins` | A comma separated list
of allowed origins to access the resources. The default value is *, which means
all origins.
| `*`
| No | 0.4.0 |
+| `gravitino.server.webserver.allowedTimingOrigins` | A comma separated list
of allowed origins to time the resource. The default value is the empty string,
which means no origins.
| ``
| No | 0.4.0 |
+| `gravitino.server.webserver.allowedMethods` | A comma separated list
of allowed HTTP methods used when accessing the resources. The default values
are GET, POST, HEAD, and DELETE.
| `GET,POST,HEAD,DELETE,PUT`
| No | 0.4.0 |
+| `gravitino.server.webserver.allowedHeaders` | A comma separated list
of allowed HTTP headers specified when accessing the resources. The default
value is X-Requested-With,Content-Type,Accept,Origin. If the value is a single
*, it accepts all headers. |
`X-Requested-With,Content-Type,Accept,Origin` | No | 0.4.0 |
+| `gravitino.server.webserver.preflightMaxAgeInSecs` | The number of seconds
to cache preflight requests by the client. The default value is 1800 seconds or
30 minutes.
| `1800`
| No | 0.4.0 |
+| `gravitino.server.webserver.allowCredentials` | A boolean indicating if
the resource allows requests with credentials. The default value is true.
| `true`
| No | 0.4.0 |
+| `gravitino.server.webserver.exposedHeaders` | A comma separated list
of allowed HTTP headers exposed on the client. The default value is the empty
list.
| ``
| No | 0.4.0 |
+| `gravitino.server.webserver.chainPreflight` | If true chained
preflight requests for normal handling (as an OPTION request). Otherwise, the
filter responds to the preflight. The default is true.
| `true`
| No | 0.4.0 |
+
+### Apache Iceberg REST service's configuration
+
+| Configuration item | Description
| Default value | Required |
Since version |
+|------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------|----------|---------------|
+| `gravitino.iceberg-rest.enableCorsFilter` | Enable cross-origin
resource share filter.
| false | No
| 0.4.0 |
+| `gravitino.iceberg-rest.allowedOrigins` | A comma separated list of
allowed origins that access the resources. The default value is *, which means
all origins.
| `*` | No
| 0.4.0 |
+| `gravitino.iceberg-rest.allowedTimingOrigins` | A comma separated list of
allowed origins that time the resource. The default value is the empty string,
which means no origins.
| `` | No
| 0.4.0 |
+| `gravitino.iceberg-rest.allowedMethods` | A comma separated list of
allowed HTTP methods used when accessing the resources. The default values are
GET, POST, HEAD, and DELETE.
| `GET,POST,HEAD,DELETE,PUT` | No
| 0.4.0 |
+| `gravitino.iceberg-rest.allowedHeaders` | A comma separated list of
HTTP allowed headers specified when accessing the resources. The default value
is X-Requested-With,Content-Type,Accept,Origin. If the value is a single *, it
accepts all headers. | `X-Requested-With,Content-Type,Accept,Origin` | No
| 0.4.0 |
+| `gravitino.iceberg-rest.preflightMaxAgeInSecs` | The number of seconds to
cache preflight requests by the client. The default value is 1800 seconds or 30
minutes.
| `1800` | No
| 0.4.0 |
+| `gravitino.iceberg-rest.allowCredentials` | A boolean indicating if the
resource allows requests with credentials. The default value is true.
| `true` | No |
0.4.0 |
+| `gravitino.iceberg-rest.exposedHeaders` | A comma separated list of
allowed HTTP headers exposed on the client. The default value is the empty
list.
| `` | No
| 0.4.0 |
+| `gravitino.iceberg-rest.chainPreflight` | If true chained preflight
requests for normal handling (as an OPTION request). Otherwise, the filter
responds to the preflight. The default is true.
| `true` | No
| 0.4.0 |
diff --git a/docs/security/how-to-use-https.md
b/docs/security/how-to-use-https.md
new file mode 100644
index 000000000..ddb7a5532
--- /dev/null
+++ b/docs/security/how-to-use-https.md
@@ -0,0 +1,127 @@
+---
+title: "How to use HTTPS"
+slug: /security/how-to-use-https
+keyword: security HTTPS protocol
+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.
+
+HTTPS protects the header of the request from smuggling, making it safer.
+
+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.
+
+### 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 |
+
+### 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 |
+
+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.
+
+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#ciphersuites)
for the list of protocols related to tlsProtocol. You can find the list of
`enableCipherAlgorithms` values for Java 8 in this document.
+
+### Example
+
+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.
+
+2. Generate the key store
+
+```shell
+cd $JAVA_HOME
+bin/keytool -genkeypair -alias localhost \
+-keyalg RSA -keysize 4096 -keypass localhost \
+-sigalg SHA256withRSA \
+-keystore localhost.jks -storetype JKS -storepass localhost \
+-dname "cn=localhost,ou=localhost,o=localhost,l=beijing,st=beijing,c=cn" \
+-validity 36500
+```
+
+3. Generate the certificate
+
+```shell
+bin/keytool -export -alias localhost -keystore localhost.jks -file
localhost.crt -storepass localhost
+```
+
+4. Import the certificate
+
+```shell
+bin/keytool -import -alias localhost -keystore jre/lib/security/cacerts -file
localhost.crt -storepass changeit -noprompt
+```
+
+5. You can refer to the [Configurations](gravitino-server-config.md) and
append the configuration to the conf/gravitino.conf.
+ Configuration doesn't support resolving environment variables, so you
should replace `${JAVA_HOME}` with the actual value.
+ Then, You can start the Gravitino server.
+
+```text
+gravitino.server.webserver.host = localhost
+gravitino.server.webserver.enableHttps = true
+gravitino.server.webserver.keyStorePath = ${JAVA_HOME}/localhost.jks
+gravitino.server.webserver.keyStorePassword = localhost
+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
+
+```java
+import org.apache.gravitino.client.GravitinoClient;
+import org.apache.gravitino.client.GravitinoVersion;
+
+public class Main {
+ public static void main(String[] args) {
+ String uri = "https://localhost:8433";;
+ GravitinoClient client =
GravitinoClient.builder(uri).withMetalake("metalake").build();
+ GravitinoVersion gravitinoVersion = client.getVersion();
+ System.out.println(gravitinoVersion);
+ }
+}
+```
+
+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
+curl -v -X GET --cacert ./certificate.pem -H "Accept:
application/vnd.gravitino.v1+json" -H "Content-Type: application/json"
https://localhost:8433/api/version
+```
diff --git a/docs/security/security.md b/docs/security/security.md
new file mode 100644
index 000000000..e09aab701
--- /dev/null
+++ b/docs/security/security.md
@@ -0,0 +1,20 @@
+---
+title: "Security"
+slug: /security/security
+keyword: security
+license: "This software is licensed under the Apache License version 2."
+---
+
+## Overview
+
+Gravitino provides features that ensure the highest levels of security for you.
+
+## Capabilities
+
+### Supports [Authentication](how-to-authenticate.md)
+
+### Supports [HTTPS](how-to-use-https.md)
+
+### Supports [Access Control](access-control.md)
+
+### Supports [CORS](how-to-use-cors.md)
\ No newline at end of file
diff --git a/docs/webui.md b/docs/webui.md
index 1fd7ef6b9..3a1742340 100644
--- a/docs/webui.md
+++ b/docs/webui.md
@@ -10,13 +10,13 @@ license: 'This software is licensed under the Apache
License version 2.'
This document primarily outlines how users can manage metadata within Apache
Gravitino using the web UI, the graphical interface is accessible through a web
browser as an alternative to writing code or using the REST interface.
-Currently, you can integrate [OAuth settings](./security.md) to view, add,
modify, and delete metalakes, create catalogs, and view catalogs, schemas, and
tables, among other functions.
+Currently, you can integrate [OAuth settings](security/security.md) to view,
add, modify, and delete metalakes, create catalogs, and view catalogs, schemas,
and tables, among other functions.
[Build](./how-to-build.md#quick-start) and
[deploy](./getting-started.md#getting-started-locally) the Gravitino Web UI and
open it in a browser at `http://<gravitino-host>:<gravitino-port>`, by default
is [http://localhost:8090](http://localhost:8090).
## Initial page
-The web UI homepage displayed in Gravitino depends on the configuration
parameter for OAuth mode, see the details in [Security](./security.md).
+The web UI homepage displayed in Gravitino depends on the configuration
parameter for OAuth mode, see the details in [Security](security/security.md).
Set parameter for `gravitino.authenticators`, [`simple`](#simple-mode) or
[`oauth`](#oauth-mode). Simple mode is the default authentication option. If
multiple authenticators are set, the first one is taken by default.
@@ -57,7 +57,7 @@ Such as Safari need to enable the developer menu, and select
`Disable Cross-Orig
-1. Enter the values corresponding to your specific configuration. For detailed
instructions, please refer to [Security](./security.md).
+1. Enter the values corresponding to your specific configuration. For detailed
instructions, please refer to [Security](security/security.md).
2. Clicking on the `LOGIN` button takes you to the homepage.
