AKHQ集成Azure AD登录配置问题解析与解决方案

背景介绍

在使用AKHQ(一个Kafka管理工具)时，很多团队会选择集成企业级身份认证系统如Azure AD来实现统一登录。本文详细分析了一个典型的Azure AD集成配置问题及其解决方案。

问题现象

用户在配置AKHQ通过Azure AD OIDC登录后，成功输入凭据后系统报错"Field required java.util.map but got string"，导致无法正常显示AKHQ的管理界面。

错误配置分析

原始配置存在两个关键问题：

1. 配置项选择错误：使用了oauth2而非专门的oidc配置项。虽然OAuth2和OIDC有联系，但AKHQ对Azure AD的集成有专门的OIDC配置方式。

2. 数据结构不匹配：groups字段期望接收Map结构，但配置中直接使用了字符串值，导致类型不匹配错误。

正确配置方案

修正后的配置应遵循以下原则：

micronaut:
  security:
    enabled: true
    oauth2:
      callback-uri: "https://AKHQ_URL/oauth/callback/oidc"
      clients:
        github:  # 这个名称可以自定义
          client-id: CLIENT-ID
          client-secret: CLIENT-SECRET
          openid:
            issuer: AZURE_AD_ISSUER_URL
          scopes:
            - email
            - profile
            - openid

akhq:
  security:
    default-group: no-roles
    oidc:  # 注意这里改为oidc而非oauth2
      enabled: true
      providers:
        github:  # 需要与micronaut部分名称一致
          label: "Login with AzureAD"
          username-field: preferred_username  # Azure AD的用户名字段
          groups-field: roles  # 组信息字段
          default-group: no-roles  # 默认组
          groups:
            - name: AZURE_AD_GROUP_MAP_NAME  # Azure AD中的组标识
              groups:  # 注意这里是列表结构
                - admin  # 映射到AKHQ的admin角色

关键配置说明

1. micronaut.security.oauth2：这部分配置OAuth2客户端参数，包括：

   • 回调URL必须与Azure AD应用中配置的重定向URI一致
   • issuer需要设置为Azure AD的颁发者URL
   • 必须包含openid scope

2. akhq.security.oidc：这部分专门配置OIDC集成：

   • username-field设置为Azure AD返回的用户名字段
   • groups-field指定包含组信息的字段
   • groups配置实现了Azure AD组到AKHQ角色的映射

最佳实践建议

1. 对于Azure AD集成，始终使用oidc而非oauth2配置项

2. 组映射配置中，groups字段必须使用列表形式，即使只有一个角色

3. 确保Azure AD应用注册中配置的权限包含profile、email和openid

4. 测试阶段可以先简化配置，仅保留基本登录功能，确认无误后再添加组映射

通过以上配置调整，AKHQ可以顺利集成Azure AD登录，并根据AD中的组信息分配相应的管理权限。