Alauda Application Services Identity Management E1
  • 简体中文

    • 管理客户端

    Keycloak 中的 Client 表示可以请求身份验证的应用或服务。每个客户端都在一个 Realm 中注册，并配置有特定协议（OpenID Connect 或 SAML）。

    目录

    客户端类型创建 OIDC 客户端创建 SAML 客户端客户端 secret 管理查看或重新生成客户端 secret客户端 secret 轮换协议映射器添加协议映射器客户端范围默认范围 vs 可选范围创建客户端范围为客户端分配客户端范围评估范围Service Accounts启用 Service Account使用 Service Account 获取 token客户端策略内置配置文件创建客户端策略

    客户端类型

    类型描述使用场景
    Public Client不能安全地存储 client secret。使用带 PKCE 的 Authorization Code 流。单页应用（SPA）、移动应用
    Confidential Client拥有用于服务器端身份验证的 client secret。后端 Web 应用、微服务
    Bearer-only仅验证 bearer token。不发起登录流程。接收来自其他客户端 token 的 REST API

    创建 OIDC 客户端

    Web Console
    CLI
    1. 登录 Keycloak Admin Console 并选择目标 Realm。
    2. 在左侧导航栏中单击 Clients。
    3. 单击 Create client。
    4. 将 Client type 设置为 OpenID Connect。
    5. 输入 Client ID（例如，my-web-app）。
    6. 单击 Next。
    7. 配置客户端身份验证：
      • 为 confidential 客户端启用 Client authentication。
      • 为 public 客户端禁用该选项。
    8. 选择合适的 Authentication flow 复选框：
      • Standard flow（Authorization Code）— 推荐用于大多数应用。
      • Direct access grants — 适用于直接处理用户凭据的受信任应用。
      • Service accounts roles — 适用于机器到机器身份验证。
    9. 单击 Next。
    10. 设置 Valid redirect URIs（例如，https://my-app.example.com/*）。
    11. 为 CORS 设置 Web origins（例如，https://my-app.example.com）。
    12. 单击 Save。

    创建 SAML 客户端

    Web Console
    1. 在 Admin Console 中，单击 Clients > Create client。
    2. 将 Client type 设置为 SAML。
    3. 输入 Client ID — 这必须与 Service Provider（SP）Entity ID 匹配（例如，https://my-app.example.com/saml/metadata）。
    4. 单击 Save。
    5. 在客户端的 Settings 选项卡中配置以下内容：
    设置描述
    Root URL应用的基础 URL
    Valid post logout redirect URIsSAML 注销后允许重定向到的 URL
    Master SAML Processing URLSP Assertion Consumer Service（ACS）URL
    Name ID Format主体名称格式（例如，email、persistent、transient）
    Sign Assertions启用后对单个 SAML assertion 进行签名
    Sign Documents启用后对整个 SAML response 进行签名
    1. 在 Keys 选项卡中，如果 SP 需要加密 assertion，请配置加密密钥。

    客户端 secret 管理

    对于 confidential 客户端，Keycloak 会自动生成 client secret。

    查看或重新生成客户端 secret

    1. 在 Admin Console 中，转到 Clients 并选择目标客户端。
    2. 单击 Credentials 选项卡。
    3. 当前的 client secret 会显示出来。单击 Regenerate 以创建新的 secret。
    Secret 重新生成

    如果在没有轮换策略的情况下单击 Regenerate，将立即使旧 secret 失效。所有使用旧 secret 的应用都必须先更新，之后才能完成身份验证。

    客户端 secret 轮换

    客户端 secret 轮换是一种单独的、受策略控制的机制，支持无停机时间的 secret 更新。配置轮换后，Keycloak 会在过渡期内同时保留多个活跃 secret。

    轮换 vs 重新生成

    客户端 secret 轮换与单击 Regenerate 不是一回事。轮换由客户端策略控制，该策略定义轮换周期和活跃 secret 数量。没有轮换策略时，重新生成 secret 会立即替换旧 secret，并可能造成中断。若要依赖无停机时间的 secret 更新，请先通过 Client Policies 配置轮换策略。

    使用客户端 secret 轮换：

    1. 创建一个带有 Secret Rotation executor 的客户端策略（参见下方的 Client Policies）。
    2. 配置轮换参数：
      • Secret expiration period — secret 创建后保持有效的时长。
      • Rotated secret expiration period — 旧的（已轮换出）secret 与新 secret 并存时保持有效的时长。
      • Remaining expiration period — 触发轮换所需的最小剩余有效期。
    3. 将该策略应用到目标客户端。
    4. 当策略触发轮换时，Keycloak 会生成新的 secret，同时在配置的宽限期内保持旧 secret 有效。
    5. 在宽限期内更新应用以使用新的 secret。

    协议映射器

    Protocol Mappers 控制为某个客户端签发的 token（OIDC）或 assertion（SAML）中包含哪些 claim。

    添加协议映射器

    1. 在客户端详细信息视图中，单击 Client scopes 选项卡。
    2. 单击专用范围（例如，my-web-app-dedicated）。
    3. 单击 Configure a new mapper 或 Add mapper > By configuration。
    4. 选择映射器类型：
    映射器类型描述
    User Attribute将用户属性映射为 token claim
    User Realm Role在 token 中包含用户的 realm 角色
    User Client Role在 token 中包含用户的客户端角色
    Group Membership在 token 中包含用户的组成员关系
    Audience为 token 添加 audience claim
    Hardcoded Claim将静态值作为 claim 添加
    1. 配置映射器名称、token claim 名称和 claim 类型。
    2. 单击 Save。

    客户端范围

    Client Scopes 定义了可复用的协议映射器和 role scope mapping 集，可以在多个客户端之间共享。

    默认范围 vs 可选范围

    范围类型行为
    Default当客户端请求身份验证时，始终包含在 token 中
    Optional仅在授权请求中通过 scope 参数显式请求时才包含

    创建客户端范围

    1. 在 Admin Console 中，转到 Client scopes。
    2. 单击 Create client scope。
    3. 输入 Name（例如，custom-profile）。
    4. 将 Protocol 设置为 OpenID Connect 或 SAML。
    5. 如果希望范围名称出现在 token 的 scope claim 中，请将 Include in token scope 设置为 On。
    6. 单击 Save。
    7. 添加协议映射器，以定义此范围提供哪些 claim。

    为客户端分配客户端范围

    1. 在客户端详细信息视图中，单击 Client scopes 选项卡。
    2. 单击 Add client scope。
    3. 选择该范围，并将其设置为 Default 或 Optional。
    4. 单击 Add。

    评估范围

    客户端范围视图中的 Evaluate 子选项卡可让你预览给定用户和范围组合下的确切 token 内容，这对于排查 token claim 问题非常有用。

    Service Accounts

    Service Account 允许 confidential 客户端在没有用户上下文的情况下进行身份验证并获取 token（使用 client_credentials 授权）。

    启用 Service Account

    1. 在客户端的 Settings 选项卡中，启用 Service accounts roles。
    2. 单击 Save。
    3. 转到 Service account roles 选项卡。
    4. 分配 realm 或客户端角色，以定义该 service account 可以访问的内容。

    使用 Service Account 获取 token

    curl -s -X POST \
  "https://<keycloak-host>/realms/<realm>/protocol/openid-connect/token" \
  -d "client_id=my-service" \
  -d "client_secret=<client-secret>" \
  -d "grant_type=client_credentials" | jq .

    客户端策略

    Client Policies 允许管理员对客户端配置强制执行规则。策略由 conditions（策略适用的条件）和 profiles（要强制执行的规则）组成。

    内置配置文件

    Keycloak 包含用于常见合规标准的配置文件：

    配置文件描述
    FAPI 1 Baseline强制执行 Financial-grade API Part 1 安全要求
    FAPI 1 Advanced强制执行 Financial-grade API Part 2 安全要求
    FAPI CIBA强制执行 FAPI Client Initiated Backchannel Authentication 要求

    创建客户端策略

    1. 转到 Realm Settings > Client policies 选项卡。
    2. 单击 Create policy。
    3. 输入名称和描述。
    4. 添加条件，以定义策略适用于哪些客户端（例如，按客户端角色、客户端范围或客户端访问类型）。
    5. 添加配置文件，以定义对匹配客户端强制执行的规则。
    6. 单击 Save。