[Suggestion] New HTTP API endpoints for configuration validation

[sunfinite]

RabbitMQ series

4.1.x

Operating system (distribution) used

Linux

How is RabbitMQ deployed?

RabbitMQ-as-a-Service from a public cloud provider

What would you like to suggest for a future version of RabbitMQ?

In settings where operators do not have remote access to the RabbitMQ nodes, it is hard to determine network reachability and potential misconfigurations without applying changes directly to a running broker.

We propose an enhancement by adding plugin specific endpoints that allows broker administrators to validate new values for auth plugin settings without affecting the running broker environment. These endpoints would enable the following:

1. Validate reachability of hostnames and ports and ensure TLS/CA trust chain settings are correct
2. Test credentials: decode an OAuth2 JWT token or attempt bind to an LDAP server

This reduces the risk of outages from misconfiguration and improves troubleshooting times.

Example using an invalid cacertfile:

% curl -X POST https://localhost:15672/api/oauth2/validate/dry-run \
  -u ${RABBIT_ADMIN_USER}:${RABBIT_ADMIN_PASSWORD} \
  -H "Content-Type: application/json" \
  -d '{
      "jwks_uri": "https://cognito-idp.us-west-2.amazonaws.com/us-west-2_L5cHZ0bp8/.well-known/jwks.json",
      "resource_server_id": "rabbitmq", 
      "https": {
        "cacertfile": "/tmp/invalid-ca-cert.pem",
      },
      "jwt_token": "$TOKEN"
  }' -i

HTTP/1.1 400 Bad Request
allow: POST
cache-control: public, max-age=0, must-revalidate
content-length: 616
content-security-policy: script-src 'self' 'unsafe-eval' 'unsafe-inline'; object-src 'self'
content-type: application/json
date: Mon, 14 Jul 2025 20:59:34 GMT
server: Cowboy
vary: accept, accept-encoding, origin

{"error":"[{message,<<\"JWT validation error: {failed_connect,\\n [{to_address,\\n {\\\"cognito-idp.us-west-2.amazonaws.com\\\",443}},\\n{inet,\\n[inet],\\n{tls_alert,\\n{unknown_ca,\\n\\\"TLS client: In state certify at ssl_handshake.erl:2134 generated CLIENT ALERT: Fatal - Unknown CA\\\\n\\\"}}}]}\">>},\n {reason,<<\"jwt_validation_error\">>},\n {status,<<\"error\">>}]"}%

Note that calling this endpoint will not affect the effective configuration of the running broker in any way. The functionality of this endpoint could be extended to perform authz checks given a vhost/queue/topic etc

[michaelklishin]

@sunfinite you can extend the HTTP API from plugins.

If the goal is to try to to validate everything that can be configured, no one on the core team would object to such a plugin.

[SimonUnge]

I have been playing with the idea to one day add a configuration manager plugin - But I think this ask here is smaller in scope!

[michaelklishin]

If the idea is to add new endpoints to a group of existing tier 1 plugins with a limited scope, the only difficult part should be naming. We don't want to promise that we will validate everything, so POST /api/oauth2/validate won't fly but POST /api/oauth2/validate/token/decode should make it very obvious that the endpoint does one thing only.