Solr部署：JWT认证插件配置与OpenID Connect集成完整指南

Posted on 四月 23, 2025 本文总阅读量次

Solr部署：JWT认证插件配置与OpenID Connect集成完整指南

概述

Solr支持通过JWTAuthPlugin实现基于JSON Web Token (JWT) 的Bearer认证。这允许Solr验证用户已通过外部身份提供者（Identity Provider, IdP）进行身份验证，通过验证JWT格式的访问令牌的数字签名来确认用户身份。

典型应用场景是将Solr与启用了OpenID Connect的身份提供者集成。

模块要求

JWT认证功能通过jwt-auth Solr模块提供，使用前需要先启用该模块。

启用JWT认证

基本配置

要使用JWT Bearer认证，security.json文件必须包含定义认证类和配置参数的authentication部分。

最简单的配置示例：

{
  "authentication": {
    "class":"solr.JWTAuthPlugin",
    "blockUnknown":"false"
  }
}

关键配置说明

默认行为：插件默认要求所有流量都提供有效的JWT令牌
blockUnknown属性：设置为false时允许通过未认证的REST API调用进行配置
配置阶段：可以在blockUnknown=false状态下完成初始配置

配置参数详解

基础认证参数

参数	描述	默认值
`blockUnknown`	设置为`false`允许通过REST API配置或与授权插件配合仅保护特定路径	`true`
`realm`	在HTTP 401响应中回显的认证域名，也在管理界面登录页显示	`'solr-jwt'`
`scope`	空格分隔的有效作用域列表。JWT访问令牌必须包含至少一个列出的作用域	无
`requireIss`	拒绝缺少`iss`（颁发者）声明的请求	`true`
`requireExp`	拒绝缺少`exp`（过期时间）声明的请求	`true`

算法和缓存参数

参数	描述	默认值
`algAllowlist`	接受的算法JSON数组：`HS256`, `HS384`, `HS512`, `RS256`, `RS384`, `RS512`, `ES256`, `ES384`, `ES512`, `PS256`, `PS384`, `PS512`, `none`	允许所有算法
`jwkCacheDur`	JWK缓存持续时间（秒）	`3600`（1小时）

声明处理参数

参数	描述	默认值
`principalClaim`	提取用户主体的声明ID	`sub`
`rolesClaim`	提取用户角色的声明ID。支持顶级和嵌套声明，使用`someClaim.child`语法	默认使用`scope`声明中的作用域
`claimsMatch`	声明必须匹配正则表达式的JSON对象。例：`{ “foo” : “A	B” }`

UI和安全参数

参数	描述	默认值
`adminUiScope`	从管理界面登录时请求的作用域	使用`scope`参数中的第一个作用域
`redirectUris`	外部认证后的有效重定向位置。字符串或字符串数组	空列表
`trustedCerts`	信任的X.509 SSL证书（PEM或PKCS#7格式）	Java信任存储
`trustedCertsFile`	包含信任证书的文件路径	Java信任存储

颁发者配置

多颁发者支持

插件支持一个或多个令牌颁发者（身份提供者）。颁发者在issuers配置键下配置为JSON对象列表。

重要：列表中的第一个颁发者是”主要颁发者”，用于管理界面登录。

颁发者配置参数

参数	描述	默认值
`name`	颁发者的唯一名称	-
`wellKnownUrl`	OpenID Connect发现端点URL	-
`clientId`	OpenID Connect客户端标识符	-
`jwksUrl`	JWKs端点URL（必须使用HTTPS）	从`wellKnownUrl`自动配置
`jwk`	静态JSON格式的公钥（JWK或JWK Set格式）	-
`iss`	颁发者ID	从`wellKnownUrl`自动配置
`aud`	验证`aud`（受众）声明	使用`clientId`
`authorizationEndpoint`	身份提供者的授权端点URL	从`wellKnownUrl`自动配置
`tokenEndpoint`	身份提供者的令牌端点URL	从`wellKnownUrl`自动配置
`authorizationFlow`	OAuth 2.0流程：`implicit`或`code_pkce`	`implicit`

向后兼容性

主要颁发者的所有配置键（除name外）可以配置为顶级键以保持向后兼容。

配置示例

使用JWKS URL的配置

{
  "authentication": {
    "class": "solr.JWTAuthPlugin",
    "jwksUrl": "https://my.key.server/jwk.json"
  }
}

支持管理界面的配置

使用OpenID Connect发现进行自动配置：

{
  "authentication": {
    "class": "solr.JWTAuthPlugin",
    "wellKnownUrl": "https://idp.example.com/.well-known/openid-configuration",
    "clientId": "xyz",
    "redirectUris": "https://my.solr.server:8983/solr/"
  }
}

复杂配置示例

双颁发者配置，其中一个使用静态嵌入的JWK：

{
  "authentication": {
    "class": "solr.JWTAuthPlugin",                    // 插件类
    "blockUnknown": true,                            // 阻止无效令牌
    "principalClaim": "solruid",                     // 从自定义声明提取用户ID
    "claimsMatch": { 
      "foo" : "A|B", 
      "dept" : "IT" 
    },                                               // 声明匹配要求
    "scope": "solr:read solr:write solr:admin",      // 必需的作用域
    "algAllowlist": [ "RS256", "RS384", "RS512" ],   // 仅接受RSA算法
    "issuers": [                                     // 颁发者配置数组
      {
        "name": "example1-static",                   // 唯一颁发者名称
        "jwk": {                                     // 内联JWK
          "e": "AQAB",
          "kid": "k1",
          "kty": "RSA",
          "n": "3ZF6w....vjbCXxw"
        },
        "clientId": "solr-client-12345",             // 客户端ID
        "iss": "https://example.com/idp",            // 颁发者ID
        "aud": "https://example.com/solr"            // 受众声明
      },
      {
        "name": "example2",
        "wellKnownUrl": "https://example2.com/.well-known/oidc",  // 自动配置
        "aud": "https://example2.com/solr"
      }
    ],
    "trustedCertsFile": "/path/to/certsFile.pem"     // SSL证书信任文件
  }
}

高级配置选项

非SSL URL支持

仅开发环境：生产环境必须使用SSL保护的HTTPS连接。

开发环境中使用HTTP URL的启动参数：

1	-Dsolr.auth.jwt.allowOutboundHttp=true

信任IdP服务器

与OAuth2服务器（IdP）的所有通信都通过HTTPS进行。

默认行为

使用Java内置的TrustStore。

自定义信任配置

配置trustedCertsFile或trustedCerts后：

仅信任提供的证书集合
不信任根CA签署的任何证书
更安全且支持自签名证书
即使Solr未在SSL模式下启动也可以工作

配置规则

仅配置trustedCerts或trustedCertsFile其中之一
同时配置会导致错误
trustedCertsFile可以是字符串数组，Solr会解析所有文件中的证书

多重认证方案

使用MultiAuthPlugin基于Authorization头支持多种认证方案：

{
  "authentication": {
    "class": "solr.MultiAuthPlugin",
    "schemes": [
      {
        "scheme": "bearer",
        "class": "solr.JWTAuthPlugin",
        "wellKnownUrl": "https://idp.example.com/.well-known/openid-configuration",
        "clientId": "solr-client"
      },
      {
        "scheme": "basic", 
        "class": "solr.BasicAuthPlugin",
        "credentials": {"admin": "password"}
      }
    ]
  }
}

动态配置管理

使用认证API

所有配置属性都可以通过认证API设置或更改：

# V1 API
curl http://localhost:8983/solr/admin/authentication \
  -H 'Content-type:application/json' \
  -H 'Authorization: Bearer xxx.yyy.zzz' \
  -d '{
    "set-property": {
      "blockUnknown":true,
      "wellKnownUrl": "https://example.com/.well-known/openid-configuration",
      "scope": "solr:read solr:write"
    }
  }'

# V2 API  
curl http://localhost:8983/api/cluster/security/authentication \
  -H 'Content-type:application/json' \
  -H 'Authorization: Bearer xxx.yyy.zzz' \
  -d '{
    "set-property": {
      "blockUnknown":true,
      "wellKnownUrl": "https://example.com/.well-known/openid-configuration", 
      "scope": "solr:read solr:write"
    }
  }'

配置策略

初始配置：使用blockUnknown=false
API配置：通过REST API完成详细配置
启用保护：设置blockUnknown=true开始强制执行

注意：当前不支持通过REST API添加多个令牌颁发者。

客户端使用指南

cURL客户端

1 2	curl -H "Authorization: Bearer xxxxxx.xxxxxx.xxxxxx" \ http://localhost:8983/solr/admin/info/system

SolrJ客户端

限制：SolrJ当前不支持每请求提供JWT令牌。

管理界面

启用插件后的管理界面行为：

登录流程：用户执行受限操作时重定向到登录页
IdP重定向：点击按钮后重定向到身份提供者登录页
多颁发者：使用列表中的第一个颁发者
会话管理：会话持续至JWT令牌过期，仅对单个Solr服务器有效
登出功能：左侧列中的登出菜单

限制和注意事项

当前限制

Solr控制脚本：bin/solr脚本当前不支持JWT认证
SolrJ集成：不支持每请求JWT令牌供应
会话范围：管理界面会话仅对单个Solr节点有效

安全建议

生产环境：始终使用HTTPS连接
证书管理：使用自定义信任存储提高安全性
作用域控制：合理配置scope限制访问权限
令牌管理：设置合理的令牌过期时间

故障排除

常见问题

认证失败：
- 检查JWT令牌格式和有效性
- 验证颁发者配置是否正确
- 确认算法白名单设置
管理界面问题：
- 验证重定向URI配置
- 检查客户端ID和IdP配置
- 确认证书信任设置
配置错误：
- 验证JSON格式正确性
- 检查必需参数是否提供
- 确认模块已正确启用

调试技巧

# 检查认证配置
curl http://localhost:8983/solr/admin/authentication

# 验证JWT令牌
echo "xxx.yyy.zzz" | base64 -d

# 测试连接
curl -v -H "Authorization: Bearer TOKEN" http://localhost:8983/solr/admin/info/system

最佳实践

部署策略

分阶段部署：
- 开发环境验证配置
- 测试环境完整测试
- 生产环境逐步迁移
监控和告警：
- 监控认证成功/失败率
- 设置证书过期告警
- 监控令牌使用情况
备份和恢复：
- 备份security.json配置
- 文档化恢复流程
- 测试灾难恢复

总结

JWT认证插件为Solr提供了现代化的认证解决方案，通过与OpenID Connect集成实现了企业级的身份管理。正确配置JWT认证可以显著提高Solr部署的安全性，同时提供良好的用户体验。

在实施过程中，需要特别注意证书管理、作用域配置和多颁发者支持等关键要素，确保系统既安全又易于管理维护。