yuqi1129 commented on code in PR #4496:
URL: https://github.com/apache/gravitino/pull/4496#discussion_r1718014114
##########
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
Review Comment:
ditto
##########
docs/security/access-control.md:
##########
@@ -0,0 +1,646 @@
+---
+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 secureable objects, when it comes to
authentication.
+Gravitino doesn't support metadata authentication.
+
+:::
+
+
+## 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". `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. You can understand that metalake a customer
organization.
Review Comment:
You can view metalake as a xxxxx.
The word `understand` is not elegant.
##########
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:
I remember this key has been replaced with `gravitino.authenticators`, Am I
correct?
##########
docs/security/access-control.md:
##########
@@ -0,0 +1,646 @@
+---
+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 secureable objects, when it comes to
authentication.
+Gravitino doesn't support metadata authentication.
+
+:::
+
+
+## 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". `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. You can understand that metalake a customer
organization.
+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.
+The owner have all the privileges of the metadata object.
+The owner could be transferred 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.
Review Comment:
catalog, too -> catalog too.
##########
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
Review Comment:
ditto
##########
docs/security/how-to-authenticate.md:
##########
@@ -0,0 +1,176 @@
+---
+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.
+
+### 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.
Review Comment:
Should we support setting a custom user name?
--
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]
