Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

chore(website): remove config auth mode doc #300

Merged
merged 9 commits into from
Nov 30, 2023
40 changes: 5 additions & 35 deletions content/cn/docs/config/config-authentication.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,11 +5,9 @@ weight: 3
---

### 概述
HugeGraph 为了方便不同用户场景下的鉴权使用,目前内置了两套权限模式:
1. 简单的`ConfigAuthenticator`模式,通过本地配置文件存储用户名和密码 (仅支持单 GraphServer)
2. 完备的`StandardAuthenticator`模式,支持多用户认证、以及细粒度的权限访问控制,采用基于“用户 - 用户组 - 操作 - 资源”的 4 层设计,灵活控制用户角色与权限 (支持多 GraphServer)
HugeGraph 为了方便不同用户场景下的鉴权使用,目前内置了完备的`StandardAuthenticator`权限模式,支持多用户认证、以及细粒度的权限访问控制,采用基于“用户 - 用户组 - 操作 - 资源”的 4 层设计,灵活控制用户角色与权限 (支持多 GraphServer)

其中 `StandardAuthenticator` 模式的几个核心设计:
`StandardAuthenticator` 模式的几个核心设计:
- 初始化时创建超级管理员 (`admin`) 用户,后续通过超级管理员创建其它用户,新创建的用户被分配足够权限后,可以创建或管理更多的用户
- 支持动态创建用户、用户组、资源,支持动态分配或取消权限
- 用户可以属于一个或多个用户组,每个用户组可以拥有对任意个资源的操作权限,操作类型包括:读、写、删除、执行等种类
Expand All @@ -24,7 +22,7 @@ user(name=xx) -belong-> group(name=xx) -access(read)-> target(graph=graph1, reso

### 配置用户认证

HugeGraph 默认**不启用**用户认证功能,需通过修改配置文件来启用该功能。内置实现了`StandardAuthenticator`和`ConfigAuthenticator`两种模式,`StandardAuthenticator`模式支持多用户认证与细粒度权限控制,`ConfigAuthenticator`模式支持简单的用户权限认证。此外,开发者可以自定义实现`HugeAuthenticator`接口来对接自身的权限系统。
HugeGraph 默认**不启用**用户认证功能,需通过修改配置文件来启用该功能。内置实现了`StandardAuthenticator`模式,该模式支持多用户认证与细粒度权限控制。此外,开发者可以自定义实现`HugeAuthenticator`接口来对接自身的权限系统。

用户认证方式均采用 [HTTP Basic Authentication](https://zh.wikipedia.org/wiki/HTTP%E5%9F%BA%E6%9C%AC%E8%AE%A4%E8%AF%81) ,简单说就是在发送 HTTP 请求时在 `Authentication` 设置选择 `Basic` 然后输入对应的用户名和密码,对应 HTTP 明文如下所示 :

Expand Down Expand Up @@ -53,7 +51,7 @@ auth.authenticator=org.apache.hugegraph.auth.StandardAuthenticator
auth.graph_store=hugegraph

# auth client config
# 如果是分开部署 GraphServer 和 AuthServer, 还需要指定下面的配置,地址填写 AuthServer 的 IP:RPC 端口
# 如果是分开部署 GraphServer 和 AuthServer还需要指定下面的配置,地址填写 AuthServer 的 IP:RPC 端口
#auth.remote_url=127.0.0.1:8899,127.0.0.1:8898,127.0.0.1:8897
```
其中,`graph_store`配置项是指使用哪一个图来存储用户信息,如果存在多个图的话,选取任意一个均可。
Expand All @@ -64,35 +62,7 @@ auth.graph_store=hugegraph
gremlin.graph=org.apache.hugegraph.auth.HugeFactoryAuthProxy
```

然后详细的权限 API 调用和说明请参考 [Authentication-API](/docs/clients/restful-api/auth) 文档

#### ConfigAuthenticator 模式

`ConfigAuthenticator`模式是通过预先在配置文件中设置用户信息来支持用户认证,该实现是基于配置好的静态`tokens`来验证用户是否合法。下面是具体的配置流程(重启服务生效):

在配置文件`gremlin-server.yaml`中配置`authenticator`及其`rest-server`文件路径:

```yaml
authentication: {
authenticator: org.apache.hugegraph.auth.ConfigAuthenticator,
authenticationHandler: org.apache.hugegraph.auth.WsAndHttpBasicAuthHandler,
config: {tokens: conf/rest-server.properties}
}
```

在配置文件`rest-server.properties`中配置`authenticator`及其`tokens`信息:

```properties
auth.authenticator=org.apache.hugegraph.auth.ConfigAuthenticator
auth.admin_token=token-value-a
auth.user_tokens=[hugegraph1:token-value-1, hugegraph2:token-value-2]
```

在配置文件`hugegraph{n}.properties`中配置`gremlin.graph`信息:

```properties
gremlin.graph=org.apache.hugegraph.auth.HugeFactoryAuthProxy
```
Comment on lines -67 to -95
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

shall we mark them as outdated & put them in a single space? (or just delete them? @javeme )

Copy link
Contributor Author

@SunnyBoy-WYH SunnyBoy-WYH Nov 25, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

shall we mark them as outdated & put them in a single space? (or just delete them? @javeme )

i think we just delete it; In the future the best method is do whole doc's version control overall,not mark the specific change;

and another way , we can record doc change log, like current Hugegraph Release change log

cc @javeme

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is the ConfigAuthenticator still available? I think we can delete this doc if NO or mark outdated if YES.
The version control of documents is the direction we need to move towards.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

shall we mark them as outdated & put them in a single space? (or just delete them? @javeme )

i think we just delete it; In the future the best method is do whole doc's version control overall,not mark the specific change;

and another way , we can record doc change log, like current Hugegraph Release change log

cc @javeme

OK,just delete it for now

outdated doc should be visited by website tag/version function,record this as a important need(issue)

然后详细的权限 API 调用和说明请参考 [Authentication-API](/docs/clients/restful-api/auth) 文档。

### 自定义用户认证系统

Expand Down
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
12 changes: 12 additions & 0 deletions content/cn/docs/quickstart/hugegraph-server.md
Original file line number Diff line number Diff line change
Expand Up @@ -646,6 +646,18 @@ _说明_
<img src="/docs/images/images-server/621swaggerui示例.png" alt="image">
</div>

在使用 Swagger UI 调试 HugeGraph 提供的 API 时,如果 HugeGraph Server 开启了鉴权模式,可以在 Swagger 页面输入鉴权信息。

<div style="text-align: center;">
<img src="/docs/images/images-server/621swaggerui设置鉴权位置示例.png" alt="image">
</div>

当前 HugeGraph 支持基于 Basic 和 Bearer 两种形式设置鉴权信息。

<div style="text-align: center;">
<img src="/docs/images/images-server/621swaggerui设置鉴权示例.png" alt="image">
</div>

### 7 停止 Server

```bash
Expand Down
42 changes: 8 additions & 34 deletions content/en/docs/config/config-authentication.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,9 +5,9 @@ weight: 3
---

### Overview
To facilitate authentication usage in different user scenarios, HugeGraph currently provides two built-in authorization modes:
1. Simple `ConfigAuthenticator` mode, which stores usernames and passwords in a local configuration file (supports only a single GraphServer).
2. Comprehensive `StandardAuthenticator` mode, which supports multi-user authentication and fine-grained access control. It adopts a 4-layer design based on "User-UserGroup-Operation-Resource" to flexibly control user roles and permissions (supports multiple GraphServers).
To facilitate authentication usage in different user scenarios, HugeGraph currently provides built-in authorization `StandardAuthenticator` mode,
which supports multi-user authentication and fine-grained access control. It adopts a 4-layer design based on "User-UserGroup-Operation-Resource" to
flexibly control user roles and permissions (supports multiple GraphServers).

Some key designs of the `StandardAuthenticator` mode include:
- During initialization, a super administrator (`admin`) user is created. Subsequently, other users can be created by the super administrator. Once newly created users are assigned sufficient permissions, they can create or manage more users.
Expand All @@ -24,17 +24,19 @@ user(name=xx) -belong-> group(name=xx) -access(read)-> target(graph=graph1, reso

### Configure User Authentication

By default, HugeGraph does **not enable** user authentication. You need to modify the configuration file to enable this feature. HugeGraph provides two built-in authentication modes: `StandardAuthenticator` and `ConfigAuthenticator`. The `StandardAuthenticator` mode supports multi-user authentication and fine-grained permission control, while the `ConfigAuthenticator` mode supports simple user permission authentication. Additionally, developers can implement their own `HugeAuthenticator` interface to integrate with their existing authentication systems.
By default, HugeGraph does **not enable** user authentication. You need to modify the configuration file to enable this feature. HugeGraph provides built-in authentication mode: `StandardAuthenticator`. This mode supports multi-user authentication and fine-grained permission control. Additionally, developers can implement their own `HugeAuthenticator` interface to integrate with their existing authentication systems.

Both authentication modes adopt [HTTP Basic Authentication](https://en.wikipedia.org/wiki/Basic_access_authentication). In simple terms, when sending an HTTP request, you need to set the `Authentication` header to `Basic` and provide the corresponding username and password. The corresponding HTTP plaintext format is as follows:
HugeGraph authentication modes adopt [HTTP Basic Authentication](https://en.wikipedia.org/wiki/Basic_access_authentication). In simple terms, when sending an HTTP request, you need to set the `Authentication` header to `Basic` and provide the corresponding username and password. The corresponding HTTP plaintext format is as follows:

```http
GET http://localhost:8080/graphs/hugegraph/schema/vertexlabels
Authorization: Basic admin xxxx
```

#### StandardAuthenticator Mode
The `StandardAuthenticator` mode supports user authentication and permission control by storing user information in the database backend. This implementation authenticates users based on their names and passwords (encrypted) stored in the database and controls user permissions based on their roles. Below is the specific configuration process (requires service restart):
The `StandardAuthenticator` mode supports user authentication and permission control by storing user information in the database backend. This
implementation authenticates users based on their names and passwords (encrypted) stored in the database and controls user permissions based on their
roles. Below is the specific configuration process (requires service restart):

Configure the `authenticator` and its `rest-server` file path in the `gremlin-server.yaml` configuration file:

Expand Down Expand Up @@ -67,34 +69,6 @@ gremlin.graph=org.apache.hugegraph.auth.HugeFactoryAuthProxy

For detailed API calls and explanations regarding permissions, please refer to the [Authentication-API](/docs/clients/restful-api/auth) documentation.

#### ConfigAuthenticator Mode

The `ConfigAuthenticator` mode supports user authentication by predefining user information in the configuration file. This implementation verifies the legitimacy of users based on preconfigured static `tokens`. Below is the specific configuration process (requires service restart):

Configure the `authenticator` and its `rest-server` file path in the `gremlin-server.yaml` configuration file:

```yaml
authentication: {
authenticator: org.apache.hugegraph.auth.ConfigAuthenticator,
authenticationHandler: org.apache.hugegraph.auth.WsAndHttpBasicAuthHandler,
config: {tokens: conf/rest-server.properties}
}
```

Configure the `authenticator` and its `tokens` information in the `rest-server.properties` configuration file:

```properties
auth.authenticator=org.apache.hugegraph.auth.ConfigAuthenticator
auth.admin_token=token-value-a
auth.user_tokens=[hugegraph1:token-value-1, hugegraph2:token-value-2]
```

In the `hugegraph{n}.properties` configuration file, configure the `gremlin.graph` information:

```properties
gremlin.graph=org.apache.hugegraph.auth.HugeFactoryAuthProxy
```

### Custom User Authentication System

If you need to support a more flexible user system, you can customize the authenticator for extension.
Expand Down
12 changes: 12 additions & 0 deletions content/en/docs/quickstart/hugegraph-server.md
Original file line number Diff line number Diff line change
Expand Up @@ -653,6 +653,18 @@ You can also visit `localhost:8080/swagger-ui/index.html` to check the API.
<img src="/docs/images/images-server/621swaggerui示例.png" alt="image">
</div>

When using Swagger UI to debug the API provided by HugeGraph, if HugeGraph Server turns on authentication mode, you can enter authentication information on the Swagger page.

<div style="text-align: center;">
<img src="/docs/images/images-server/621swaggerui设置鉴权位置示例.png" alt="image">
</div>

Currently HugeGraph supports setting authentication information in two forms: Basic and Bearer.

<div style="text-align: center;">
<img src="/docs/images/images-server/621swaggerui设置鉴权示例.png" alt="image">
</div>

### 7 Stop Server

```bash
Expand Down