Homelab 零信任访问:HashiCorp Boundary + Vault 实践
Boundary 0.21 + Vault 2.2:Transit KMS、OIDC 登录与按身份授权的 SSH 访问
为什么不用 VPN
我以前访问 Homelab 的方式很典型:WireGuard 连回内网,再从一台跳板机 SSH 到其他机器。能用,但有几个绕不过去的问题:
- VPN 一旦连上,整个内网都对客户端可见,权限边界只有「连没连上」
- 跳板机上的密钥和 known_hosts 越堆越多,谁在什么时候登录了哪台机器,只能翻 shell history
- 给临时设备开权限,往往意味着加一条 VPN peer 或复制一把私钥
零信任的思路反过来:不因为你在内网就信任你,每次连接都要重新验证身份,并且只授权到具体的 Target。HashiCorp Boundary 就是做这件事的:用户先通过认证方法(密码、OIDC、LDAP 等)登录,再按 Role/Grant 决定能不能连接某个 Target;实际的连接由 Worker 代理,用户不需要拿到目标机器的网络位置或长期凭据。
本文在 1 台 Debian 12 虚拟机上部署了 Vault 和 Boundary,走通了这条链路:
用户 -> Boundary CLI/UI -> Controller -> Vault Transit(加密)
-> Worker -> Target 127.0.0.1:22
实测:Vault 2.2.2 初始化与 Transit、Boundary 0.21.3 的 PostgreSQL/Controller/Worker、密码认证、用户/角色/授权、TCP Target、通过 Boundary 的 SSH 会话,以及 Authentik 2026.8.5 的完整 OIDC 登录(Provider/Application、Authorization Code、回调、自动创建 User)。
未实测:Authentik 的 managed group(managed group 机制用临时测试 IdP 验证过,Authentik 需要额外的 groups scope mapping)、Vault Agent/AppRole 自动续期、跨版本升级。
方案对比
| 方案 | 定位 | 开源版限制 | 适合场景 |
|---|---|---|---|
| Boundary | HashiCorp 生态的零信任访问 | OSS 仅 TCP Target,无 SSH Target/会话录制 | 已有 Vault、想要身份驱动授权 |
| Teleport | 企业级访问平台 | 社区版功能较多,但架构更重 | 需要完整审计、SSH/K8s/DB 统一入口 |
| Cloudflare Access | SaaS 零信任 | 依赖 Cloudflare 网络 | 不想自托管控制面 |
| JumpServer | 堡垒机 | 偏传统运维审计 | 以 Web 终端和录像为主 |
Boundary 的 OSS 版本有一个必须先说清楚的限制:只有 TCP Target。虽然 CLI 里有 targets create ssh,OSS Controller 会返回 Unknown type provided;SSH Target 的自动凭据注入和会话录制属于 Enterprise/HCP 功能。OSS 里可以用 TCP Target 加 boundary connect 做本地端口转发,再在客户端侧 SSH,本文走的就是这条路。
架构与实验环境
实验环境
- Debian 12 虚拟机,4 vCPU / 5.8 GiB 内存
- Vault 2.2.2,监听
127.0.0.1:8202,Raft 存储 - Boundary 0.21.3,Controller
9200/9201,Worker9202 - PostgreSQL 15(Docker),只监听
127.0.0.1:5432 - 所有组件在同一台机器上,Vault 与 Boundary 通过 localhost 通信
生产环境应该把 Vault、Boundary Controller 和 Worker 拆开:Vault 单独一台机器,Controller 只暴露 API,Worker 放在能访问目标资源的网段。本文为了验证方便把它们放在同一台 VM,端口和配置都按可拆分的方式写。
graph TB
CLI["客户端 Boundary CLI"]
UI["客户端 Boundary UI"]
subgraph Host["Debian 12 虚拟机"]
Controller[Boundary Controller<br/>:9200 API / :9201 Cluster]
Worker[Boundary Worker<br/>:9202 Proxy]
PG[(PostgreSQL<br/>:5432)]
Vault[HashiCorp Vault 2.2.2<br/>:8202]
Target[SSH Target<br/>127.0.0.1:22]
Controller --> PG
Controller --> Vault
Worker --> Controller
Worker --> Target
end
CLI -->|"HTTP/HTTPS"| Controller
UI -->|"HTTP/HTTPS"| Controller
style Controller fill:#7c3aed,color:#fff
style Worker fill:#22c55e,color:#fff
style Vault fill:#eab308,color:#000
style PG fill:#2563eb,color:#fff
| 端口 | 用途 |
|---|---|
| 8202 / 8203 | Vault API / Raft cluster |
| 9200 / 9201 | Boundary Controller API / cluster |
| 9202 | Boundary Worker proxy |
| 5432 | Boundary PostgreSQL,只监听 127.0.0.1 |
| 22 | 被访问的 SSH Target |
这套组件跑起来后,Vault/Boundary/PostgreSQL 合计大约 700 MiB 内存,剩下的大部分留给系统和测试会话。
部署 Vault
安装二进制
Vault 2.x 的社区版二进制可以从 HashiCorp Releases 下载。本文使用 2.2.2:
cd /tmp
curl -fO https://releases.hashicorp.com/vault/2.2.2/vault_2.2.2_linux_amd64.zip
unzip vault_2.2.2_linux_amd64.zip
sudo install -m 755 vault /usr/local/bin/vault
vault version
# Vault v2.2.2 ...
配置 Raft 存储
实验环境为了少一层证书,Vault 监听 HTTP;生产环境应在 listener 上启用 TLS,并让 Boundary 的 KMS 配置使用 https://:
# /etc/vault-boundary.d/vault.hcl
ui = true
api_addr = "http://127.0.0.1:8202"
cluster_addr = "http://127.0.0.1:8203"
disable_mlock = true
storage "raft" {
path = "/opt/vault-boundary/data"
node_id = "vault-boundary-1"
}
listener "tcp" {
address = "127.0.0.1:8202"
cluster_address = "127.0.0.1:8203"
tls_disable = true
}
sudo useradd --system --home /opt/vault-boundary/data --shell /sbin/nologin vault || true
sudo mkdir -p /opt/vault-boundary/data /etc/vault-boundary.d
sudo chown -R vault:vault /opt/vault-boundary
systemd 服务:
# /etc/systemd/system/vault-boundary.service
[Unit]
Description=Vault for Boundary lab
After=network-online.target
Wants=network-online.target
[Service]
User=vault
Group=vault
ExecStart=/usr/local/bin/vault server -config=/etc/vault-boundary.d/vault.hcl
Restart=on-failure
LimitMEMLOCK=infinity
[Install]
WantedBy=multi-user.target
sudo systemctl daemon-reload
sudo systemctl enable --now vault-boundary
VAULT_ADDR=http://127.0.0.1:8202 vault status
初始化与解封
实验环境用 1 个 share 简化操作;生产环境至少用 5 个 share、3 个 threshold,并把 unseal key 分开保存:
VAULT_ADDR=http://127.0.0.1:8202 \
vault operator init -key-shares=1 -key-threshold=1 -format=json \
| sudo tee /root/vault-boundary-init.json >/dev/null
sudo chmod 600 /root/vault-boundary-init.json
从 JSON 里取出 unseal key 和 root token,解封:
KEY=$(sudo python3 -c 'import json;print(json.load(open("/root/vault-boundary-init.json"))["unseal_keys_b64"][0])')
ROOT=$(sudo python3 -c 'import json;print(json.load(open("/root/vault-boundary-init.json"))["root_token"])')
VAULT_ADDR=http://127.0.0.1:8202 vault operator unseal "$KEY"
root token 只用于初始化。初始化完成后应创建带策略的普通 token 或 AppRole,root token 离线保存。
Transit 引擎
Boundary 用 Vault Transit 加密数据库里的敏感字段。Transit 的密钥不需要离开 Vault,Boundary 只把明文发给 Vault,拿回密文:
export VAULT_ADDR=http://127.0.0.1:8202
export VAULT_TOKEN="$ROOT"
vault secrets enable transit
vault write -f transit/keys/boundary
vault write -f transit/keys/boundary-worker-auth
vault write -f transit/keys/boundary-recovery
实验环境用一个允许 transit/* 的周期 token,减少变量;生产环境应该按 key 收紧:
vault policy write boundary-controller - <<'EOF'
path "transit/*" {
capabilities = ["create", "read", "update", "delete", "list"]
}
EOF
sudo mkdir -p /etc/boundary.d
vault token create -policy=boundary-controller -period=24h -field=token \
| sudo tee /etc/boundary.d/vault-token >/dev/null
sudo chmod 600 /etc/boundary.d/vault-token
EnvironmentFile 注入 VAULT_TOKEN。生产环境建议用 AppRole 让 Vault Agent 自动获取和续期 token,再渲染成 /run/boundary/vault-token.env;这样 token 不落在服务配置里,也不需要人工轮换。Vault Agent 的方案本文没有做端到端实测。实测 Vault 状态和 Transit:
VAULT_ADDR=http://127.0.0.1:8202 vault status
VAULT_TOKEN="$ROOT" vault secrets list | grep transit
# transit/ transit transit_afeaf5ae n/a
部署 Boundary
安装 0.21.3
Boundary 社区版当前是 0.21.3:
cd /tmp
curl -fO https://releases.hashicorp.com/boundary/0.21.3/boundary_0.21.3_linux_amd64.zip
unzip boundary_0.21.3_linux_amd64.zip
sudo install -m 755 boundary /usr/local/bin/boundary
boundary version
# Version Number: 0.21.3
PostgreSQL
Boundary 的元数据存在 PostgreSQL。实验环境用 Docker 跑一个只监听本机的实例:
docker volume create boundary-postgres-data
docker run --name boundary-postgres -d \
-e POSTGRES_USER=boundary \
-e POSTGRES_PASSWORD='<strong-password>' \
-e POSTGRES_DB=boundary \
-v boundary-postgres-data:/var/lib/postgresql/data \
-p 127.0.0.1:5432:5432 \
--restart unless-stopped \
postgres:15-alpine
先创建运行 Boundary 的系统用户和目录:
sudo useradd --system --home /var/lib/boundary --shell /usr/sbin/nologin boundary || true
sudo mkdir -p /etc/boundary.d /var/lib/boundary /var/log/boundary
sudo chown -R boundary:boundary /etc/boundary.d /var/lib/boundary /var/log/boundary
把数据库 URL 和 Vault token 放进一个 600 权限的环境文件:
# /etc/boundary.d/boundary.env
DATABASE_URL=postgresql://boundary:<strong-password>@127.0.0.1:5432/boundary?sslmode=disable
VAULT_ADDR=http://127.0.0.1:8202
VAULT_TOKEN=<周期 token 或 Vault Agent 渲染的值>
Controller 配置
# /etc/boundary.d/controller.hcl
disable_mlock = true
controller {
name = "boundary-controller-01"
database {
url = "postgresql://boundary:<strong-password>@127.0.0.1:5432/boundary?sslmode=disable"
}
}
listener "tcp" {
purpose = "api"
address = "127.0.0.1:9200"
tls_disable = true
}
listener "tcp" {
purpose = "cluster"
address = "127.0.0.1:9201"
tls_disable = true
}
kms "transit" {
purpose = "root"
address = "http://127.0.0.1:8202"
disable_renewal = true
key_name = "boundary"
mount_path = "transit"
}
kms "transit" {
purpose = "worker-auth"
address = "http://127.0.0.1:8202"
disable_renewal = true
key_name = "boundary-worker-auth"
mount_path = "transit"
}
kms "transit" {
purpose = "recovery"
address = "http://127.0.0.1:8202"
disable_renewal = true
key_name = "boundary-recovery"
mount_path = "transit"
}
tls_disable = true,Vault 也是 HTTP。生产环境应给 Boundary listener 启用 TLS,或者用 Nginx/Ingress 终结 TLS,并把 Controller 的 advertise_url 和 OIDC 的 api_url_prefix 改成外部 HTTPS 地址。这里三个 KMS 都从环境变量 VAULT_TOKEN 取 token;disable_renewal = true 表示续期由外部负责(生产用 Vault Agent,实验用周期 token)。
Worker 配置
# /etc/boundary.d/worker.hcl
disable_mlock = true
listener "tcp" {
address = "127.0.0.1:9202"
purpose = "proxy"
}
worker {
name = "boundary-worker-01"
public_addr = "127.0.0.1:9202"
initial_upstreams = ["127.0.0.1:9201"]
tags {
type = ["worker", "egress"]
}
}
kms "transit" {
purpose = "worker-auth"
address = "http://127.0.0.1:8202"
disable_renewal = true
key_name = "boundary-worker-auth"
mount_path = "transit"
}
name,否则启动会报错。auth_storage_path 也不能和 KMS 认证一起用,它属于 PKI 认证模式。systemd 服务
Controller 和 Worker 都用同一个环境文件;Vault token 在 EnvironmentFile 里注入,进程启动后从环境变量读取。
# /etc/systemd/system/boundary-controller.service
[Unit]
Description=HashiCorp Boundary Controller
After=network-online.target boundary-postgres.service
Wants=network-online.target
[Service]
User=boundary
Group=boundary
EnvironmentFile=/etc/boundary.d/boundary.env
ExecStart=/usr/local/bin/boundary server -config=/etc/boundary.d/controller.hcl
Restart=on-failure
RestartSec=5
LimitMEMLOCK=infinity
[Install]
WantedBy=multi-user.target
Worker 服务同理,把 ExecStart 换成 worker.hcl,并加 After=boundary-controller.service。
初始化数据库
Boundary 第一次启动前要初始化数据库:
sudo -u boundary env \
VAULT_ADDR=http://127.0.0.1:8202 \
VAULT_TOKEN="$(sudo cat /etc/boundary.d/vault-token)" \
boundary database init -config /etc/boundary.d/controller.hcl
初始化成功后会输出管理员登录凭据,以及自动生成的 org、project、host catalog、两个 TCP Target。把输出保存到 600 权限的文件里;如果丢了管理员凭据,只能走 recovery KMS 或重建数据库。
sudo systemctl daemon-reload
sudo systemctl enable --now boundary-controller boundary-worker
sudo ss -tlnp | grep -E ':(9200|9201|9202) '
Worker 注册成功后,Boundary 后台的 Workers 页面会显示它的版本、地址和最近心跳:

Controller 的 UI 默认就在 9200 端口:


服务状态检查
systemctl is-active boundary-controller boundary-worker vault-boundary
# active
# active
# active
VAULT_ADDR=http://127.0.0.1:8202 vault status
# Sealed false
Vault、Boundary、PostgreSQL 的状态和 lab-ssh Target 的 CLI 输出:

授权模型
Boundary 的授权模型有几层,先把概念理清,后面命令才不会乱:
| 概念 | 作用 |
|---|---|
| Scope | 层级容器:Global -> Organization -> Project |
| Auth Method | 认证方式,比如密码、OIDC、LDAP |
| Account | 某个 Auth Method 下的登录凭据 |
| User | 身份实体,可以关联多个 Account |
| Role | 权限载体,包含 Grant 和 Principal |
| Grant | 权限声明,格式 ids=...;type=...;actions=... |
| Target | 用户最终连接的目标(TCP/SSH/数据库等) |
认证方法必须放在 Global 或 Org Scope,不能放在 Project;Target 和 Role 通常放在 Project。一个典型的流程是:
- 在 Org 下创建 Project
- 在 Org 下创建密码或 OIDC Auth Method
- 创建 User,并把 Account 关联到 User
- 在 Project 下创建 Role,加 Target 授权和 Principal
- 用户登录后,只能看到/连接被授权的 Target
实测:创建一个受限用户
下面的命令是用管理员 token 执行的。CLI 的 BOUNDARY_TOKEN 环境变量已标记为 deprecated,建议显式用 -token env://TOKEN:
export BOUNDARY_ADDR=http://127.0.0.1:9200
export TOKEN="$(sudo cat /root/boundary-token)"
# 1. 在已有 org 下创建 project
boundary scopes create \
-scope-id o_xxxxxxxxxx \
-name boundary-lab \
-description "Boundary lab project" \
-token env://TOKEN
# 2. 在 org 下创建密码认证方法
boundary auth-methods create password \
-scope-id o_xxxxxxxxxx \
-name lab-password \
-description "Lab password auth" \
-token env://TOKEN
# 3. 创建用户
boundary users create \
-scope-id o_xxxxxxxxxx \
-name lab-user \
-description "Lab user" \
-token env://TOKEN
# 4. 创建密码账户(Account)
export LAB_PASS='<lab-password>'
boundary accounts create password \
-auth-method-id ampw_xxxxxxxxxx \
-login-name labuser \
-password env://LAB_PASS \
-token env://TOKEN
# 5. 把 account 关联到用户
boundary users add-accounts \
-id <user_id> \
-account <account_id> \
-token env://TOKEN
然后在 Project 下创建 Role,只授予 Target 的查看和连接权限:
boundary roles create \
-scope-id p_xxxxxxxxxx \
-name lab-target-role \
-token env://TOKEN
boundary roles add-grants \
-id <role_id> \
-grant 'ids=*;type=target;actions=list,read,authorize-session' \
-token env://TOKEN
boundary roles add-principals \
-id <role_id> \
-principal <user_id> \
-token env://TOKEN
用普通用户登录,确认能看到 Target:
export LAB_PASS='<lab-password>'
boundary authenticate password \
-keyring-type none \
-auth-method-id ampw_xxxxxxxxxx \
-login-name labuser \
-password env://LAB_PASS \
-format json > /tmp/lab-auth.json
export LAB_TOKEN="$(python3 -c 'import json;print(json.load(open("/tmp/lab-auth.json"))["item"]["attributes"]["token"])')"
boundary targets list -scope-id p_xxxxxxxxxx -token env://LAB_TOKEN
实测这个用户只拿到 target 的 list/read/authorize-session,没有管理权限;登录后能看到 lab-ssh 和自动生成的两个 Target。
Grant 语法
ids=<资源 ID 或 *>;type=<资源类型>;actions=<操作>;output_fields=<可选字段>
常用的最小授权:
| 目的 | Grant |
|---|---|
| 查看并连接 Target | ids=*;type=target;actions=list,read,authorize-session |
| 查看会话 | ids=*;type=session;actions=list,read |
| 管理 Host Catalog | ids=*;type=host-catalog;actions=* 加 host-set、host 的权限 |
| 全局管理员 | ids=*;type=*;actions=*(只给管理员) |
权限会从父 Scope 向下继承,但 Role 本身是 Scope 资源;给 Project 建 Role 时,Grant 默认只在这个 Project 内生效。
Target 与 SSH 会话
Boundary 初始化时会自动生成一个直接地址 Target 和一个基于 Host Set 的 Target。可以再创建一个明确的 lab-ssh:
boundary targets create tcp \
-scope-id p_xxxxxxxxxx \
-name lab-ssh \
-description "SSH to lab host" \
-address 127.0.0.1 \
-default-port 22 \
-token env://TOKEN
OSS 版只支持 TCP Target,所以连接方式是先用 Boundary 拿到本地代理端口,再在客户端 SSH:
boundary connect -target-id ttcp_xxxxxxxxxx -token env://LAB_TOKEN
输出类似:
Proxy listening information:
Address: 127.0.0.1
Port: 43931
Protocol: tcp
Session ID: s_xxxxxxxxxx
然后另开一个终端:
ssh -p 43931 -i ~/.ssh/boundary_test \
-o StrictHostKeyChecking=no [email protected]
实测输出:
Warning: Permanently added '[127.0.0.1]:43931' (ED25519) to the list of known hosts.
lab-ssh-target-ok
boundary targets create ssh,OSS Controller 会返回 Unknown type provided。SSH Target 的自动凭据注入和会话录制需要 Enterprise 或 HCP Boundary。OSS 里用 TCP Target + boundary connect + 客户端 SSH 即可,但审计只能依赖客户端和 Target 侧的日志。boundary connect ssh -target-id ... 对 127.0.0.1 这类直接地址可能报 hostname contains invalid characters。先用 boundary connect 拿到本地端口,再用系统 ssh 连接,行为更可控,也方便指定私钥和 known_hosts 策略。Worker 选择
Worker 可以用 tags 和 -egress-worker-filter 过滤。本文的 Worker 带 type=worker 和 type=egress 两个 tag;只有一个 Worker 时无需过滤,多 Worker/多网段时再按 tag 指定,例如:
boundary targets create tcp \
-egress-worker-filter '"egress" in "/tags/type"' \
...
OIDC 接入
前面用密码认证跑通了 Boundary 的核心链路。实际使用中更希望直接接 Authentik,让用户用统一身份登录。Boundary 的 OIDC 配置有几个顺序和字段容易踩坑,下面按实际流程拆开。
OIDC 在 Boundary 里的完整流程
sequenceDiagram
participant User as 用户浏览器
participant Boundary as Boundary Controller
participant IdP as Authentik
User->>Boundary: 访问登录页,选择 OIDC 认证方法
Boundary->>User: 302 到 IdP 的 authorization endpoint(带 state/nonce)
User->>IdP: 登录并授权
IdP->>User: 302 回 Boundary 回调地址(authorization code)
User->>Boundary: GET /v1/auth-methods/oidc:authenticate:callback?code=...
Boundary->>IdP: 用 code 换 token
IdP-->>Boundary: id_token + access_token
Boundary->>Boundary: 校验 issuer/audience/签名,提取 sub/name/email/groups
Boundary->>Boundary: 首次登录创建 Account;如果该方法是 scope 的 primary,则自动创建 User
Boundary-->>User: 登录成功,进入 Boundary UI
这里有三个关键点:
- 回调地址是固定的:
<api-url-prefix>/v1/auth-methods/oidc:authenticate:callback。路径里的oidc是字面值,不是 Auth Method ID;实际 ID 是amoidc_...,但它不会出现在回调路径里。 - Auth Method 默认是 inactive:创建后必须显式改成
active-public(或active-private),否则登录页根本不会显示它。 - 只有 primary Auth Method 会自动创建 User:OIDC 首次登录会创建 Account;如果这个 Auth Method 不是所在 Scope 的 primary,Boundary 会拒绝自动创建 User,并报
auth method is not primary for the scope so refusing to auto-create user。
Authentik 侧配置
在 Authentik 里创建一个 OAuth2/OpenID Provider 和一个 Application:
| 配置项 | 值 |
|---|---|
| Provider 类型 | OAuth2/OpenID |
| Name | HashiCorp Boundary |
| Authorization flow | default-provider-authorization-explicit-consent |
| Client type | Confidential |
| Client ID | 自动生成或自定义,记下来 |
| Client Secret | 自动生成,记下来 |
| Redirect URI | https://boundary.example.com/v1/auth-methods/oidc:authenticate:callback |
| Signing Key | 选择一个 RSA Key |
| Grant types | Authorization Code、Refresh Token |
| Scopes | openid、email、profile、groups |
Application 侧填同一个 Provider,Launch URL 填 Boundary 的外部地址。
如果想让 Authentik 的组进入 Boundary,需要额外创建一个 Scope Mapping(只做登录可以先不加,等要映射组时再补):
- 打开 Customization -> Property Mappings -> Create -> Scope Mapping
- Name 填
groups,Scope name 填groups - Expression:
return {
"groups": [group.name for group in request.user.ak_groups.all()],
}
- 回到 Provider 的 Advanced protocol settings,把这个
groupsscope 加到 Scopes 里。
验证 OIDC Discovery:
curl -s https://auth.example.com/application/o/hashicorp-boundary/.well-known/openid-configuration \
| jq '{issuer, authorization_endpoint, token_endpoint, userinfo_endpoint, jwks_uri}'
issuer 必须和 Boundary 里填的完全一致,尤其注意末尾斜杠。
Boundary 侧:创建 OIDC Auth Method
export BOUNDARY_ADDR=https://boundary.example.com
export TOKEN='<admin-token>'
export OIDC_CLIENT_SECRET='<authentik-client-secret>'
boundary auth-methods create oidc \
-scope-id o_xxxxxxxxxx \
-name authentik-oidc \
-description "Authentik OIDC" \
-issuer 'https://auth.example.com/application/o/hashicorp-boundary/' \
-client-id '<client-id>' \
-client-secret "$OIDC_CLIENT_SECRET" \
-api-url-prefix 'https://boundary.example.com' \
-signing-algorithm RS256 \
-claims-scopes email \
-claims-scopes profile \
-account-claim-maps 'email=name' \
-allowed-audience '<client-id>' \
-token env://TOKEN
参数解释:
| 参数 | 作用 |
|---|---|
-issuer |
IdP 的 issuer URL,必须和 discovery 文档一致 |
-client-id / -client-secret |
Authentik Provider 的客户端凭据 |
-api-url-prefix |
Boundary 对外地址,用于生成回调 URL |
-claims-scopes |
额外请求的 scope,可重复;不写 email/profile 时通常只能拿到 sub,用户名可能是一串 hash |
-account-claim-maps |
把 IdP 的 claim 映射到 Boundary 的标准 claim(sub/name/email),格式 from=to;例如 email=name 让显示名用邮箱 |
-allowed-audience |
可选;设置后校验 IdP 返回的 aud,通常填 client ID |
-idp-ca-cert |
Authentik 使用私有 CA 时,把 CA 证书交给 Boundary 校验 |
-client-secret env://VAR 会被当成字面字符串,导致 OIDC 回调报 invalid_client。要么在 shell 里先读入变量再传值(-client-secret "$OIDC_CLIENT_SECRET"),要么创建后用实际值 update。不要把这个值写进 shell history。读取回调地址:
boundary auth-methods read -id amoidc_xxxxxxxxxx -token env://TOKEN -format json \
| jq -r '.item.attributes.callback_url'
# https://boundary.example.com/v1/auth-methods/oidc:authenticate:callback
把它填到 Authentik Provider 的 Redirect URI。两边必须逐字符一致。
激活并设为 primary
创建出来的 OIDC 方法是 inactive,先激活:
boundary auth-methods change-state oidc \
-id amoidc_xxxxxxxxxx \
-state active-public \
-token env://TOKEN
active-public 会出现在登录页;active-private 只对已认证用户可见,不能用来做首次登录。
再把它设为所在 Scope 的 primary:
boundary scopes update \
-id o_xxxxxxxxxx \
-primary-auth-method-id amoidc_xxxxxxxxxx \
-token env://TOKEN
每个 Scope 只能有一个 primary。如果同时有密码和 OIDC 两种登录方式,把 OIDC 设为 primary 后,密码方法仍可用于已有用户登录,但新 OIDC 用户只能由 primary 方法自动创建。
如果没有设置 primary,OIDC 同意后会看到:
user not found for account acctoidc_xxx and auth method is not primary
for the scope so refusing to auto-create user
这不是 Authentik 配置错了,而是 Boundary 的自动建用户策略。要么设 primary,要么先手动创建 User 并把 OIDC Account 关联进去。
实测:用 Authentik 跑通完整 OIDC 登录
实验环境的 Authentik 2026.8.5 跑在 http://127.0.0.1:9000。在 Authentik 里创建了 OAuth2/OpenID Provider HashiCorp Boundary 和 Application hashicorp-boundary,Client ID 为 boundary,Redirect URI 是 Boundary 的回调地址;测试用户 [email protected] 属于 boundary-users 组。
Boundary 侧创建 authentik-oidc 方法:
- issuer:
http://127.0.0.1:9000/application/o/hashicorp-boundary/ - claims scopes:
email、profile - account claim maps:
email=name - 状态:
active-public - 设为 global scope 的 primary
登录页会出现 authentik-oidc 方法:

点击后 Boundary 打开 Authentik 登录窗口:

输入用户名/密码并完成授权后,回调到 Boundary;首次登录自动创建 [email protected] 的 Account/User,并进入管理后台:

这次实测验证了:
- Authentik Provider/Application 的 Authorization Code 流程
- Boundary 回调地址、issuer、client ID/secret 的匹配
claims-scopes email/profile能拿到邮箱和显示名account-claim-maps email=name把显示名映射为邮箱active-public后登录页出现 OIDC 入口primary设置后首次 OIDC 登录能自动创建 User- 回调地址使用字面量
oidc,不是 Auth Method ID
如果不用 Authentik 界面而是直接调 API 创建 Provider,grant_types 默认是空列表。此时 OIDC 授权请求会失败,Boundary 侧只看到 invalid_request: The request is otherwise malformed,Authentik 日志里则是 Invalid grant_type for provider。
创建 Provider 时要显式设置:
"grant_types": ["authorization_code", "refresh_token"]
用界面创建时,Grant types 里勾选 Authorization Code 和 Refresh Token 即可。这是我在 API 创建 Provider 时实际踩到的坑。
用 CLI 登录
boundary authenticate oidc \
-auth-method-id amoidc_xxxxxxxxxx \
-keyring-type none
CLI 会打印一个登录 URL 并等待浏览器完成 OIDC;服务器上没有浏览器时,把 URL 复制到本机打开即可。成功后会在当前终端拿到 Boundary token。
组映射:Managed Groups
OIDC 用户自动创建后,还需要把它映射到 Role。Boundary 的 managed group 可以根据 IdP 的 claims 自动维护组成员:
boundary managed-groups create oidc \
-auth-method-id amoidc_xxxxxxxxxx \
-name boundary-users \
-description "OIDC users" \
-filter '"boundary-users" in "/userinfo/groups"' \
-token env://TOKEN
过滤器使用 JSON Pointer:
/userinfo/groups对应 UserInfo 响应里的groups/token/groups对应 ID Token 里的groups- 过滤器里的组名要和 IdP 实际返回的组名一致,区分大小写
managed group 机制我在临时测试 IdP 上验证过:用户登录后 member_ids 里出现了对应的 Account。换成 Authentik 时,需要先按上面的 Scope Mapping 把 groups claim 加进去,再用同样的过滤器;这一步没有在 Authentik 上单独验证。之后把 managed group 加为 Role 的 principal 即可:
boundary roles add-principals \
-id r_xxxxxxxxxx \
-principal mgoidc_xxxxxxxxxx \
-token env://TOKEN
profile scope 不一定包含组信息。按前面的 Scope Mapping 增加 groups,并在 Boundary 的 -claims-scopes 里请求 groups,否则 /userinfo/groups 会是空,managed group 永远匹配不到。OIDC 排查清单
1. invalid_client / Invalid client credentials
先检查 Boundary 和 Authentik 的 client secret 是否一致。实测 -client-secret env://VAR 不会解析,必须传实际值;创建后用 auth-methods update oidc -client-secret "$SECRET" 修正。
2. auth method is not primary
执行 boundary scopes update -id <scope> -primary-auth-method-id <oidc-auth-method-id>。
3. 登录页看不到 OIDC 方法
检查 auth-methods read 里的 state 是否为 active-public。inactive 和 active-private 都不会出现在首次登录页。
4. Redirect URI mismatch
IdP 的 Redirect URI 必须是 https://<api-url-prefix>/v1/auth-methods/oidc:authenticate:callback,路径里是 oidc,不是 amoidc_...。
5. issuer 不匹配
Authentik 的 issuer 通常以 /application/o/<slug>/ 结尾,末尾斜杠不能少;以 discovery 文档里的 issuer 为准。
6. 私有 CA 导致 Boundary 连不上 Authentik
Boundary Controller 需要信任 Authentik 的 CA。用 -idp-ca-cert /path/to/ca.pem 指定,或者在系统信任链里安装 Homelab Root CA。不要用 -tls-insecure 绕过。
7. 用户名是一串 hash
说明只拿到了 sub。增加 -claims-scopes email -claims-scopes profile,再用 -account-claim-maps 把 email 或 preferred_username 映射到 name。
8. groups 为空
Authentik 需要自定义 groups scope mapping,Boundary 需要 -claims-scopes groups;两项缺一不可。
运维
日常检查
# 服务状态
systemctl is-active vault-boundary boundary-controller boundary-worker
# Vault 密封状态
VAULT_ADDR=http://127.0.0.1:8202 vault status
# Boundary 会话
export TOKEN="$(sudo cat /root/boundary-token)"
boundary sessions list -scope-id p_xxxxxxxxxx -token env://TOKEN
# 最近日志
journalctl -u boundary-controller -n 50 --no-pager
journalctl -u boundary-worker -n 50 --no-pager
备份
Boundary 元数据在 PostgreSQL,备份方式和普通 PostgreSQL 一样:
docker exec boundary-postgres pg_dump -U boundary -d boundary -F t \
> /tmp/boundary-backup.tar
实测这份备份约 9 MB。恢复到临时库验证:
docker exec boundary-postgres psql -U boundary -d boundary \
-c "DROP DATABASE IF EXISTS boundary_restore_test;" \
-c "CREATE DATABASE boundary_restore_test;"
docker cp /tmp/boundary-backup.tar boundary-postgres:/tmp/backup.tar
docker exec boundary-postgres pg_restore -U boundary \
-d boundary_restore_test --no-owner --no-privileges /tmp/backup.tar
docker exec boundary-postgres psql -U boundary -d boundary_restore_test \
-tAc "select (select count(*) from auth_account), (select count(*) from iam_user), (select count(*) from target);"
# 2|5|2
docker exec boundary-postgres psql -U boundary -d boundary \
-c "DROP DATABASE boundary_restore_test;"
Vault 用 Raft snapshot:
VAULT_ADDR=http://127.0.0.1:8202 VAULT_TOKEN="$ROOT" \
vault operator raft snapshot save /tmp/vault-boundary.snap
ls -lh /tmp/vault-boundary.snap
# 23K
Vault 的 unseal key、root token 和 snapshot 要分开保存;不要把 unseal key 和 snapshot 放在同一块磁盘上。
升级
升级前先备份 Boundary 数据库和 Vault snapshot,并停止 Controller/Worker。Boundary 的二进制升级通常包括替换 /usr/local/bin/boundary、执行数据库迁移、重启服务;具体版本要求以官方 Release Notes 为准。本文没有做跨版本升级实测,不建议在生产环境直接照搬实验命令。
故障排查
1. Boundary 启动报 Vault KMS 认证失败
确认 VAULT_ADDR、VAULT_TOKEN 已经进入 Boundary 进程环境。systemd 的 EnvironmentFile 顺序很重要;如果先加载了静态 token 文件、又加载了 Vault Agent 渲染的文件,后加载的会覆盖前者。用 systemctl show boundary-controller -p Environment 检查实际环境(注意不要泄露 token)。
2. Worker 启动报 name 缺失
KMS 认证模式必须设置 worker { name = "..." };auth_storage_path 是 PKI 模式用的,不能和 KMS 混用。
3. 登录成功但看不到 Target
检查 Role 的 Grant、Principal 和 Scope。Grant 只授予了 list 但没有 authorize-session 时,能看到 Target 但连不上;Role 建在 Org 而不是 Project 时,权限范围也不同。
4. boundary connect ssh 报 hostname contains invalid characters
OSS + TCP Target 的直接 IP 场景下常见。改用 boundary connect 获取本地端口,再运行系统 ssh。
5. OSS 版创建 SSH Target 失败
OSS 只支持 tcp Target。SSH Target、会话录制和企业级凭据注入需要 Enterprise/HCP。
6. Vault 重启后 Boundary 连不上
Vault 默认重启后是 sealed 状态,需要重新 unseal。生产环境要把 unseal 流程自动化或使用自动 unseal(云 KMS/HSM),否则 Boundary 会在 Vault sealed 期间无法创建新会话。
7. Boundary 初始化凭据丢失
boundary database init 输出的管理员登录名和密码只显示一次。丢失后可以尝试 recovery KMS 流程,或者从备份恢复数据库;没有 recovery 配置时只能重建。初始化输出要立刻保存到 600 权限的文件。
参考
如果你觉得这篇文章对你有所帮助,欢迎赞赏~
赞赏