Skip to content

Commit 13c6c68

Browse files
SylviaBABYSylviaBABY
authored
docs: add Forward Auth plugin blog (#860)
1 parent 9143d66 commit 13c6c68

File tree

2 files changed

+202
-0
lines changed

2 files changed

+202
-0
lines changed

‎website/blog/2022/01/26/apisix-integrate-forward-auth-plugin.md‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
---
2+
title: "Forward-auth, Another Choice for Authentication Function"
3+
authors:
4+
- name: "Zeping Bai"
5+
title: "Author"
6+
url: "https://github.com/bzp2010"
7+
image_url: "https://avatars.githubusercontent.com/u/8078418?v=4"
8+
- name: "Sylvia"
9+
title: "Technical Writer"
10+
url: "https://github.com/SylviaBABY"
11+
image_url: "https://avatars.githubusercontent.com/u/39793568?v=4"
12+
keywords:
13+
- Apache APISIX
14+
- Authentication
15+
- Plugin
16+
- Ecosystem
17+
description: This article describes the use of `forward-auth`, a new plugin in Apache APISIX, and provides detailed instructions on how to use this cleanly designed authentication model.
18+
tags: [Technology,Ecosystem,Authentication]
19+
---
20+
21+
> This article describes the use of `forward-auth`, a new plugin in Apache APISIX, and provides detailed instructions on how to use this cleanly designed authentication model.
22+
23+
<!--truncate-->
24+
25+
Forward Auth cleverly moves the authentication and authorization logic to a dedicated external service, where the gateway forwards the user's request to the authentication service and blocks the original request and replaces the result when the authentication service responds with a non-20x status. In this way, it is possible to return a custom error or redirect the user to the authentication page if the authentication fails.
26+
27+
## Principle
28+
29+
![Plugin priciple](https://static.apiseven.com/202108/1643096414141-ccbc33c0-7899-445a-a2f8-b6d5341c44df.jpg)
30+
31+
The principle and flow of the `forward-auth plugin` in Apache APISIX is shown in the figure above and is summarized in the following steps.
32+
33+
- Step 1: A request is made by the client to APISIX
34+
- Step 2: APISIX makes a request to the user-configured authentication service
35+
- Step 3: The authentication service responds (2xx or exception status)
36+
- Step 4: Based on the authentication service response, APISIX will decide to forward the request upstream or send a rejection response directly to the client
37+
38+
## How to use
39+
40+
### Step 1: Set up the authentication service
41+
42+
Suppose there is an authentication service to which the user sends a request with an Authorization request header. If this data passes authentication, a 200 status code and a response header named `X-User-ID` are returned; if it does not pass authentication, the authentication status is considered expired and a 302 status code and `Location` response header are returned to redirect the client to the login page.
43+
44+
### Step 2: Create a route and enable the `forward-auth` plugin
45+
46+
Next, we will configure a route and enable the `forward-auth` plugin to interface the above authentication service with the upstream application.
47+
48+
```shell
49+
curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
50+
{
51+
"plugins": {
52+
"forward-auth": {
53+
"address": "http://127.0.0.1:9080/auth",
54+
"request_headers": ["Authorization"],
55+
"upstream_headers": ["X-User-ID"],
56+
"client_headers": ["Location"]
57+
}
58+
},
59+
"uri": "/user"
60+
}'
61+
```
62+
63+
The above configuration details are explained.
64+
65+
- When a request matches the current route, a request is sent to the `address` in address with the request header Authorization defined in `request_headers` (i.e., the request header configured to be forwarded by the client to the authentication service, if not set, no request header is forwarded), whereby the authentication service can confirm the user's identity.
66+
- If the authentication passes, the status code is 200 and returns an `X-User-ID` as defined in `upstream_headers` (i.e. the request header to be forwarded upstream by the authentication service when the authentication passes, if not set, no request header is forwarded).
67+
- If authentication fails, the status code is 302 and returns a `Location` as defined in `client_headers` (i.e., the response header sent by the authentication service to the client if authentication fails, or no response header if it is not set).
68+
69+
### Step 3: Test Requests
70+
71+
```shell
72+
# Request and send data using POST
73+
curl http://127.0.0.1:9080/user \
74+
--header 'Authorization: true'
75+
76+
HTTP/1.1 200 OK
77+
Content-Type: application/json
78+
Content-Length: 28
79+
Server: APISIX/2.11.0
80+
81+
{"user_id":"i-am-real-user"}
82+
83+
# Request using GET
84+
curl -i http://127.0.0.1:9080/user \
85+
--header 'Authorization: false'
86+
87+
HTTP/1.1 302 FOUND
88+
Server: APISIX/2.11.0
89+
Location: https://example.com/auth
90+
```
91+
92+
### Addendum: Disable the plugin
93+
94+
If you have finished using the Forward Auth plugin, simply remove the `forward-auth` plugin configuration from the route configuration and save it to turn off the Forward Auth plugin on the route.
95+
96+
Thanks to the dynamic nature of Apache APISIX, there is no need to restart Apache APISIX to turn the plugin on and off.
97+
98+
## Summary
99+
100+
To get more information about the `forward-auth` plugin description and full configuration list, you can refer to the [official documentation](https://apisix.apache.org/docs/apisix/next/plugins/forward-auth). Also, if you have more complex authentication or authorization application scenarios, try using the `opa` plugin, which allows for more powerful functionality in a programmable way.
101+
102+
Apache APISIX is also currently working on additional plugins to support the integration of additional services, so if you are interested, feel free to start a discussion in [GitHub Discussion](https://github.com/apache/apisix/discussions), or via the [mailing list]( https://apisix.apache.org/zh/docs/general/subscribe-guide) to communicate.

‎website/i18n/zh/docusaurus-plugin-content-blog/2022/01/26/apisix-integrate-forward-auth-plugin.md‎

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
---
2+
title: "新插件 forward-auth 已上线，认证功能又多一项选择"
3+
authors:
4+
- name: "白泽平"
5+
title: "Author"
6+
url: "https://github.com/bzp2010"
7+
image_url: "https://avatars.githubusercontent.com/u/8078418?v=4"
8+
- name: "苏钰"
9+
title: "Technical Writer"
10+
url: "https://github.com/SylviaBABY"
11+
image_url: "https://avatars.githubusercontent.com/u/39793568?v=4"
12+
keywords:
13+
- Apache APISIX
14+
- 认证
15+
- 插件
16+
- 生态
17+
description: 本文将介绍 Apache APISIX 中新增插件 `forward-auth` 的使用方法，为大家详细说明如何使用这款设计简洁的认证模型。
18+
tags: [Technology,Ecosystem,Authentication]
19+
---
20+
21+
> 本文将介绍 Apache APISIX 中新增插件 `forward-auth` 的使用方法，为大家详细说明如何使用这款设计简洁的认证模型。
22+
23+
<!--truncate-->
24+
25+
Forward Auth 能巧妙地将认证与授权逻辑转移至专门的外部服务中，网关会将用户的请求转发至认证服务中，并在认证服务响应非 20x 状态时，阻止原有请求并替换结果。通过这样的方式，就可以实现认证未通过时，返回自定义报错或用户重定向至认证页面。接下来将为大家介绍 Apache APISIX 中新增插件 `forward-auth` 的使用方法。
26+
27+
## 原理
28+
29+
![插件原理图](https://static.apiseven.com/202108/1643096414141-ccbc33c0-7899-445a-a2f8-b6d5341c44df.jpg)
30+
31+
关于 `forward-auth` 插件在 Apache APISIX 中的运行原理与流程如上图所示，具体总结为以下几步：
32+
33+
- 第一步：由客户端向 APISIX 发起请求
34+
- 第二步：由 APISIX 向用户配置的认证服务发起请求
35+
- 第三步：认证服务响应（2xx 或异常状态）
36+
- 第四步：APISIX 会根据认证服务响应，决定向上游转发请求或直接向客户端发送拒绝响应
37+
38+
## 如何使用
39+
40+
### 步骤一：设置认证服务
41+
42+
假设有这样一项认证服务，用户向其发送带有 Authorization 请求头的请求。如果这个数据通过验证则返回 200 状态码和一个名为 `X-User-ID` 的响应头；如果没有通过验证则认为认证状态过期，返回 302 状态码和 `Location` 响应头将客户端重定向至登录页面。
43+
44+
### 步骤二：创建路由并开启 `forward-auth` 插件
45+
46+
接下来，我们将配置一个路由并开启 `forward-auth` 插件，将上述的认证服务和上游应用对接起来。
47+
48+
```shell
49+
curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
50+
{
51+
"plugins": {
52+
"forward-auth": {
53+
"address": "http://127.0.0.1:9080/auth",
54+
"request_headers": ["Authorization"],
55+
"upstream_headers": ["X-User-ID"],
56+
"client_headers": ["Location"]
57+
}
58+
},
59+
"uri": "/user"
60+
}'
61+
```
62+
63+
上述配置细节释义：
64+
65+
- 当有请求匹配到当前路由时，发送一个请求至 `address` 中的地址，其中将附带`request_headers` 中定义的请求头 `Authorization`（即配置需要由客户端转发至认证服务的请求头，如果不设置则不转发任何请求头），认证服务可以据此进行用户身份确认。
66+
- 如果认证通过，状态码为 200 并返回一个 `upstream_headers` 中定义的 `X-User-ID`（即认证通过时由认证服务转发至上游的请求头，如果不设置则不转发任何请求头）。
67+
- 如果认证失败，状态码为 302 并返回一个在 `client_headers` 中定义的 `Location`（即认证失败时由认证服务向客户端发送的响应头，如果不设置则不转发任何响应头）。
68+
69+
### 步骤三：测试请求
70+
71+
```shell
72+
# 使用 POST 请求并发送数据
73+
curl http://127.0.0.1:9080/user \
74+
--header 'Authorization: true'
75+
76+
HTTP/1.1 200 OK
77+
Content-Type: application/json
78+
Content-Length: 28
79+
Server: APISIX/2.11.0
80+
81+
{"user_id":"i-am-real-user"}
82+
83+
# 使用 GET 请求
84+
curl -i http://127.0.0.1:9080/user \
85+
--header 'Authorization: false'
86+
87+
HTTP/1.1 302 FOUND
88+
Server: APISIX/2.11.0
89+
Location: https://example.com/auth
90+
```
91+
92+
### 补充：关闭插件
93+
94+
如已使用完毕，只需移除路由配置中 `forward-auth` 插件相关配置并保存，即可关闭路由上的 Forward Auth 插件。得益于 Apache APISIX 的动态化特性，开启关闭插件的过程都不需要重启 Apache APISIX。
95+
96+
## 总结
97+
98+
想要获取更多关于 `forward-auth` 插件说明和完整配置列表，可参考[官方文档](https://apisix.apache.org/docs/apisix/next/plugins/forward-auth)。同时，如果您有更加复杂的认证或授权应用场景，也可以尝试使用 `opa` 插件，该插件允许以可编程的方式提供更强大的功能。
99+
100+
目前，Apache APISIX 也在开发其他插件以支持集成更多服务，如果您对此感兴趣，欢迎随时在 [GitHub Discussion](https://github.com/apache/apisix/discussions) 中发起讨论，也可通过[邮件列表](https://apisix.apache.org/zh/docs/general/subscribe-guide)进行交流。

0 commit comments

Comments
 (0)
⚡