第 3 章 使用红帽构建 Keycloak (RHBK)进行身份验证

流程

1. 要允许 Developer Hub 使用 RHBK 进行身份验证，请完成 RHBK 中的步骤，创建 realm 和用户，并保护第一个应用程序:

   1. 使用现有域，或使用不同的名称（如 < my_ realm > ）创建一个 域。为下一步保存值：

      • RHBK 域基本 URL，例如： < your_rhbk_URL> /realms/ <your_realm>。

   2. 要在 RHBK 中注册您的 Developer Hub，请在创建域中注册 第一个应用程序，使用以下内容保护第一个应用程序 ：

      1. 客户端 ID ：不同的客户端 ID，如 < RHDH>。
      2. 有效的重定向 URI ：设置为 OIDC 处理程序 URL： https:// <my_developer_hub_domain&gt; /api/auth/oidc/handler/frame。
      3. 导航到 Credentials 选项卡，再复制 Client secret。

      4. 保存下一步的值：

         • 客户端 ID
         • Client Secret
   3. 要准备验证步骤，请在同一域中获取现有用户 或创建用户的凭证 信息。保存验证步骤的用户凭证信息。

2. 要将 RHSSO 凭证添加到 Developer Hub，请将以下键/值对添加到 Developer Hub secret 中。您可以使用其相应的环境变量名称在 Developer Hub 配置文件中使用这些 secret。

   AUTHENTICATION_OIDC_CLIENT_ID

   输入保存 的客户端 ID。

   AUTHENTICATION_OIDC_CLIENT_SECRET

   输入保存 的客户端 Secret。

   AUTHENTICATION_OIDC_METADATA_URL

   输入保存的 RHBK 域基础 URL。

3. 启用 Keycloak 组织插件(backstage-community-plugin-catalog-backend-module-keycloak-dynamic)。该插件命名为 RHBK 上游项目。此插件将 RHBK 用户和组放入 Developer Hub 软件目录。

   dynamic-plugins.yaml 文件片段

   plugins:
     - package: './dynamic-plugins/dist/backstage-community-plugin-catalog-backend-module-keycloak-dynamic'
       disabled: false

4. 要将 RHBK 用户和组置备到 Developer Hub 软件目录，请将 catalog.providers.keycloakOrg 部分添加到自定义 Developer Hub app-config.yaml 配置文件中：

   1. 添加必填字段：

      带有强制 keycloakOrg 字段的 app-config.yaml 片段

      catalog:
        providers:
          keycloakOrg:
            default:
              baseUrl: ${AUTHENTICATION_OIDC_METADATA_URL}
              clientId: ${AUTHENTICATION_OIDC_CLIENT_ID}
              clientSecret: ${AUTHENTICATION_OIDC_CLIENT_SECRET}
              realm: master
              loginRealm: master

      baseUrl

      输入您的 RHBK 服务器 URL，在启用 RHBK 身份验证时定义。

      clientId

      在 RHBK 中启用身份验证时，在 RHBK 中输入您的 Developer Hub 应用程序客户端 ID。???

      clientSecret

      在 RHBK 中启用身份验证时，在 RHBK 中输入您的 Developer Hub 应用程序客户端 secret。???

      realm

      输入 realm 名称以置备用户，如 master。

      loginRealm

      输入 realm 名称以验证用户，如 master。

   2. 可选： 考虑添加可选字段：

      userQuerySize

      输入用户数以同时查询。默认值 ：100。

      带有可选 userQuerySize 字段的 app-config.yaml 片段

      catalog:
        providers:
          keycloakOrg:
            default:
              userQuerySize: 100

      groupQuerySize

      输入要同时查询的组数。默认值 ：100。

      带有可选 groupQuerySize 字段的 app-config.yaml 片段

      catalog:
        providers:
          keycloakOrg:
            default:
              groupQuerySize: 100

      schedule.frequency

      输入调度频率。支持代码中使用的 cron、ISO 持续时间和"human 持续时间"。

      带有可选 schedule.frequency 字段的 app-config.yaml 片段

      catalog:
        providers:
          keycloakOrg:
            default:
              schedule:
                frequency: { hours: 1 }

      schedule.timeout

      输入用户置备作业的超时时间。支持代码中使用的 ISO 持续时间和"human duration"。

      带有可选 schedule.timeout 字段的 app-config.yaml 片段

      catalog:
        providers:
          keycloakOrg:
            default:
              schedule:
                timeout: { minutes: 50 }

      schedule.initialDelay

      输入在启动用户置备作业前等待的初始延迟。支持代码中使用的 ISO 持续时间和"human duration"。

      带有可选 schedule.initialDelay 字段的 app-config.yaml 片段

      catalog:
        providers:
          keycloakOrg:
            default:
              schedule:
                initialDelay: { seconds: 15}

5. 要在 Developer Hub 自定义配置中设置 RHBK 身份验证供应商，请编辑自定义 Developer Hub ConfigMap，如 app-config-rhdh，并将以下行添加到 app-config.yaml 内容：

   1. 添加必填字段：

      app-config.yaml 片段带有强制字段，以启用 RHBK 身份验证

      auth:
        environment: production
        providers:
          oidc:
            production:
              metadataUrl: ${AUTHENTICATION_OIDC_METADATA_URL}
              clientId: ${AUTHENTICATION_OIDC_CLIENT_ID}
              clientSecret: ${AUTHENTICATION_OIDC_CLIENT_SECRET}
              prompt: auto
      signInPage: oidc

      环境：production

      将环境标记为 production，以在 Developer Hub 主页中隐藏 Guest 登录。

      metadataUrl, clientId, clientSecret

      使用您的 secret 配置 OIDC 供应商。

      sigInPage: oidc

      将 OIDC 供应商作为默认登录供应商启用。

      提示： auto

      要允许身份提供程序自动决定是否提示输入凭证，或者在存在活跃的 RHSSO 会话时绕过登录重定向。

      注意

      如果没有设置 prompt: auto，则身份提供程序默认为 prompt: none，这假设您已经登录，并在没有活跃会话的情况下拒绝登录请求。

   2. 可选： 考虑添加可选字段：

      callbackUrl

      RHBK 回调 URL。

      带有可选 callbackURL 字段的 app-config.yaml 片段

      auth:
        providers:
          oidc:
            production:
              callbackUrl: ${AUTHENTICATION_OIDC_CALLBACK_URL}

      tokenEndpointAuthMethod

      令牌端点身份验证方法。

      带有可选 tokenEndpointAuthMethod 字段的 app-config.yaml 片段

      auth:
        providers:
          oidc:
            production:
              tokenEndpointAuthMethod: ${AUTHENTICATION_OIDC_TOKEN_ENDPOINT_METHOD}

      tokenSignedResponseAlg

      令牌签名的响应算法。

      带有可选 tokenSignedResponseAlg 字段的 app-config.yaml 片段

      auth:
        providers:
          oidc:
            production:
              tokenSignedResponseAlg: ${AUTHENTICATION_OIDC_SIGNED_RESPONSE_ALG}

      additionalScopes

      输入额外的 RHBK 范围，以便在身份验证流中请求。

      带有可选 additionalScopes 字段的 app-config.yaml 片段

      auth:
        providers:
          oidc:
            production:
              additionalScopes: ${AUTHENTICATION_OIDC_SCOPE}

      signIn

      解析器

      身份验证成功后，中的用户签名必须解析为 Developer Hub 目录中的现有用户。为了更好地为您的用例安全地匹配用户，请考虑配置特定的解析器。

      输入解析器列表以覆盖默认解析器： oidcSubClaimMatchingKeycloakUserId。

      可用值：

      oidcSubClaimMatchingKeycloakUserId

      将用户与 OIDC 中的不可变 sub 参数匹配到 RHBK 用户 ID。考虑将此解析器用于增强安全性。

      emailLocalPartMatchingUserEntityName

      将电子邮件本地部分与用户实体名称匹配。

      emailMatchingUserEntityProfileEmail

      将电子邮件与用户实体配置集电子邮件匹配。

      preferredUsernameMatchingUserEntityName

      将首选用户名与用户实体名称匹配。

      身份验证提供程序尝试每个登录解析器按顺序尝试，直到成功为止，如果没有成功，则失败。

      警告

      在 production 模式中，只配置一个解析器以确保用户被安全地匹配。

      带有可选 解析器 列表的 app-config.yaml 片段

      auth:
        providers:
          oidc:
            production:
              signIn:
                resolvers:
                  - resolver: oidcSubClaimMatchingKeycloakUserId
                  - resolver: preferredUsernameMatchingUserEntityName
                  - resolver: emailMatchingUserEntityProfileEmail
                  - resolver: emailLocalPartMatchingUserEntityName

      dangerouslyAllowSignInWithoutUserInCatalog: true

      配置登录解析器以绕过 Developer Hub 软件目录中的用户置备要求。

      警告

      使用这个选项探索 Developer Hub 功能，但不要在生产环境中使用它。

      带有可选字段的 app-config-rhdh.yaml 片段，允许软件目录中缺少的用户签名

      auth:
        environment: production
        providers:
          oidc:
            production:
              metadataUrl: ${AUTHENTICATION_OIDC_METADATA_URL}
              clientId: ${AUTHENTICATION_OIDC_CLIENT_ID}
              clientSecret: ${AUTHENTICATION_OIDC_CLIENT_SECRET}
              signIn:
                resolvers:
                  - resolver: oidcSubClaimMatchingKeycloakUserID
                    dangerouslyAllowSignInWithoutUserInCatalog: true
      signInPage: oidc

      sessionDuration

      用户会话的寿命。以 ms 库格式输入持续时间（如 '24h'、'2 days'）、ISO 持续时间或 "human duration"，如代码中使用的。

      带有可选 sessionDuration 字段的 app-config-rhdh.yaml 片段

      auth:
        providers:
          github:
            production:
              sessionDuration: { hours: 24 }

      auth

      backstageTokenExpiration

      要从默认值一小时修改 Developer Hub 令牌过期，请注意，这指的是短期加密令牌的有效性，而不是会话持续时间。expiration 值必须在 10 分钟到 24 小时之间设置。

      .app-config.yaml 片段带有可选的 auth.backstageTokenExpiration 字段

      auth:
        backstageTokenExpiration: { minutes: <user_defined_value> }

      安全考虑

      如果因为频繁刷新令牌请求而发出多个有效的刷新令牌，旧的令牌将保持有效，直到它们过期。要增强安全性并防止旧令牌造成潜在的滥用，请在 RHBK 域中启用刷新令牌轮转策略。

      1. 在导航菜单的 Configure 部分中，单击 Realm Settings。
      2. 从 Realm Settings 页面，单击 Tokens 选项卡。
      3. 在 Tokens 选项卡的 Refresh tokens 部分中，将 Revoke Refresh Token 切换到 Enabled 位置。

验证

1. 要验证用户和组置备，请检查控制台日志。

   成功同步示例：

   2025-06-27T16:02:34.647Z catalog info Read 5 Keycloak users and 3 Keycloak groups in 0.4 seconds. Committing... class="KeycloakOrgEntityProvider" taskId="KeycloakOrgEntityProvider:default:refresh" taskInstanceId="db55c34b-46b3-402b-b12f-2fbc48498e82" trace_id="606f80a9ce00d1c86800718c4522f7c6" span_id="7ebc2a254a546e90" trace_flags="01"
   
   2025-06-27T16:02:34.650Z catalog info Committed 5 Keycloak users and 3 Keycloak groups in 0.0 seconds. class="KeycloakOrgEntityProvider" taskId="KeycloakOrgEntityProvider:default:refresh" taskInstanceId="db55c34b-46b3-402b-b12f-2fbc48498e82" trace_id="606f80a9ce00d1c86800718c4522f7c6" span_id="7ebc2a254a546e90" trace_flags="01"

2. 验证 RHBK 用户身份验证：

   1. 进入 Developer Hub 登录页面。
   2. 您的 Developer Hub 签名页面显示 使用 OIDC 的 Sign in，并且 guest 用户登录被禁用。
   3. 使用保存 的用户名和密码 值使用 OIDC 登录。