如何让mod_auth_openidc传递Keycloak访问令牌中的角色等声明？

mod_auth_openidc不会自动把JWT中的所有字段传递给后端应用，需要通过特定配置开启信息传递并正确映射Keycloak的角色声明，以下是具体解决步骤：

1. 开启用户信息传递配置 #

mod_auth_openidc默认仅处理认证会话，不会主动将用户声明传给后端，需通过以下参数开启传递：

• OIDCPassClaimsAs：指定声明传递方式，可选值为headers（HTTP请求头）、environment（环境变量）或both。例如：

  OIDCPassClaimsAs headers
  

• OIDCScope：确保包含足够的scope，至少保留openid，如需获取更多用户信息可添加profile、email等：

  OIDCScope "openid profile"
  

• OIDCUnAuthAction auth：强制未认证请求跳转到Keycloak登录，确保只有认证后的请求才会携带用户信息。

2. 映射Keycloak嵌套的角色声明 #

你的JWT角色信息嵌套在openid-connect.roles中，mod_auth_openidc默认无法直接识别嵌套字段，需配置提取规则：

• 使用OIDCAddClaim将嵌套的角色字段提取为顶级声明：

  OIDCAddClaim roles "openid-connect.roles"
  

• 用OIDCRoleClaim指定角色来源为提取后的roles字段：

  OIDCRoleClaim roles
  

• 可选配置OIDCClaimPrefix为请求头添加统一前缀，方便后端识别：

  OIDCClaimPrefix OIDC-
  

3. 验证核心配置正确性 #

确保基础OIDC配置无误，否则mod_auth_openidc无法正常获取和解析JWT：

• OIDCProviderMetadataURL：正确指向Keycloak realm的元数据地址，格式为：

  OIDCProviderMetadataURL http://your-keycloak-domain/auth/realms/your-realm/.well-known/openid-configuration
  

• OIDCClientID和OIDCClientSecret：与Keycloak中创建的客户端ID、密钥完全一致。
• 确保AuthType openid-connect和Require valid-user已添加到需要保护的路径配置中：

  <Location /your-app-path>
      AuthType openid-connect
      Require valid-user
  </Location>
  

完整配置示例 #

<VirtualHost *:80>
    ServerName your-app.example.com

    # 基础OIDC配置
    OIDCProviderMetadataURL http://keycloak.example.com/auth/realms/your-realm/.well-known/openid-configuration
    OIDCClientID your-client-id
    OIDCClientSecret your-client-secret
    OIDCScope "openid profile"
    OIDCUnAuthAction auth

    # 声明传递配置
    OIDCPassClaimsAs headers
    OIDCClaimPrefix OIDC-
    OIDCAddClaim roles "openid-connect.roles"
    OIDCRoleClaim roles

    # 应用路径保护
    <Location /app>
        AuthType openid-connect
        Require valid-user
        # 可选：基于角色授权
        # Require claim roles=role-1
    </Location>
</VirtualHost>

验证方法 #

配置完成后重启Apache，访问受保护的应用路径，登录成功后：

• 用浏览器开发者工具查看请求头，应能看到OIDC-roles等携带角色信息的头字段；
• 后端可通过读取对应HTTP头或环境变量获取角色数据。

内容的提问来源于stack exchange，提问作者QF0