OAuth 2 故障排除
概述
本指南介绍了使用 OAuth 2.0 和 管理插件 时最常见的错误以及如何诊断它们。
故障排除客户端连接
最大 JWT 令牌长度限制
重现步骤
当客户端连接到一个配置为使用 JWT 令牌进行身份验证和授权的节点时，可能会遇到最大消息协议帧限制异常。
故障排除
JWT 令牌的长度可能因编码内容而异。RabbitMQ 支持的消息协议对最大帧长度有实际限制。
默认值通常远高于实际可能的 JWT 令牌长度。例如，对于 AMQP 0-9-1 和 RabbitMQ Stream 协议，默认值为 128 kB。但是，可以通过 rabbitmq.conf 和客户端库配置覆盖最大帧限制。
如果客户端提供了长令牌且配置的限制较低，则连接将被拒绝，并在 服务器日志 中出现“帧长度超出”、“帧过大”等错误消息。
例如，对于 AMQP 0-9-1，情况如下：
2025-03-15 05:55:21.689185+00:00 [info] <0.2771.0> accepting AMQP connection <0.2771.0> (10.8.121.164:45024 -> 10.8.121.141:5672)
2025-03-15 05:55:24.745906+00:00 [error] <0.2771.0> closing AMQP connection <0.2771.0> (10.8.121.164:45024 -> 10.8.121.141:5672):
2025-03-15 05:55:24.745906+00:00 [error] <0.2771.0> {handshake_error,starting,0,
2025-03-15 05:55:24.745906+00:00 [error] <0.2771.0> {amqp_error,frame_error,
2025-03-15 05:55:24.745906+00:00 [error] <0.2771.0> "type 1, all octets = <<>>: {frame_too_large,6307,4088}",
2025-03-15 05:55:24.745906+00:00 [error] <0.2771.0> none}}
有两种可用解决方案：
- 增加
rabbitmq.conf中的initial_frame_max值，或advanced.config中的rabbit.initial_frame_max。 - 减小令牌内容大小，例如，通过删除 RabbitMQ 未使用的某些作用域或对其进行优化（简化）。
增加初始帧大小限制
以下 rabbitmq.conf 示例将初始帧大小限制从默认的 4096 字节增加到 8192 字节。
initial_frame_max = 8192
使用 advanced.config 的相同示例
[
{rabbit, [
{initial_frame_max, 8192}
]}
].
减小 JWT 令牌负载大小
通常可以通过删除 RabbitMQ 未使用的某些作用域来减小 JWT 令牌大小。或者，可以生成一个新的 JWT 令牌，其中包含一组更少的作用域，从而减小其大小。
管理 UI 中 OAuth 2.0 的故障排除
OpenID 发现端点不可达
重现步骤
在浏览器中打开管理 UI 的根 URL。您会看到以下错误消息，而不是“单击此处登录”按钮。
OAuth resource [rabbitmq] not available. OpenId Discovery endpoint https://<the_issuer_url>/.well-known/openid-configuration not reachable
故障排除
这些是导致此问题的最常见原因：
确定根本原因的最快方法是打开浏览器的 JavaScript 控制台并搜索 net::ERR_。最可能的错误是：
net::ERR_CONNECTION_REFUSED：端点已关闭或不可达。net::ERR_CERT_AUTHORITY_INVALID：端点的 TLS 证书不受浏览器信任。要信任此证书，请单击错误消息中的 URL 并按照提示操作。
如果没有错误与 net::ERR 匹配，请搜索 CORS。如果出现类似以下内容的错误：
Access to fetch at 'https://<the_issuer_url>>/.well-known/openid-configuration' from origin
'<rabbitmq_url_to_management_ui>' has been blocked by CORS policy
那么浏览器正在阻止端点返回的响应，因此该响应未传递给管理 UI。这是由于 CORS 策略。请要求身份提供商的管理员将管理 UI 的 URL 添加到允许的源列表中。
OpenID 发现端点不合规
重现步骤
在浏览器中打开管理 UI 的根 URL。您会看到以下错误消息，而不是“单击此处登录”按钮。
OAuth resource [rabbitmq] not available. OpenId Discovery endpoint https://<the_issuer_url>/.well-known/openid-configuration not compliant
故障排除
当端点返回的 JSON 负载与 OpenID Connect Discovery Configuration 不匹配时，会发生此问题。可能的原因如下：
- 端点返回的负载不合规，因为它为空或缺少一些关键信息。要确定根本原因，请打开浏览器的 JavaScript 控制台并搜索以下可能错误消息之一：
Payload does not contain openid configuration当负载为空或不是 JSON 负载时，会出现此错误。Missing authorization_endpoint当缺少 JSON 属性authorization_endpoint时，会出现此错误。Missing token_endpoint当缺少 JSON 属性token_endpoint时，会出现此错误。Missing jwks_uri当缺少 JSON 属性jwks_uri时，会出现此错误。
- URL 错误。请从您的身份提供商管理员那里获取正确的 OpenID Connect Discovery 端点 URL。
未授权
重现步骤
在浏览器中打开管理 UI 的根 URL。单击“单击此处登录”按钮，然后输入身份提供商要求的凭据。
您会被重定向回管理 UI，并显示以下错误：
Not authorized
故障排除
当令牌的作用域或权限不足以访问管理 UI 时，会出现此问题。您至少需要以下作用域之一或等效作用域：
rabbitmq.tag:administrator.rabbitmq.tag:management.rabbitmq.tag:monitoring.rabbitmq.tag:policymaker.
请按照以下步骤找出令牌中包含哪些作用域或权限：
- 打开浏览器的开发者工具（例如，在 Chrome 或 Firefox 中，右键单击页面并选择“检查”菜单选项）。
- 转到“应用程序”选项卡。
- 在左侧面板中选择“存储”>“本地存储”选项。
- 单击与管理 UI URL 匹配的树选项。
- 在右侧面板中选择键
rabbitmq.credentials。 - 复制其值。
- 导航到 https://jwt.net.cn。
- 将值粘贴到“已编码”文本字段中。
- 查看“已解码”文本字段中的负载。
- 搜索令牌属性
scope或配置的auth_oauth2.additional_scopes_key的值（如果存在）。 - 找到适当的令牌范围属性后，在属性值中查找上面列出的任何范围。如果使用了
auth_oauth2.scope_prefix，则必须将其考虑在内：范围将命名为myprefix_tag:administrator。如果使用了 范围别名，请查找映射到上述范围之一的范围别名。
OpenID 发现端点因证书无效而无法访问
此问题不一定仅限于管理 UI，当应用程序通过消息协议进行身份验证时也可能发生。当 RabbitMQ 需要通过 auth_oauth2.issuer 中配置的 URL 下载 OpenID Connect 配置时，以及颁发者使用的证书是通配符证书时，就会发生此问题。这意味着证书的 CN 属性与颁发者的域名不完全匹配。这在 SaaS 部署中非常常见。
重现步骤
- 在浏览器中打开管理 UI 的根 URL。
- 单击“单击此处登录”。
- 输入您的凭据。
- 您会被重定向回 RabbitMQ，但会收到“未授权”错误。
故障排除
- 访问 RabbitMQ 日志。
- 查找
{bad_cert,hostname_check_failed}。 - 如果找到该条目，则表示 RabbitMQ 尝试联系
auth_oauth2.issuer中找到的 URL，并且颁发者提供了一个通配符证书。 - 要解决此问题，请将以下行添加到
rabbitmq.conf：auth_oauth2.https.hostname_verification = wildcard，或者如果使用多个身份提供商，则为auth_oauth2.oauth_providers.<my_oauth_provider_name>.https.hostname_verification = wildcard。