From 08ebdfc95fe0b4c687c73ddd89d4be14bc74e3c2 Mon Sep 17 00:00:00 2001
From: John Niang <johnniang@fastmail.com>
Date: Fri, 1 Mar 2024 11:11:18 +0800
Subject: [PATCH] Add documentation for authentication webfilter extension
 points (#320)

* Add documentation for authentication webfilter extension points

* Refine requirements of extension point definition
---
 .../authentication-webfilter.md               | 81 +++++++++++++++++++
 .../server/extension-points/index.md          |  4 +-
 sidebars.js                                   |  1 +
 3 files changed, 84 insertions(+), 2 deletions(-)
 create mode 100644 docs/developer-guide/plugin/api-reference/server/extension-points/authentication-webfilter.md

diff --git a/docs/developer-guide/plugin/api-reference/server/extension-points/authentication-webfilter.md b/docs/developer-guide/plugin/api-reference/server/extension-points/authentication-webfilter.md
new file mode 100644
index 00000000..f54e8057
--- /dev/null
+++ b/docs/developer-guide/plugin/api-reference/server/extension-points/authentication-webfilter.md
@@ -0,0 +1,81 @@
+---
+title: 认证安全过滤器
+description: 提供 Security WebFilter 扩展点，插件可实现自定义认证逻辑，例如：用户名密码认证，JWT 认证，匿名认证。
+---
+
+此前，Halo 提供了 AdditionalWebFilter 作为扩展点供插件扩展认证相关的功能。但是近期我们明确了 AdditionalWebFilter
+的使用用途，故不再作为认证的扩展点。
+
+目前，Halo 提供了三种认证扩展点：表单登录认证、普通认证和匿名认证。
+
+## 表单登录（FormLogin）
+
+示例如下：
+
+```java
+import org.springframework.stereotype.Component;
+import org.springframework.web.server.ServerWebExchange;
+import org.springframework.web.server.WebFilterChain;
+import reactor.core.publisher.Mono;
+import run.halo.app.security.FormLoginSecurityWebFilter;
+
+@Component
+public class MyFormLoginSecurityWebFilter implements FormLoginSecurityWebFilter {
+
+  @Override
+  public Mono<Void> filter(ServerWebExchange exchange, WebFilterChain chain) {
+    // Do your logic here
+    return chain.filter(exchange);
+  }
+}
+
+```
+
+## 普通认证（Authentication）
+
+示例如下：
+
+```java
+import org.springframework.stereotype.Component;
+import org.springframework.web.server.ServerWebExchange;
+import org.springframework.web.server.WebFilterChain;
+import reactor.core.publisher.Mono;
+import run.halo.app.security.AuthenticationSecurityWebFilter;
+
+@Component
+public class MyAuthenticationSecurityWebFilter implements AuthenticationSecurityWebFilter {
+
+    @Override
+    public Mono<Void> filter(ServerWebExchange exchange, WebFilterChain chain) {
+        // Do your logic here
+        return chain.filter(exchange);
+    }
+}
+```
+
+## 匿名认证（Anonymous Authentication）
+
+示例如下：
+
+```java
+import org.springframework.stereotype.Component;
+import org.springframework.web.server.ServerWebExchange;
+import org.springframework.web.server.WebFilterChain;
+import reactor.core.publisher.Mono;
+import run.halo.app.security.AnonymousAuthenticationSecurityWebFilter;
+
+@Component
+public class MyAnonymousAuthenticationSecurityWebFilter
+    implements AnonymousAuthenticationSecurityWebFilter {
+
+    @Override
+    public Mono<Void> filter(ServerWebExchange exchange, WebFilterChain chain) {
+        // Do your logic here
+        return chain.filter(exchange);
+    }
+}
+```
+
+我们在实现扩展点的时候需要注意：如果当前请求不满足认证条件，请一定要调用 `chain.filter(exchange)`，给其他 filter 留下机会。
+
+后续会根据需求实现其他认证相关的扩展点。
diff --git a/docs/developer-guide/plugin/api-reference/server/extension-points/index.md b/docs/developer-guide/plugin/api-reference/server/extension-points/index.md
index 37a01782..2cb89985 100644
--- a/docs/developer-guide/plugin/api-reference/server/extension-points/index.md
+++ b/docs/developer-guide/plugin/api-reference/server/extension-points/index.md
@@ -49,9 +49,9 @@ spec:
 ```
 
 :::tip Note
-每一个扩展点都会声明一个对应的 `ExtensionPointDefinition` 自定义模型对象被称之为扩展点定义，用于描述该扩展点的信息，例如：扩展点的名称、描述、扩展点的类型等。
+单实例或多实例的扩展点需要声明对应的 `ExtensionPointDefinition` 自定义模型对象被称之为扩展点定义，用于描述该扩展点的信息，例如：扩展点的名称、描述、扩展点的类型等。
 
-而每一个扩展也必须声明一个对应的 `ExtensionDefinition` 自定义模型对象被称之为扩展定义，用于描述该扩展的信息，例如：扩展的名称、描述、对应扩展点的对象名称等。
+单实例或多实例扩展点的实现也必须声明一个对应的 `ExtensionDefinition` 自定义模型对象被称之为扩展定义，用于描述该扩展的信息，例如：扩展的名称、描述、对应扩展点的对象名称等。
 :::
 
 关于如何在插件中声明自定义模型对象请参考：[自定义模型](../../server/extension.md#declare-extension-object)
diff --git a/sidebars.js b/sidebars.js
index 9819da8d..1be18fb9 100644
--- a/sidebars.js
+++ b/sidebars.js
@@ -181,6 +181,7 @@ module.exports = {
                   },
                   items: [
                     "developer-guide/plugin/api-reference/server/extension-points/additional-webfilter",
+                    "developer-guide/plugin/api-reference/server/extension-points/authentication-webfilter",
                     "developer-guide/plugin/api-reference/server/extension-points/attachment",
                     "developer-guide/plugin/api-reference/server/extension-points/comment-subject",
                     "developer-guide/plugin/api-reference/server/extension-points/comment-widget",