目录

Homelab 零信任访问:HashiCorp Boundary + Vault 实践

Boundary 0.21 + Vault 2.2:Transit KMS、OIDC 登录与按身份授权的 SSH 访问

我以前访问 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,Worker 9202
  • 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 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 ...
为什么不用 1.21
网上不少 Boundary 文章还停留在 Vault 1.x。2026 年的 Vault 已经发布到 2.2.2,配置格式和 Transit 用法基本兼容;本文按实际安装的 2.2.2 写。

实验环境为了少一层证书,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 离线保存。

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
生产环境用 AppRole + Vault Agent
本文为了聚焦 Boundary,直接给 Controller/Worker 一个周期 token,并通过 systemd 的 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:

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

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 渲染的值>
# /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"
}
实验环境是 HTTP
实验环境的 Boundary API/Cluster 监听是 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)。

# /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"
}
Worker 的 name 不能省
KMS 认证模式下 Worker 必须设置 name,否则启动会报错。auth_storage_path 也不能和 KMS 认证一起用,它属于 PKI 认证模式。

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 页面会显示它的版本、地址和最近心跳:

Boundary Workers 页面
Boundary Worker 已注册,版本 v0.21.3,地址 127.0.0.1:9202

Controller 的 UI 默认就在 9200 端口:

Boundary 登录页
Boundary 登录页:选择全局密码认证方法

Boundary 管理后台
Boundary 管理后台:Global Level 的 Orgs

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 输出:

Vault、Boundary 与 Target 状态
Vault、Boundary 服务和 lab-ssh Target 的实测状态

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。一个典型的流程是:

  1. 在 Org 下创建 Project
  2. 在 Org 下创建密码或 OIDC Auth Method
  3. 创建 User,并把 Account 关联到 User
  4. 在 Project 下创建 Role,加 Target 授权和 Principal
  5. 用户登录后,只能看到/连接被授权的 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。

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 内生效。

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
OSS 版不支持 SSH Target 和会话录制
虽然 CLI 里有 boundary targets create ssh,OSS Controller 会返回 Unknown type provided。SSH Target 的自动凭据注入和会话录制需要 Enterprise 或 HCP Boundary。OSS 里用 TCP Target + boundary connect + 客户端 SSH 即可,但审计只能依赖客户端和 Target 侧的日志。
connect ssh 的小坑
在 OSS + TCP Target 的场景里,直接 boundary connect ssh -target-id ... 对 127.0.0.1 这类直接地址可能报 hostname contains invalid characters。先用 boundary connect 拿到本地端口,再用系统 ssh 连接,行为更可控,也方便指定私钥和 known_hosts 策略。

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"' \
  ...

前面用密码认证跑通了 Boundary 的核心链路。实际使用中更希望直接接 Authentik,让用户用统一身份登录。Boundary 的 OIDC 配置有几个顺序和字段容易踩坑,下面按实际流程拆开。

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 里创建一个 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(只做登录可以先不加,等要映射组时再补):

  1. 打开 Customization -> Property Mappings -> Create -> Scope Mapping
  2. Name 填 groups,Scope name 填 groups
  3. Expression:
return {
    "groups": [group.name for group in request.user.ak_groups.all()],
}
  1. 回到 Provider 的 Advanced protocol settings,把这个 groups scope 加到 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 里填的完全一致,尤其注意末尾斜杠。

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://
实测 -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。两边必须逐字符一致。

创建出来的 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 的真实报错

如果没有设置 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 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 登录页出现 authentik-oidc 认证方法

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

Authentik 登录页
Authentik 2026.8.5 登录页,登录后继续到 HashiCorp Boundary

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

Boundary OIDC 登录成功
Authentik OIDC 登录成功,右上角显示 [email protected]

这次实测验证了:

  • 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
API 创建 Authentik Provider 时 grant_types 默认为空

如果不用 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 时实际踩到的坑。

boundary authenticate oidc \
  -auth-method-id amoidc_xxxxxxxxxx \
  -keyring-type none

CLI 会打印一个登录 URL 并等待浏览器完成 OIDC;服务器上没有浏览器时,把 URL 复制到本机打开即可。成功后会在当前终端拿到 Boundary token。

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
Authentik 的 groups claim 要自己加
Authentik 默认的 profile scope 不一定包含组信息。按前面的 Scope Mapping 增加 groups,并在 Boundary 的 -claims-scopes 里请求 groups,否则 /userinfo/groups 会是空,managed group 永远匹配不到。

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 权限的文件。