配置 API 身份认证
为保障安全,应只允许通过身份认证并获得授权的消费者访问 API。API7 网关提供多种插件,实现身份认证和授权。
在服务上启用的身份认证插件相当于 API 的锁,消费者凭据则是开锁的钥匙。在 API7 网关中,创建消费者需要唯一的用户名和至少一个凭据。
消费者可以使用多个不同类型的凭据,在身份认证时这些凭据具有同等作用。
前提条件
避免在同一服务或路由上配置多个身份认证插件,以防止冲突。
为 API 启用 Key Authentication
针对服务
如需对服务中的所有路由使用 Key 身份认证,请在服务上启用 Key Auth 插件。
- 控制台
- ADC
- Ingress Controller
- 在侧边导航栏选择网关组的已发布服务,然后选择要修改的服务,例如版本为
1.0.0的httpbin。 - 在侧边导航栏选择插件,然后点击新增插件。
- 搜索
key-auth插件,然后点击新增。 - 在对话框中完成以下操作。
-
在 JSON 编辑器中添加以下配置。
{} -
点击新增。
更新服务配置,使用 Key 身份认证。
services:
- name: httpbin
upstream:
name: default
scheme: http
nodes:
- host: httpbin.org
port: 80
weight: 100
plugins:
key-auth:
_meta:
disable: false
routes:
- uris:
- /ip
name: get-ip
methods:
- GET
将配置同步到 API7 企业版。
adc sync -f adc-consumer.yaml -f adc-service.yaml
ADC 将配置文件作为唯一的配置依据。因此,请确保将消费者和服务的配置文件一起传递给 adc sync 命令,使两项配置都生效。
- Gateway API
- APISIX CRD
创建路由的 Kubernetes 清单文件,同时创建服务,并启用 Key 身份认证。
apiVersion: apisix.apache.org/v1alpha1
kind: PluginConfig
metadata:
namespace: api7
name: auth-plugin-config
spec:
plugins:
- name: key-auth
config:
_meta:
disable: false
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
namespace: api7
name: httpbin
spec:
parentRefs:
- name: apisix
rules:
- matches:
- path:
type: Exact
value: /ip
filters:
- type: ExtensionRef
extensionRef:
group: apisix.apache.org
kind: PluginConfig
name: auth-plugin-config
backendRefs:
- name: httpbin
port: 80
将配置应用到集群。
kubectl apply -f httpbin-key-auth.yaml
APISIX CRD 目前不支持在服务级别启用插件。
针对单个路由
- 控制台
- ADC
- Ingress Controller
如需对特定路由使用 Key 身份认证,请在该路由上启用 Key Auth 插件,而不是在服务上启用。
- 在侧边导航栏选择网关组的已发布服务,然后选择要修改的服务,例如版本为
1.0.0的httpbin。 - 在已发布服务中,从侧边导航栏选择路由。
- 选择目标路由,例如
get-ip。 - 在插件字段中,点击新增插件。
- 搜索
key-auth插件,然后点击新增。 - 在对话框中完成以下操作。
-
在 JSON 编辑器中添加以下配置。
{} -
点击新增。
更新路由配置,使用 Key 身份认证。
services:
- name: httpbin
upstream:
name: default
scheme: http
nodes:
- host: httpbin.org
port: 80
weight: 100
routes:
- uris:
- /ip
name: get-ip
methods:
- GET
plugins:
key-auth:
_meta:
disable: false
将配置同步到 API7 网关。
adc sync -f adc-consumer.yaml -f adc-route.yaml
ADC 将配置文件作为唯一的配置依据。因此,请确保将消费者和服务的配置文件一起传递给 adc sync 命令,使两项配置都生效。
- Gateway API
- APISIX CRD
Gateway API 目前不支持在路由级别启用插件。
创建路由的 Kubernetes 清单文件,同时创建服务,并启用 Key 身份认证。
apiVersion: apisix.apache.org/v2
kind: ApisixRoute
metadata:
namespace: api7
name: httpbin
spec:
ingressClassName: apisix
http:
- name: get-ip
match:
paths:
- /ip
backends:
- serviceName: httpbin
servicePort: 80
plugins:
- name: key-auth
enable: true
将配置应用到集群。
kubectl apply -f httpbin-key-auth.yaml
验证 Key Authentication
按照配置 Key Authentication 凭据创建具有 Key 身份认证凭据的消费者。
然后按照以下步骤验证 Key 身份认证。
- 发送不包含
apikey请求头的请求。
curl -i "http://127.0.0.1:9080/ip"
由于未提供 Key,你会收到 HTTP/1.1 401 Unauthorized 响应,响应体如下。
{"message":"Missing API key found in request"}
- 发送在
apikey请求头中包含错误 Key 的请求。
curl -i "http://127.0.0.1:9080/ip" -H "apikey: wrongkey"
由于 Key 错误,你会收到 HTTP/1.1 401 Unauthorized 响应,响应体如下。
{"message":"Invalid API key in request"}
- 发送在
apikey请求头中包含正确 Key 的请求。
curl -i "http://127.0.0.1:9080/ip" -H "apikey: alice-primary-key"
请求包含正确 Key 时,你会收到 HTTP/1.1 200 OK 响应。
为 API 启用 Basic Authentication
针对服务
如需对服务中的所有路由使用 Basic 身份认证,请在服务上启用 Basic Auth 插件。
- 控制台
- ADC
- Ingress Controller
- 在侧边导航栏选择网关组的已发布服务,然后选择要修改的服务,例如版本为
1.0.0的httpbin。 - 在侧边导航栏选择插件,然后点击新增插件。
- 搜索
basic-auth插件,然后点击新增。 - 在对话框中完成以下操作。
-
在 JSON 编辑器中添加以下配置。
{} -
点击新增。
更新服务配置,使用 Basic 身份认证。
services:
- name: httpbin
upstream:
name: default
scheme: http
nodes:
- host: httpbin.org
port: 80
weight: 100
plugins:
basic-auth:
_meta:
disable: false
routes:
- uris:
- /ip
name: get-ip
methods:
- GET
将配置同步到 API7 企业版。
adc sync -f adc-consumer.yaml -f adc-service.yaml
ADC 将配置文件作为唯一的配置依据。因此,请确保将消费者和服务的配置文件一起传递给 adc sync 命令,使两项配置都生效。
- Gateway API
- APISIX CRD
创建路由的 Kubernetes 清单文件,同时创建服务,并在服务上启用 Basic 身份认证。
apiVersion: apisix.apache.org/v1alpha1
kind: PluginConfig
metadata:
namespace: api7
name: auth-plugin-config
spec:
plugins:
- name: basic-auth
config:
_meta:
disable: false
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
namespace: api7
name: httpbin
spec:
parentRefs:
- name: apisix
rules:
- matches:
- path:
type: Exact
value: /ip
filters:
- type: ExtensionRef
extensionRef:
group: apisix.apache.org
kind: PluginConfig
name: auth-plugin-config
backendRefs:
- name: httpbin
port: 80
将配置应用到集群。
kubectl apply -f httpbin-basic-auth.yaml
APISIX CRD 目前不支持在服务级别启用插件。
针对单个路由
- 控制台
- ADC
- Ingress Controller
如需对特定路由使用 Basic 身份认证,请在该路由上启用 Basic Auth 插件,而不是在服务上启用。
- 在侧边导航栏选择网关组的已发布服务,然后选择要修改的服务,例如版本为
1.0.0的httpbin。 - 在已发布服务中,从侧边导航栏选择路由。
- 选择目标路由,例如
get-ip。 - 在插件字段中,点击新增插件。
- 搜索
basic-auth插件,然后点击新增。 - 在对话框中完成以下操作。
-
在 JSON 编辑器中添加以下配置。
{} -
点击新增。
更新路由配置,使用 Basic 身份认证。
services:
- name: httpbin
upstream:
name: default
scheme: http
nodes:
- host: httpbin.org
port: 80
weight: 100
routes:
- uris:
- /ip
name: get-ip
methods:
- GET
plugins:
basic-auth:
_meta:
disable: false
将配置同步到 API7 网关。
adc sync -f adc-consumer.yaml -f adc-route.yaml
ADC 将配置文件作为唯一的配置依据。因此,请确保将消费者和服务的配置文件一起传递给 adc sync 命令,使两项配置都生效。
- Gateway API
- APISIX CRD
Gateway API 目前不支持在路由级别启用插件。
创建路由的 Kubernetes 清单文件,同时创建服务,并在服务上启用 Basic 身份认证。
apiVersion: apisix.apache.org/v2
kind: ApisixRoute
metadata:
namespace: api7
name: httpbin
spec:
ingressClassName: apisix
http:
- name: get-ip
match:
paths:
- /ip
backends:
- serviceName: httpbin
servicePort: 80
plugins:
- name: basic-auth
enable: true
将配置应用到集群。
kubectl apply -f httpbin-basic-auth.yaml
验证 Basic Authentication
按照配置 Basic Authentication 凭据创建具有 Basic 身份认证凭据的消费者。
按照以下步骤验证 Basic 身份认证。
- 发送请求,请求头中不包含 Basic 身份认证凭据。
curl -i "http://127.0.0.1:9080/ip"
由于未提供凭据,你会收到 HTTP/1.1 401 Unauthorized 响应,响应体如下。
{"message":"Missing authorization in request"}
- 发送请求,请求头中包含无效的 Basic 身份认证凭据,即用户名与密码不匹配,或用户名不存在。
curl -i "http://127.0.0.1:9080/ip" -u alice:wrong-password
由于密码与任何消费者凭据都不匹配,你会收到 HTTP/1.1 401 Unauthorized 响应,响应体如下。
{"message":"Invalid user authorization"}
- 发送包含正确 Basic 身份认证凭据的请求。
curl -i "http://127.0.0.1:9080/ip" -u alice:alice-password
请求包含正确凭据时,你会收到 HTTP/1.1 200 OK 响应。
为 API 启用 JWT 认证
针对服务
如需对服务中的所有路由使用 JWT 身份认证,请在服务上启用 JWT Auth 插件。
- 控制台
- ADC
- Ingress Controller
- 在侧边导航栏选择网关组的已发布服务,然后选择要修改的服务,例如版本为
1.0.0的httpbin。 - 在侧边导航栏选择插件,然后点击新增插件。
- 搜索
jwt-auth插件,然后点击新增。 - 在对话框中完成以下操作。
-
在 JSON 编辑器中添加以下配置。
{} -
点击新增。
更新服务配置,使用 JWT 身份认证。
services:
- name: httpbin
upstream:
name: default
scheme: http
nodes:
- host: httpbin.org
port: 80
weight: 100
plugins:
jwt-auth:
_meta:
disable: false
routes:
- uris:
- /ip
name: get-ip
methods:
- GET
将配置同步到 API7 企业版。
adc sync -f adc-consumer.yaml -f adc-service.yaml
ADC 将配置文件作为唯一的配置依据。因此,请确保将消费者和服务的配置文件一起传递给 adc sync 命令,使两项配置都生效。
- Gateway API
- APISIX CRD
创建路由的 Kubernetes 清单文件,同时创建服务,并在服务上启用 JWT 身份认证。
apiVersion: apisix.apache.org/v1alpha1
kind: PluginConfig
metadata:
namespace: api7
name: auth-plugin-config
spec:
plugins:
- name: jwt-auth
config:
_meta:
disable: false
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
namespace: api7
name: httpbin
spec:
parentRefs:
- name: apisix
rules:
- matches:
- path:
type: Exact
value: /ip
filters:
- type: ExtensionRef
extensionRef:
group: apisix.apache.org
kind: PluginConfig
name: auth-plugin-config
backendRefs:
- name: httpbin
port: 80
将配置应用到集群。
kubectl apply -f httpbin-jwt-auth.yaml
APISIX CRD 目前不支持在服务级别启用插件。
针对单个路由
- 控制台
- ADC
- Ingress Controller
如需对特定路由使用 JWT 身份认证,请在该路由上启用 JWT Auth 插件,而不是在服务上启用。
- 在侧边导航栏选择网关组的已发布服务,然后选择要修改的服务,例如版本为
1.0.0的httpbin。 - 在已发布服务中,从侧边导航栏选择路由。
- 选择目标路由,例如
get-ip。 - 在插件字段中,点击新增插件。
- 搜索
jwt-auth插件,然后点击新增。 - 在对话框中完成以下操作。
-
在 JSON 编辑器中添加以下配置。
{} -
点击新增。
更新路由配置,使用 JWT 身份认证。
services:
- name: httpbin
upstream:
name: default
scheme: http
nodes:
- host: httpbin.org
port: 80
weight: 100
routes:
- uris:
- /ip
name: get-ip
methods:
- GET
plugins:
jwt-auth:
_meta:
disable: false
将配置同步到 API7 网关。
adc sync -f adc-consumer.yaml -f adc-route.yaml
ADC 将配置文件作为唯一的配置依据。因此,请确保将消费者和服务的配置文件一起传递给 adc sync 命令,使两项配置都生效。
- Gateway API
- APISIX CRD
Gateway API 目前不支持在路由级别启用插件。
创建路由的 Kubernetes 清单文件,同时创建服务,并在服务上启用 JWT 身份认证。
apiVersion: apisix.apache.org/v2
kind: ApisixRoute
metadata:
namespace: api7
name: httpbin
spec:
ingressClassName: apisix
http:
- name: get-ip
match:
paths:
- /ip
backends:
- serviceName: httpbin
servicePort: 80
plugins:
- name: jwt-auth
enable: true
将配置应用到集群。
kubectl apply -f httpbin-jwt-auth.yaml
暴露 JWT 签名端点
本步骤用于在 API7 企业版中公开 JWT 签名端点。如果使用 HS256(默认)或 HS512 等对称算法,API7 企业版既是 JWT 签发方,也是验证方,必须完成此步骤。如果使用 RS256 或 ES256 等非对称算法,签发方和验证方可以由不同主体担任,此步骤可选。
jwt-auth 插件在 /apisix/plugin/jwt/sign 创建用于签署 JWT 的内部端点。使用 Public API 插件公开该端点。
- 新增名为
jwt-auth-api的已发布服务,以及名称为jwt-auth-api、路径为/api7/plugin/jwt/sign的路由。 - 在侧边导航栏选择插件,然后点击新增插件。
- 搜索
public-api插件,然后点击新增。 - 在对话框中完成以下操作。
-
在 JSON 编辑器中添加空配置。
{} -
点击新增。
验证 JWT 认证
按照配置 JWT 身份认证凭据创建具有 JWT 凭据的消费者。
按照以下步骤验证 JWT 身份认证。
- 发送不包含凭据的请求。
curl -i "http://127.0.0.1:9080/ip"
由于未提供凭据,你会收到 HTTP/1.1 401 Unauthorized 响应,响应体如下。
{"message":"Missing authorization in request"}
- 使用消费者 JWT 凭据中的
key获取 JWT Token。
jwt_token=$(curl -s "http://127.0.0.1:9080/apisix/plugin/jwt/sign?key=john-jwt-key") && echo $jwt_token
- 向 API 发送请求,在请求头中包含
jwt_token。
curl -i "http://127.0.0.1:9080/ip" -H "Authorization: ${jwt_token}"
请求包含正确凭据时,你会收到 HTTP/1.1 200 OK 响应。
30 秒后,Token 应已过期。使用相同 Token 发送请求进行验证,你会收到 HTTP/1.1 401 Unauthorized 响应,响应体如下。
{"message":"failed to verify jwt"}
为 API 启用 HMAC 认证
针对服务
如需对服务中的所有路由使用 HMAC 身份认证,请在服务上启用 HMAC Auth 插件。
- 控制台
- ADC
- Ingress Controller
- 在侧边导航栏选择网关组的已发布服务,然后选择要修改的服务,例如版本为
1.0.0的httpbin。 - 在侧边导航栏选择插件,然后点击新增插件。
- 搜索
hmac-auth插件,然后点击新增。 - 在对话框中完成以下操作。
-
在 JSON 编辑器中添加以下配置。
{} -
点击新增。
更新服务配置,使用 HMAC 身份认证。
services:
- name: httpbin
upstream:
name: default
scheme: http
nodes:
- host: httpbin.org
port: 80
weight: 100
plugins:
hmac-auth:
_meta:
disable: false
routes:
- uris:
- /ip
name: get-ip
methods:
- GET
将配置同步到 API7 企业版。
adc sync -f adc-consumer.yaml -f adc-service.yaml
ADC 将配置文件作为唯一的配置依据。因此,请确保将消费者和服务的配置文件一起传递给 adc sync 命令,使两项配置都生效。
- Gateway API
- APISIX CRD
创建路由的 Kubernetes 清单文件,同时创建服务,并在服务上启用 HMAC 身份认证。
apiVersion: apisix.apache.org/v1alpha1
kind: PluginConfig
metadata:
namespace: api7
name: auth-plugin-config
spec:
plugins:
- name: hmac-auth
config:
_meta:
disable: false
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
namespace: api7
name: httpbin
spec:
parentRefs:
- name: apisix
rules:
- matches:
- path:
type: Exact
value: /ip
filters:
- type: ExtensionRef
extensionRef:
group: apisix.apache.org
kind: PluginConfig
name: auth-plugin-config
backendRefs:
- name: httpbin
port: 80
将配置应用到集群。
kubectl apply -f httpbin-hmac-auth.yaml
APISIX CRD 目前不支持在服务级别启用插件。
针对单个路由
- 控制台
- ADC
- Ingress Controller
如需对特定路由使用 HMAC 身份认证,请在该路由上启用 HMAC Auth 插件,而不是在服务上启用。
- 在侧边导航栏选择网关组的已发布服务,然后选择要修改的服务,例如版本为
1.0.0的httpbin。 - 在已发布服务中,从侧边导航栏选择路由。
- 选择目标路由,例如
get-ip。 - 在插件字段中,点击新增插件。
- 搜索
hmac-auth插件,然后点击新增。 - 在对话框中完成以下操作。
-
在 JSON 编辑器中添加以下配置。
{} -
点击新增。
更新路由配置,使用 HMAC 身份认证。
services:
- name: httpbin
upstream:
name: default
scheme: http
nodes:
- host: httpbin.org
port: 80
weight: 100
routes:
- uris:
- /ip
name: get-ip
methods:
- GET
plugins:
jwt-auth:
_meta:
disable: false
将配置同步到 API7 网关。
adc sync -f adc-consumer.yaml -f adc-route.yaml
ADC 将配置文件作为唯一的配置依据。因此,请确保将消费者和服务的配置文件一起传递给 adc sync 命令,使两项配置都生效。
- Gateway API
- APISIX CRD
Gateway API 目前不支持在路由级别启用插件。
创建路由的 Kubernetes 清单文件,同时创建服务,并启用 HMAC 身份认证。
apiVersion: apisix.apache.org/v2
kind: ApisixRoute
metadata:
namespace: api7
name: httpbin
spec:
ingressClassName: apisix
http:
- name: get-ip
match:
paths:
- /ip
backends:
- serviceName: httpbin
servicePort: 80
plugins:
- name: hmac-auth
enable: true
将配置应用到集群。
kubectl apply -f httpbin-hmac-auth.yaml
验证 HMAC 认证
按照配置 HMAC 身份认证凭据创建具有 HMAC 凭据的消费者。
按照以下步骤验证 HMAC 身份认证。
- 生成签名
你可以使用以下 Python 代码片段,也可以选择其他技术栈。
import hmac
import hashlib
import base64
from datetime import datetime, timezone
key_id = "john-key" # Key ID
secret_key = b"john-hmac-key" # Secret Key
request_method = "GET" # HTTP 方法
request_path = "/headers" # 路由 URI
algorithm= "hmac-sha256" # 可使用 allowed_algorithms 中的其他算法
# 获取 GMT 当前日期和时间
# 注意,签名会在允许的时钟偏差(默认 300 秒)后失效
# 签名失效后可以重新生成,也可以在建议的安全范围内增大
# 时钟偏差以延长有效期
gmt_time = datetime.now(timezone.utc).strftime('%a, %d %b %Y %H:%M:%S GMT')
# 按顺序构造签名字符串
# 日期和后续自定义请求头应使用小写,并以单个空格分隔,
# 即 `<key>:<space><value>`
# https://datatracker.ietf.org/doc/html/draft-cavage-http-signatures-12#section-2.1.6
signing_string = (
f"{key_id}\n"
f"{request_method} {request_path}\n"
f"date: {gmt_time}\n"
)
# 创建签名
signature = hmac.new(secret_key, signing_string.encode('utf-8'), hashlib.sha256).digest()
signature_base64 = base64.b64encode(signature).decode('utf-8')
# 构造请求头
headers = {
"Date": gmt_time,
"Authorization": (
f'Signature keyId="{key_id}",algorithm="{algorithm}",'
f'headers="@request-target date",'
f'signature="{signature_base64}"'
)
}
# 打印请求头
print(headers)
运行脚本。
python3 hmac-sig-header-gen.py
- 发送不包含这些请求头的请求。
curl -i "http://127.0.0.1:9080/ip"
由于未提供凭据,你会收到 HTTP/1.1 401 Unauthorized 响应,响应体如下。
{"message":"Missing authorization in request"}
- 向 API 发送包含这些请求头的请求。
curl -X GET "http://127.0.0.1:9080/ip" \
-H "Date: Fri, 06 Sep 2024 06:41:29 GMT" \
-H 'Authorization: Signature keyId="alice-keyid",algorithm="hmac-sha256",headers="@request-target date",signature="wWfKQvPDr0wHQ4IHdluB4IzeNZcj0bGJs2wvoCOT5rM="'
请求包含正确凭据时,你会收到 HTTP/1.1 200 OK 响应,内容类似以下示例。
{
"headers":{
"Accept": "*/*",
"Authorization": "Signature keyId=\"john-key\",aigorithm=\'hmac-sha256\",headers=\"@reques
t-target date\", signature=\'HtQm1m8kGvnVlztZ59)XokweovFqQN04Ui6P6NfzjRr4=\'"
"Date": "Tue, 24 Sep 2024 10:28:41 GMT",
"Host": "127.0.0.1",
"User-Agent":"curl/8.7.1",
"X-Amzn-Trace-Id": "Root=1-66f29481-7355340a05778cbb21e9b25a",
"X-Consumer-Username": "John",
"X-Credential-Identifier": "4130bb4a-0fdc-461d-be8d-2bba8a1e36dc",
"X-Forwarded-Host": "127.0.0.1"
}
}
相关阅读
- 关键概念
- API 消费