VCF9.1 PAIS私有AI服务：Keycloak配置OIDC‑PKCE完整实操解析

VCF Private AI Services（PAIS私有AI服务）强制要求IdP支持带PKCE(S256)的授权码OIDC流程；本文基于VIS Appliance内置Keycloak，给出端到端完整配置；对比旧版PAIS9.0使用Authentik的经验；包含Keycloak Realm、OIDC客户端、Client‑Scope映射groups与audience声明；输出PAIS的YAML身份配置片段；同时提供PKCE流程Shell调试脚本validate_keycloak_pkce_api_token_for_pais.sh，获取access_token调用PAIS OpenAI兼容模型接口；大量坑点集中在Redirect‑URI末尾斜杠、Web‑Origins不能带斜杠、Token声明映射缺失。

有VMware全系列产品官方资源和定制版资源需求的可以移步：

VMware全系列产品官方镜像和定制版下载汇总(更新到2026年8月）

时间：2026-08-01

查看

VCF‑PAIS必须使用Authorization Code+PKCE(S256) OIDC流程；Keycloak客户端开启Standard flow+Direct access grants，PKCE方法强制S256；Redirect‑URI末尾带斜杠，Web‑Origins不能带斜杠；Client Scope必须添加Group‑Membership(groups)与Audience映射；提取Issuer‑URL要剔除.well‑known之后路径；配置authorizedGroups做访问控制；没有图形界面拿Token，需要PKCE shell脚本完成授权码交换拿到access_token调用PAIS模型endpoint；VIS内置Keycloak适合PoC实验室验证。

一、环境前置条件

二、Step‑by‑Step Keycloak配置步骤

步骤1：登录Keycloak管理UI，切换目标Realm

1. 访问Keycloak管理后台；点击Manage realms，选择或新建用于PAIS的Realm（示例：VCF）。

步骤2：新建OIDC客户端（核心参数）

1. 左侧菜单选择Clients → Create Client；填写Client‑ID、Name；可选Always display in UI。

2. Authentication Flow：勾选Standard flow（必须）；勾选Direct access grants（调试用）。

3. PKCE Method 设置为 S256（PAIS强制要求）。

4. Valid Redirect URL：填写PAIS FQDN，末尾必须带斜杠，示例 https://pais.vcf.lab/。

5. Web Origins：填写相同PAIS FQDN，末尾禁止斜杠，示例 https://pais.vcf.lab。

6. 保存客户端配置。

⚠️高频坑：Redirect‑URI / Web‑Origins斜杠处理错误，会直接报回调不匹配。

步骤3：Client Scopes 添加两组Mapper映射（极易遗漏）

1. 进入刚刚新建客户端 → Client Scopes标签页；打开自动生成的 <clientid>-dedicated专属客户端作用域。

2. Add Mapper by Configuration → 选择 Group Membership；自定义名称；Token Claim Name填 groups；关闭Full group path。
   作用：把用户所属组放到access‑token的groups声明，供PAIS做authorizedGroups鉴权。

3. Add Mapper by Configuration → 选择 Audience；自定义名称；Included Client Audience选择本PAIS的Client‑ID；开启Add to access token。
   作用：填充aud受众声明，PAIS校验token受众合法性。

步骤4：创建用户组与测试账号

1. 左侧Groups，新建授权组示例：vcf‑admins；

2. Users页面新建测试用户，把用户加入vcf‑admins组；该组成员才有访问PAIS模型接口权限。

三、PAIS YAML身份配置片段

auth:
 providers:
 - name: oidc
  oidc:
   authorizedGroups:
   - vcf‑admins
   clientId: pais
   groupsClaim: groups
   issuerUrl: https://vis.vcf.lab:9444/realms/VCF
   scope:
   - openid
   - profile
   - offline_access

• 获取IssuerUrl方法：Realm settings页面，鼠标悬浮“OpenID Endpoint Configuration”链接，把链接中/.well‑known/*及后面全部删除，剩余即为issuerUrl。

• authorizedGroups：只允许属于vcf‑admins组的用户访问PAIS服务。

四、调用PAIS模型Endpoint：获取Bearer access_token

Keycloak管理UI没有图形界面直接获取API access_token；需要使用配套Shell脚本 validate_keycloak_pkce_api_token_for_pais.sh完成完整PKCE授权码流程。

脚本顶部需要修改变量

KEYCLOAK_HOST="https://vis.vcf.lab:9444"
REALM="VCF"
CLIENT_ID="pais"
REDIRECT_URI="https://pais.vcf.lab/"
SCOPES="openid profile email"

1. 运行脚本，脚本输出授权URL；复制在浏览器打开；

2. 使用已经加入vcf‑admins组的账号完成Keycloak登录；浏览器跳转回调页面；复制浏览器完整URL；

3. 粘贴回Shell脚本；脚本内部完成PKCE code‑verifier交换，输出access_token；

4. 导出环境变量 export PAIS_API_TOKEN="拿到的access_token"。

PAIS OpenAI兼容接口curl调用示例

curl -k https://pais.vcf.lab/api/v1/compatibility/openai/v1/completions \
 -H "Content‑Type: application/json" \
 -H "Authorization: Bearer $PAIS_API_TOKEN" \
 -d '{
 "model": "gpt‑oss‑20b",
 "prompt": "What is the capital of the United States?",
 "max_tokens": 200,
 "temperature": 0
 }'

五、关键故障排查清单

六、高频问答

Q1：PAIS可以使用Client Credentials客户端模式吗？ A：PAIS要求Authorization Code + PKCE(S256)；客户端凭证模式不适用本身份流，仅用于特殊后台集成。

Q2：Direct access grants开启是生产必须吗？ A：生产环境可以关闭；仅用于实验室调试拿token；脚本PKCE流程本身不需要该开关。

Q3：VIS Appliance内置Keycloak能不能直接上生产？ A：文章用于PoC与实验室；生产环境建议独立高可用Keycloak集群。

Q4：groups声明拿不到组信息？ A：注意修改的是dedicated专属client‑scope，不要修改全局默认scope。

Q5：access_token过期怎么办？ A：scope携带offline_access，脚本可以拿到refresh_token用于刷新access_token。

全文总结

VCF9.1 PAIS私有AI服务强制使用Authorization Code+PKCE‑S256的OIDC身份流；基于VIS Appliance内置Keycloak做PoC测试时，客户端必须开启Standard flow，PKCE方法选S256；严格区分Redirect‑URI（带末尾斜杠）和Web‑Origins（不带斜杠）；在dedicated Client Scope配置Group‑Membership输出groups声明、Audience映射受众声明；提取issuerUrl需要剔除.well‑known路径；YAML配置authorizedGroups做访问控制；Keycloak无图形化API令牌获取入口，依靠PKCE shell脚本完成授权码交换拿到access_token，调用PAIS兼容OpenAI的模型推理Endpoint；大量故障来源于斜杠处理错误、Mapper映射遗漏，生产环境不建议直接使用VIS内置Keycloak。