带有安全配置文件的 Demo 只在 agent 上放置了 AuthBridge——tool 只是一个普通工作负载,agent → tool 的跳转只是一次裸的集群内 HTTP 调用。本指南是同一个天气 demo 的高级版本:AuthBridge 会注入到双方,并且每一次 agent 到 tool 的调用都会经过 OAuth 2.0 RFC 8693 令牌交换,因此 tool 看到的 token 的受众范围仅限于 tool。
具体来说:
- agent 的 AuthBridge 会将出站主机与
authproxy-routes 规则进行匹配,把其入站 JWT 交换为一个新的 access token;该 token 的 aud 声明是 tool 的 Keycloak client id,并在出站请求上注入 Authorization: Bearer <exchanged-token>。
- tool 的 AuthBridge 会在 MCP server 看到请求之前验证这个新 token。任何 token 中不包含 tool 受众的请求都会在 tool 的入口处被拒绝——即使它来自 mesh 内部的其他工作负载。
- Keycloak 会在两个 client 上启用
standard.token.exchange.enabled: true,并通过一个 client scope 和其中的 token mapper,将 tool 的受众写入交换后 token 的 aud 声明。
我们在每个资源名称后都使用 -advanced 后缀,因此这个 demo 可以与基础的 secure-profile demo 共存于同一个 team1 命名空间中。
涉及的 ConfigMap
高级 demo 会在 demo 命名空间中涉及两个与 AuthBridge 相关的 ConfigMap:
authproxy-routes 是唯一需要你显式执行 kubectl apply 的部分。
Keycloak client-id 约定
operator 的 ClientRegistrationReconciler 会使用简短的 <namespace>/<workload> 形式在 Keycloak 中注册每个工作负载(本 demo 中分别是 team1/weather-tool-advanced 和 team1/weather-service-advanced)。本指南中每个 route 的 target_audience 以及 Keycloak client scope 上的每个 audience mapper 都按这个简短形式编写——这也是 tool 自身入站 JWT 校验插件期望在交换后 token 的 aud 声明中看到的值。
前提条件
开始之前:
-
前两个指南都已完成(或已在原地重复其步骤):
- 安装安全配置文件依赖项 —— SPIRE、Keycloak、Istio ambient。
- 启用安全配置文件 ——
featureGates.globalEnabled: true,authbridgeConfig.enabled: true,并已设置 keycloak.publicUrl。
-
Kagenti operand 上的 featureGates.injectTools: true。 高级 demo 会把 AuthBridge 注入到 tool 上,而对 tool 工作负载的注入默认是关闭的。请先打一次补丁并滚动 controller,使新开关生效:
kubectl -n kagenti-system patch kagenti kagenti --type merge \
-p '{"spec":{"featureGates":{"injectTools":true}}}'
kubectl -n kagenti-system rollout restart deploy/kagenti-controller-manager
-
带有 kagenti-enabled=true 标签的 demo 命名空间 team1:
kubectl create namespace team1 --dry-run=client -o yaml | kubectl apply -f -
kubectl label namespace team1 kagenti-enabled=true --overwrite
-
一个提供 OpenAI 兼容 chat API 的 InferenceService(本指南在 models 中使用 qwen36-27b-gguf)。
-
具有读取 keycloak 命名空间中 keycloak-initial-admin 的权限的 kubectl 集群访问权限。
这个 demo 所依赖的 client 最终会以以下名称出现在 Keycloak 中——在整个指南中你都会用到它们:
SPIFFE ID 这一列是 sidecar 通过 SPIRE 进行 mTLS 时使用的——Alauda operator 不会把它作为 Keycloak 标识符来使用。
不同于基础 demo,这个 tool 工作负载会获得自己的 AgentRuntime,因此 AuthBridge webhook 会注入一个 sidecar,而 operator 会为 tool 的 ServiceAccount 注册一个 Keycloak client。不要自己在 Deployment 上设置 kagenti.io/type: tool——ValidatingAdmissionPolicy 会把这个标签保留给 operator,并由 operator 根据你创建的 AgentRuntime 来应用它。
kubectl apply -f - <<EOF
apiVersion: v1
kind: ServiceAccount
metadata:
name: weather-tool-advanced
namespace: team1
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: weather-tool-advanced
namespace: team1
labels:
app.kubernetes.io/name: weather-tool-advanced
spec:
replicas: 1
selector:
matchLabels:
app.kubernetes.io/name: weather-tool-advanced
template:
metadata:
labels:
app.kubernetes.io/name: weather-tool-advanced
spec:
serviceAccountName: weather-tool-advanced
containers:
- name: mcp
image: docker.io/alaudadockerhub/weather_tool:v0.1.0-rc.1
imagePullPolicy: IfNotPresent
env:
- name: PORT
value: "8000"
- name: HOST
value: 0.0.0.0
- name: UV_CACHE_DIR
value: /app/.cache/uv
- name: NO_PROXY
value: "127.0.0.1,localhost,.svc,.svc.cluster.local,geocoding-api.open-meteo.com,api.open-meteo.com"
ports:
- containerPort: 8000
volumeMounts:
- mountPath: /app/.cache
name: cache
volumes:
- name: cache
emptyDir: {}
---
apiVersion: v1
kind: Service
metadata:
name: weather-tool-advanced-mcp
namespace: team1
spec:
selector:
app.kubernetes.io/name: weather-tool-advanced
ports:
- name: http
port: 8000
targetPort: 8000
---
apiVersion: agent.kagenti.dev/v1alpha1
kind: AgentRuntime
metadata:
name: weather-tool-advanced-runtime
namespace: team1
spec:
type: tool
targetRef:
apiVersion: apps/v1
kind: Deployment
name: weather-tool-advanced
EOF
serviceAccountName: weather-tool-advanced —— SPIRE 会签发一个以 spiffe://<trustDomain>/ns/team1/sa/weather-tool-advanced 为键的 X.509 SVID,而 operator 会把 Keycloak client id 注册为 team1/weather-tool-advanced。
NO_PROXY 覆盖了 tool 到公共地理编码 API 的出站调用。webhook 会尊重预先声明的 NO_PROXY,因此这些请求会绕过 tool 自己的 forward-proxy sidecar(参见 在 proxy-sidecar 模式下允许出站流量)。
AgentRuntime 上的 spec.type: tool —— operator 会应用 kagenti.io/type: tool 标签,注入 AuthBridge sidecar(受 featureGates.injectTools: true 约束),并为 tool 注册 Keycloak client。
等待 sidecar 注入完成,并等待 credentials Secret 出现:
kubectl rollout status deploy/weather-tool-advanced -n team1 --timeout=180s
kubectl get pod -n team1 -l app.kubernetes.io/name=weather-tool-advanced
# NAME READY STATUS RESTARTS AGE
# weather-tool-advanced-XXXXXXXXXX-YYYYY 2/2 Running 0 1m
# The operator records the Secret name on the Deployment annotation
kubectl -n team1 get deploy weather-tool-advanced \
-o jsonpath='{.spec.template.metadata.annotations.kagenti\.io/keycloak-client-credentials-secret-name}'; echo
# kagenti-keycloak-client-credentials-<hash-tool>
READY 2/2 表示 tool 现在已经拥有一个 AuthBridge sidecar 和 mcp 应用容器。
第 2 步:为 token exchange 配置 Keycloak
operator 已经为 tool 创建了一个 Keycloak client(clientId team1/weather-tool-advanced)。我们仍然需要进行三个管理端更改:
- 创建一个 client scope
weather-tool-advanced-aud,并配置一个 audience mapper,把 team1/weather-tool-advanced 追加到交换后 token 的 aud 声明中。
- 在 tool client 上启用
standard.token.exchange.enabled: true。
- 将该 scope 作为 tool client 的一个可选 client scope,以便请求它的 token-exchange 请求可以成功。
我们通过一个临时 pod 从 Keycloak 的 admin REST API 执行这三项操作,该 pod 会挂载平台的 keycloak-initial-admin Secret。先把 Secret 复制到 demo 命名空间中(该 pod 只能挂载自己命名空间中的 Secret):
kubectl -n keycloak get secret keycloak-initial-admin -o yaml \
| sed 's/namespace: keycloak/namespace: team1/' \
| kubectl apply -f -
然后运行 setup Job:
kubectl apply -f - <<'EOF'
apiVersion: batch/v1
kind: Job
metadata:
name: keycloak-setup-advanced-tool
namespace: team1
spec:
ttlSecondsAfterFinished: 300
template:
spec:
restartPolicy: OnFailure
containers:
- name: setup
image: docker.io/alaudadockerhub/curl:8.1.2
command: ["/bin/sh", "-c"]
args:
- |
set -eu
KC=http://keycloak-service.keycloak.svc:8080
USER=$(cat /kc/username)
PASS=$(cat /kc/password)
T=$(curl -s -X POST $KC/realms/master/protocol/openid-connect/token \
-d grant_type=password -d client_id=admin-cli \
--data-urlencode "username=$USER" --data-urlencode "password=$PASS" \
| sed 's/.*"access_token":"\([^"]*\)".*/\1/')
AUTH="Authorization: Bearer $T"
echo "==> create client scope weather-tool-advanced-aud"
curl -sS -o /dev/null -w 'scope-status=%{http_code}\n' -X POST \
"$KC/admin/realms/kagenti/client-scopes" -H "$AUTH" -H 'Content-Type: application/json' -d '{
"name":"weather-tool-advanced-aud",
"protocol":"openid-connect",
"attributes":{"include.in.token.scope":"true","display.on.consent.screen":"true"},
"protocolMappers":[{
"name":"weather-tool-advanced-aud-mapper",
"protocol":"openid-connect",
"protocolMapper":"oidc-audience-mapper",
"consentRequired":false,
"config":{
"included.custom.audience":"team1/weather-tool-advanced",
"id.token.claim":"false",
"access.token.claim":"true",
"userinfo.token.claim":"false"
}
}]
}' || true
SCOPE_ID=$(curl -s "$KC/admin/realms/kagenti/client-scopes" -H "$AUTH" \
| tr '}' '\n' | grep 'weather-tool-advanced-aud' \
| grep -o '"id":"[^"]*"' | head -1 | sed 's/"id":"\([^"]*\)"/\1/')
echo "scope_id=$SCOPE_ID"
TOOL_ID=$(curl -s "$KC/admin/realms/kagenti/clients?clientId=team1%2Fweather-tool-advanced" -H "$AUTH" \
| grep -o '"id":"[^"]*"' | head -1 | sed 's/"id":"\([^"]*\)"/\1/')
echo "tool_id=$TOOL_ID"
echo "==> enable token exchange on tool client"
curl -sS -o /dev/null -w 'te-status=%{http_code}\n' -X PUT \
"$KC/admin/realms/kagenti/clients/$TOOL_ID" -H "$AUTH" -H 'Content-Type: application/json' \
-d '{"attributes":{"standard.token.exchange.enabled":"true"}}'
echo "==> add scope as optional on tool client"
curl -sS -o /dev/null -w 'opt-status=%{http_code}\n' -X PUT \
"$KC/admin/realms/kagenti/clients/$TOOL_ID/optional-client-scopes/$SCOPE_ID" -H "$AUTH"
volumeMounts:
- name: kc-admin
mountPath: /kc
readOnly: true
volumes:
- name: kc-admin
secret:
secretName: keycloak-initial-admin
EOF
kubectl -n team1 wait --for=condition=Complete job/keycloak-setup-advanced-tool --timeout=120s
kubectl -n team1 logs job/keycloak-setup-advanced-tool
日志尾部应出现:scope-status=201、te-status=204、opt-status=204。
第 3 步:准备 agent 的出站路由
agent 的 AuthBridge 会从同一命名空间中的 authproxy-routes ConfigMap 读取其出站规则。每条规则都会说明:“当出站请求的 Host 头匹配此模式时,把入站 JWT 交换为一个 aud 声明为该受众、并请求这些 scope 的 token”。
请在部署 agent 之前应用该规则,以便 sidecar 在首次启动时就能读取它:
kubectl apply -f - <<EOF
apiVersion: v1
kind: ConfigMap
metadata:
name: authproxy-routes
namespace: team1
data:
routes.yaml: |
- host: "weather-tool-advanced-mcp.team1.svc.cluster.local" # [!code callout]
target_audience: "team1/weather-tool-advanced" # [!code callout]
token_scopes: "openid weather-tool-advanced-aud"
EOF
host 与 HTTP Host 头 完全 匹配——不是短服务名。路由器使用 gobwas/glob,并将 . 作为段分隔符,因此 * 永远不会跨越点号。请使用集群内的完整 FQDN(不含端口;路由器在匹配前会去掉端口),或者显式列出你需要的模式。这里单独使用 weather-tool-advanced-mcp 不会匹配 weather-tool-advanced-mcp.team1.svc.cluster.local。
target_audience 是 tool 的 Keycloak clientId(Alauda 的 <ns>/<workload> 形式),也就是 tool 自身的入站 JWT 校验插件期望在交换后 token 的 aud 中看到的值。
如果没有匹配到 route,agent 的 AuthBridge 会回退到 default_policy: passthrough——token 会原样转发,其 aud 声明仍然是 team1/weather-service-advanced,而 tool 的入口在严格配置下会拒绝它。
routes.yaml 只会在 Configure 时加载一次
token-exchange 插件会在 sidecar 启动时读取 /etc/authproxy/routes.yaml。编辑 ConfigMap 不会立即对已经运行中的 pod 生效,直到它们重启并且 kubelet 已将新内容同步到挂载中(约 60 秒)。当你修改 route 时,请先应用 ConfigMap,等待约 60 秒,然后对受影响的工作负载执行 kubectl delete pod。仅执行 rollout restart 可能会与 kubelet 同步发生竞争,并使新 pod 仍然使用旧文件启动。
第 4 步:部署受保护的 agent
与基础 secure demo 的形态相同,但使用 -advanced 命名,并指向高级 tool 的 Service。MCP_URL 和 route 的 host 字段必须一致——两者都必须是集群内的完整 FQDN。
kubectl apply -f - <<EOF
apiVersion: v1
kind: ServiceAccount
metadata:
name: weather-service-advanced
namespace: team1
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: weather-service-advanced
namespace: team1
labels:
app.kubernetes.io/name: weather-service-advanced
protocol.kagenti.io/a2a: ""
spec:
replicas: 1
selector:
matchLabels:
app.kubernetes.io/name: weather-service-advanced
template:
metadata:
labels:
app.kubernetes.io/name: weather-service-advanced
spec:
serviceAccountName: weather-service-advanced
containers:
- name: agent
image: docker.io/alaudadockerhub/weather_service:v0.1.0-rc.1
imagePullPolicy: IfNotPresent
ports:
- containerPort: 8000
env:
- name: PORT
value: "8000"
- name: UV_CACHE_DIR
value: /app/.cache/uv
- name: MCP_URL
value: http://weather-tool-advanced-mcp.team1.svc.cluster.local:8000/mcp
- name: LLM_API_BASE
value: http://qwen36-27b-gguf-predictor.models.svc.cluster.local/v1
- name: LLM_API_KEY
value: dummy
- name: LLM_MODEL
value: qwen36-27b-gguf
---
apiVersion: v1
kind: Service
metadata:
name: weather-service-advanced
namespace: team1
spec:
selector:
app.kubernetes.io/name: weather-service-advanced
ports:
- name: http
port: 8000
targetPort: 8000
---
apiVersion: agent.kagenti.dev/v1alpha1
kind: AgentRuntime
metadata:
name: weather-service-advanced-runtime
namespace: team1
spec:
type: agent
targetRef:
apiVersion: apps/v1
kind: Deployment
name: weather-service-advanced
EOF
kubectl rollout status deploy/weather-service-advanced -n team1 --timeout=180s
kubectl get pods -n team1 -l app.kubernetes.io/name=weather-service-advanced
# NAME READY STATUS RESTARTS AGE
# weather-service-advanced-XXXXXXXXX-YYYYY 2/2 Running 0 1m
一旦 agent pod 进入 Ready 状态并且其 Keycloak client 已注册,请再运行一个 setup Job,在 agent client 上启用 token exchange,并把同一个 scope 也作为可选 scope 分配给它。这个 Job 是第 2 步的两行变体:
kubectl apply -f - <<'EOF'
apiVersion: batch/v1
kind: Job
metadata:
name: keycloak-setup-advanced-agent
namespace: team1
spec:
ttlSecondsAfterFinished: 300
template:
spec:
restartPolicy: OnFailure
containers:
- name: setup
image: docker.io/alaudadockerhub/curl:8.1.2
command: ["/bin/sh", "-c"]
args:
- |
set -eu
KC=http://keycloak-service.keycloak.svc:8080
USER=$(cat /kc/username)
PASS=$(cat /kc/password)
T=$(curl -s -X POST $KC/realms/master/protocol/openid-connect/token \
-d grant_type=password -d client_id=admin-cli \
--data-urlencode "username=$USER" --data-urlencode "password=$PASS" \
| sed 's/.*"access_token":"\([^"]*\)".*/\1/')
AUTH="Authorization: Bearer $T"
SCOPE_ID=$(curl -s "$KC/admin/realms/kagenti/client-scopes" -H "$AUTH" \
| tr '}' '\n' | grep 'weather-tool-advanced-aud' \
| grep -o '"id":"[^"]*"' | head -1 | sed 's/"id":"\([^"]*\)"/\1/')
AGENT_ID=$(curl -s "$KC/admin/realms/kagenti/clients?clientId=team1%2Fweather-service-advanced" -H "$AUTH" \
| grep -o '"id":"[^"]*"' | head -1 | sed 's/"id":"\([^"]*\)"/\1/')
echo "agent_id=$AGENT_ID scope_id=$SCOPE_ID"
curl -sS -o /dev/null -w 'te-status=%{http_code}\n' -X PUT \
"$KC/admin/realms/kagenti/clients/$AGENT_ID" -H "$AUTH" -H 'Content-Type: application/json' \
-d '{"attributes":{"standard.token.exchange.enabled":"true"}}'
curl -sS -o /dev/null -w 'opt-status=%{http_code}\n' -X PUT \
"$KC/admin/realms/kagenti/clients/$AGENT_ID/optional-client-scopes/$SCOPE_ID" -H "$AUTH"
volumeMounts:
- name: kc-admin
mountPath: /kc
readOnly: true
volumes:
- name: kc-admin
secret:
secretName: keycloak-initial-admin
EOF
kubectl -n team1 wait --for=condition=Complete job/keycloak-setup-advanced-agent --timeout=120s
kubectl -n team1 logs job/keycloak-setup-advanced-agent
预期结果:te-status=204 和 opt-status=204 都会出现。
第 5 步:验证 token-exchange 路径
向 agent 发送一个已认证的 A2A message/send 请求,方式与 基础 secure demo 的第 4 步 完全相同。你挂载的 credentials Secret 是 agent 的——交换会在 agent 的 AuthBridge 内部透明完成。
从 Deployment 上 operator 的注解中找到 agent 的 credentials Secret:
AGENT_SECRET=$(kubectl -n team1 get deploy weather-service-advanced \
-o jsonpath='{.spec.template.metadata.annotations.kagenti\.io/keycloak-client-credentials-secret-name}')
echo "$AGENT_SECRET"
# kagenti-keycloak-client-credentials-<agent-hash>
从一个 pod 中运行已认证查询(此处的 shell 使用上面 $AGENT_SECRET 的值):
kubectl apply -f - <<EOF
apiVersion: v1
kind: Pod
metadata:
name: adv-smoke
namespace: team1
spec:
restartPolicy: Never
containers:
- name: query
image: docker.io/alaudadockerhub/curl:8.1.2
command: ["/bin/sh", "-c"]
args:
- |
set -e
CID=\$(cat /creds/client-id.txt)
CSEC=\$(cat /creds/client-secret.txt)
TOKEN=\$(curl -s \\
http://keycloak-service.keycloak.svc:8080/realms/kagenti/protocol/openid-connect/token \\
-d grant_type=client_credentials \\
--data-urlencode "client_id=\$CID" \\
--data-urlencode "client_secret=\$CSEC" \\
| sed 's/.*"access_token":"\\([^"]*\\)".*/\\1/')
curl -sS -X POST http://weather-service-advanced.team1.svc.cluster.local:8000/ \\
-H "Authorization: Bearer \$TOKEN" \\
-H "Content-Type: application/json" \\
-d '{"jsonrpc":"2.0","id":"1","method":"message/send","params":{"message":{"role":"user","parts":[{"kind":"text","text":"What is the weather in Berlin?"}],"messageId":"m1"}}}'
volumeMounts:
- name: creds
mountPath: /creds
readOnly: true
volumes:
- name: creds
secret:
secretName: $AGENT_SECRET
EOF
kubectl -n team1 wait --for=condition=Ready pod/adv-smoke --timeout=60s
kubectl -n team1 logs adv-smoke
kubectl -n team1 delete pod adv-smoke
你应该会得到一个包含真实天气数据的已完成 A2A task。请求路径如下:
client ─(token A, aud=team1/weather-service-advanced)─▶ agent AuthBridge
│ validates token A (inbound)
▼
weather-service-advanced
│ MCP call to weather-tool-advanced-mcp
▼
agent AuthBridge outbound
│ matches route → RFC 8693 exchange
│ obtains token B (aud=team1/weather-tool-advanced)
▼
tool AuthBridge
│ validates token B against its own audience
▼
weather-tool-advanced (mcp)
│ HTTPS to geocoding-api.open-meteo.com (NO_PROXY)
▼
response
在 agent-sidecar 日志中确认交换已经发生:
kubectl -n team1 logs -c authbridge-proxy \
-l app.kubernetes.io/name=weather-service-advanced --tail=100 \
| grep -E 'outbound token exchanged|outbound passthrough'
# time=... level=INFO msg="outbound token exchanged" host=weather-tool-advanced-mcp.team1.svc.cluster.local:8000 audience=team1/weather-tool-advanced
以及 tool 侧的入站验证:
kubectl -n team1 logs -c authbridge-proxy \
-l app.kubernetes.io/name=weather-tool-advanced --tail=100 \
| grep -E 'inbound authorized|inbound rejected'
# time=... level=INFO msg="inbound authorized" subject=<uuid> clientID=team1/weather-service-advanced
agent 侧出现 "outbound token exchanged",同时 tool 侧出现 "inbound authorized",这两行就是 RFC 8693 流程端到端连通的证明。
清理
kubectl delete namespace team1
如果你之后不再打算保护 tool 工作负载,也可以把 Kagenti operand 上的 featureGates.injectTools 还原为 false:
kubectl -n kagenti-system patch kagenti kagenti --type merge \
-p '{"spec":{"featureGates":{"injectTools":false}}}'
故障排查