Alauda Application Services Identity Management E1
  • 简体中文

    • 可扩展性

    Keycloak 基于模块化架构构建，并提供 服务提供商接口（SPIs），使开发人员能够扩展系统的几乎所有方面。本页面概述扩展点以及 Kubernetes 环境中的部署模型。

    目录

    扩展点开发自定义扩展在 Kubernetes 中部署扩展必需：构建自定义镜像版本控制与兼容性

    扩展点

    SPI用途示例用例
    Authenticator登录流程中的自定义身份验证步骤SMS OTP 验证、自定义质询问题
    User Storage连接到自定义用户数据库或 API遗留数据库集成、HR 系统用户查找
    Protocol MapperOIDC 令牌或 SAML 断言中的自定义声明向令牌添加部门、成本中心或授权信息
    Event Listener响应登录和管理事件将事件发送到外部 SIEM、审计日志系统或消息队列
    Required Action用户登录时必须完成的自定义操作接受服务条款、验证电话号码
    Identity Provider自定义外部 Identity Provider 集成连接到专有 SSO 系统
    Theme自定义登录、帐户和电子邮件界面企业品牌、自定义注册表单
    Policy Provider自定义授权策略类型基于地理位置的访问控制、IP 允许列表
    Vault自定义机密存储后端与 HashiCorp Vault 或 AWS Secrets Manager 集成

    开发自定义扩展

    自定义扩展以实现 Keycloak SPI 的 Java 库形式开发。其一般模式如下：

    1. 实现 SPI 的 Provider 接口（运行时逻辑）。
    2. 实现 SPI 的 ProviderFactory 接口（实例化和配置）。
    3. 在 META-INF/services/ 中注册工厂（Java ServiceLoader 机制）。
    4. 打包为 JAR 文件。
    开发人员参考

    完整的 SPI 开发指南维护在上游 Keycloak 文档中。本页面重点介绍 Alauda Application Services Identity Management E1 在 Kubernetes 上特有的部署模型。有关 SPI 实现的详细信息，请参阅上游 Keycloak Server Developer Guide。

    在 Kubernetes 中部署扩展

    Keycloak 26.x（基于 Quarkus）采用了与旧版 Keycloak/RH-SSO（基于 WildFly）根本不同的扩展部署模型。在 Quarkus 模型中，服务器会执行一个构建阶段（kc.sh build），进行提前编译和优化。大多数 SPI 和 provider 必须在此构建阶段存在，才能注册到 Quarkus 运行时中。

    这意味着：

    • 在构建阶段之前放入 /opt/keycloak/providers/ 的 provider JAR 会被编译到优化后的运行时中。
    • 在构建阶段之后添加的 provider JAR（例如在 Pod 启动时通过卷挂载添加）通常不会被 Quarkus 运行时识别，某些 SPI 类型存在有限的例外情况。
    • 没有通用的热部署机制——与基于 WildFly 的 Keycloak 不同，不能简单地将 JAR 放入正在运行的服务器中。

    必需：构建自定义镜像

    构建包含扩展的自定义 Keycloak 镜像：

    基于产品镜像构建自定义镜像

    下面的示例使用上游 Community 镜像，因此可以按原样运行。基于 Community 镜像构建会生成 Community Keycloak™ 构建版本：它不包含 Alauda Application Services Identity Management E1 的基础镜像、打包内容或补丁，也不受本网站支持政策的覆盖。要构建受支持的自定义镜像，请以产品自有的服务器镜像为基础——即已安装的 Operator 用于其实例的镜像引用——并使版本与正在运行的版本保持一致。

    FROM quay.io/keycloak/keycloak:26.7.4 as builder

# Copy custom provider JARs
COPY my-custom-authenticator.jar /opt/keycloak/providers/
COPY my-custom-mapper.jar /opt/keycloak/providers/

# Rebuild Keycloak to include the new providers
# Include all required build-time options here
RUN /opt/keycloak/bin/kc.sh build \
  --health-enabled=true \
  --metrics-enabled=true

FROM quay.io/keycloak/keycloak:26.7.4

COPY --from=builder /opt/keycloak/ /opt/keycloak/

ENTRYPOINT ["/opt/keycloak/bin/kc.sh"]

    更新 Keycloak CR 以使用自定义镜像：

    spec:
  image: my-registry.example.com/keycloak-custom:26.7.4
    构建阶段是必需的

    在 Keycloak 26.x（Quarkus）中，注册新 SPI、身份验证机制或协议映射器的 provider 必须在 kc.sh build 步骤期间存在。跳过构建阶段将导致无法发现或加载 provider。自定义镜像方法是生产部署中唯一受支持的方法。

    自定义镜像中的构建时选项

    使用预构建的自定义镜像时，--health-enabled 和 --metrics-enabled 等构建时选项必须包含在 Dockerfile 中的 kc.sh build 命令内。如果通过 Keycloak CR 中的 additionalOptions 指定这些选项，在使用自定义镜像时会被忽略，因为 Operator 不会重新运行构建步骤。始终在 Dockerfile 中包含所有必要的构建时标志。

    unsupported.podTemplate 不是稳定 API

    某些指南建议使用带有 unsupported.podTemplate 的 init 容器，在运行时挂载 provider JAR。这种方法使用不稳定的 API 字段，不会运行 Quarkus 构建阶段，并且无法保证适用于大多数 provider 类型。请勿将此方法用于生产部署。

    版本控制与兼容性

    • Extension JAR 必须针对部署中使用的相同 Keycloak 版本进行编译。
    • 升级 Keycloak 时，针对新版本重新构建并测试所有自定义 Extension。
    • 使用 Keycloak 内部 API（而非公共 SPI）的 Extension 可能会在次要版本之间出现兼容性问题。