Canton 开发者文档 / 全局同步器

完整文档页面（中文翻译）。文末附有来源说明。

阅读英文版

global-synchronizerdeploymentcommunity-keycloak-config

社区 Keycloak 配置

Canton 验证者 Keycloak 认证配置指南（社区）。

社区贡献的 Canton 验证器端到端 Keycloak 配置指南

This section features solutions shared by community members. While they haven't been formally tested by the Splice maintainers, users are encouraged to verify the information independently. Contributions to enhance accuracy and completeness are always welcome.

要部署具有 Keycloak 身份验证的验证器节点，请按照以下详细配置步骤操作。本指南提供了有关将 Keycloak 设置为验证者的 OIDC 提供商的全面说明，包括 Canton 网络部署所需的所有自定义设置。

有关其他身份验证提供程序和配置详细信息，请参阅配置身份验证。

先决条件

在继续配置之前，请确保您拥有：

  • 具有管理访问权限的正在运行的 Keycloak 实例
  • 管理控制台访问您的 Keycloak 部署
  • 配置以下主机名：
    • 验证器 API 基本 URL：https://validator-api.your-domain.example/api
    • 钱包界面：https://wallet.your-domain.example *中枢神经系统用户界面：https://cns.your-domain.example
  • Canton 网络为您分配的 PARTY_HINT 标识符

领域配置

  1. 为您的 Canton 验证器创建领域。
    1. 导航到 管理控制台 → 管理领域 → 创建领域。
    2. 将 领域名称 设置为 canton（或您的环境特定名称）。
    3. 单击“创建”以初始化领域。
  2. 配置离线访问和刷新令牌的会话设置。
    1. 导航到 领域设置 → 会话。
    2. 配置以下设置：
      • 将 离线会话最大限制 设置为 ON
      • 将 离线会话最大值 设置为 5,184,000 秒（60 天；根据需要调整）
      • 将 离线会话空闲超时 设置为 2,592,000 秒（30 天；根据需要调整）
    3. 单击“保存”应用更改。

客户端范围设置

  1. 创建 daml_ledger_api 客户端范围。

    1. 导航到 客户端范围 → 创建。

    2. 配置基本设置：

      • 姓名：daml_ledger_api
      • 协议：OpenID Connect
      • 类型：Default
      • 在同意屏幕上显示：OFF
      • 包含在代币范围内：OFF

    3. 单击保存。

    4. 将所需的映射器添加到daml_ledger_api：

      用户客户端角色映射器：

      • 导航到 daml_ledger_api → 映射器 → 创建
      • 将映射器类型设置为User Client Role
      • 将名称设置为daml_ledger_api_scope
      • 设置添加访问令牌为ON
      • 将添加到ID令牌、添加到用户信息、添加到令牌内省和多值设置为OFF
      • 点击保存

      受众映射器：

      • 导航到 daml_ledger_api → 映射器 → 创建
      • 将映射器类型设置为Audience
      • 将名称设置为audience
      • 将 包含的自定义受众 设置为 https://canton.network.global
      • 将添加到访问令牌和添加到令牌内省设置为ON
      • 将添加到ID令牌和添加到轻量级访问令牌设置为OFF
      • 点击保存
  2. 创建openid客户端范围。

    1. 导航到 客户端范围 → 创建。

    2. 配置设置：

      • 姓名：openid
      • 协议：OpenID Connect
      • 类型：Default
      • 在同意屏幕上显示：OFF
      • 包含在代币范围内：ON

    3. 单击保存。4. 将所需的映射器添加到openid：

      验证器 API 受众映射器：

      • 导航到 openid → 映射器 → 创建
      • 将 映射器类型 设置为 Audience
      • 将名称设置为aud
      • 将 包含的自定义受众 设置为 https://validator-api.your-domain.example/api
      • 将添加到访问令牌和添加到令牌内省设置为ON
      • 将添加到ID令牌和添加到轻量级访问令牌设置为OFF
      • 点击保存

      主题映射器：

      • 导航到 openid → 映射器 → 创建
      • 将 映射器类型 设置为 Subject (sub)
      • 将名称设置为sub
      • 将添加到访问令牌和添加到令牌内省设置为ON
      • 将添加到轻量级访问令牌设置为OFF
      • 点击保存

客户端配置

  1. 创建账本API资源客户端。
    1. 导航到 客户端 → 创建客户端。
    2. 将客户端类型设置为OpenID Connect，将客户端ID设置为ledger-api。
    3. 单击下一步。
    4. 在功能配置中，将所有开关设置为OFF。
    5. 单击下一步。
    6. 将所有 登录设置 字段留空，然后单击 保存。
    7. 添加客户端范围：导航到 客户端范围 → 添加客户端范围 → 选择 daml_ledger_api → 添加为“默认”。
  2. 创建验证器应用程序后端服务帐户客户端。
    1. 导航到 客户端 → 创建客户端。
    2. 将客户端类型设置为OpenID Connect，将客户端ID设置为validator-app-backend。
    3. 单击下一步。
    4. 在能力配置中：
      • 将客户端身份验证设置为ON
      • 将服务帐户设置为ON
      • 将所有其他选项设置为OFF
    5. 单击下一步。
    6. 将登录设置字段留空，然后单击保存。
    7. 记录凭据：
      • 从 Credentials 选项卡，复制 Client Secret
      • 从 服务帐户角色选项卡，单击服务帐户用户链接
      • 从浏览器 URL 复制 用户 ID (UUID)（用作 LEDGER_API_ADMIN_USER）
    8. 添加客户端范围：导航到 客户端范围 → 添加客户端范围 → 选择 daml_ledger_api → 添加为“默认”。
  3. 创建钱包 Web UI 公共客户端。
    1. 导航到 客户端 → 创建客户端。
    2. 将客户端类型设置为OpenID Connect，将客户端ID设置为wallet-web-ui。
    3. 单击下一步。
    4. 在能力配置中：
      • 将标准流量设置为ON
      • 将所有其他选项设置为OFF
    5. 单击下一步。
    6. 配置登录设置：
      • 有效的重定向 URI： https://wallet.your-domain.example/*
      • 有效的注销后重定向 URI： https://wallet.your-domain.example
      • 网络来源：https://wallet.your-domain.example
    7. 单击“保存”。
    8. 配置客户端范围：
      • 添加 openid 和 daml_ledger_api 作为 “默认”
      • 添加 offline_access 作为 “可选”（如果需要）
  4. 创建 CNS UI 公共客户端。
    1. 按照与钱包 Web UI 相同的流程进行以下修改：
      • 将 客户端 ID 设置为 cns-ui
      • 将 有效的重定向 URI 设置为 https://cns.your-domain.example/*
      • 将 有效的注销后重定向 URI 设置为 https://cns.your-domain.example
      • 将 Web 来源 设置为 https://cns.your-domain.example
      • 配置与 wallet-web-ui 相同的客户端范围

用户管理9. 创建运营商钱包用户。

  1. 导航至 用户 → 添加用户。 2.配置用户：
    • 将 用户名 设置为您的确切 PARTY_HINT 值
    • 将 用户启用 设置为 ON
  2. 单击保存。
  3. 设置永久密码：导航至 凭据选项卡 → 设置密码，并将 临时 设置为 OFF。
  4. 从浏览器 URL 复制 用户 ID (UUID)（用作 WALLET_ADMIN_USER）。
The username must exactly match your assigned `PARTY_HINT` identifier from the Canton network.

应用程序配置

使用以下与 Keycloak 相关的环境变量配置验证器应用程序：

Keycloak 领域端点

AUTH_URL=https://your-keycloak-host/realms/canton AUTH_WELLKNOWN_URL=https://your-keycloak-host/realms/canton/.well-known/openid-configuration AUTH_JWKS_URL=https://your-keycloak-host/realms/canton/protocol/openid-connect/certs

后端客户端凭据

VALIDATOR_AUTH_CLIENT_ID=validator-app-backend 验证者_AUTH_CLIENT_SECRET=替换_WITH_CLIENT_SECRET

用户身份 UUID（来自 Keycloak 用户 URL）

LEDGER_API_ADMIN_USER=替换_WITH_SERVICE_ACCOUNT_USER_UUID 钱包_ADMIN_USER=替换_WITH_OPERATOR_USER_UUID

OAuth 范围和受众

LEDGER_API_AUTH_SCOPE=daml_ledger_api LEDGER_API_AUTH_AUDIENCE=https://canton.network.global VALIDATOR_AUTH_AUDIENCE=https://validator-api.your-domain.example/api

UI 客户端 ID

WALLET_UI_CLIENT_ID=wallet-web-ui ANS_UI_CLIENT_ID=cns-ui

验证和测试

  1. 通过测试后端客户端凭据流程来验证您的配置：

    curl -X POST “https://your-keycloak-host/realms/canton/protocol/openid-connect/token”
    -H“内容类型：application/x-www-form-urlencoded”
    -d “grant_type=client_credentials”
    -d “client_id=validator-app-backend”
    -d“客户端_秘密=您的_客户端_秘密”

    解码返回的access_token并验证其包含：

    • aud: ["https://canton.network.global"]
    • scope: "daml_ledger_api"

配置注意事项

* **User Identifiers**: Both `LEDGER_API_ADMIN_USER` and `WALLET_ADMIN_USER` must be UUIDs from Keycloak URLs, not usernames * **Mapper Configuration**: The `daml_ledger_api` scope uses both User Client Role and Audience mappers for comprehensive authorization * **Token Audiences**: UI tokens contain both standard OpenID Connect claims and your validator API audience * **Username Matching**: The wallet admin user's username must exactly match your `PARTY_HINT` value

故障排除

如果您遇到身份验证问题：

  • 验证所有受众映射是否已正确配置
  • 确保客户端范围被正确分配为“默认”类型
  • 确认用户 UUID 是从 Keycloak URL 复制的，而不是使用用户名
  • 检查会话超时值是否适合您的用例

本文由 CC Privacy Club 根据 Canton Network 官方文档（CC-BY-4.0）整理翻译，仅供学习；实现细节以官方最新版本为准。