jerqi commented on code in PR #4496:
URL: https://github.com/apache/gravitino/pull/4496#discussion_r1718023688
##########
docs/security/how-to-authenticate.md:
##########
@@ -0,0 +1,173 @@
+---
+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.authenticator` 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.authenticator` 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` | The authenticator which
Gravitino uses, setting as `simple`,`oauth` or `kerberos`. |
`simple` | No | 0.3.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.authenticator = oauth
Review Comment:
We don't merge this document.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
