HTTP-based authorisation and authentication for RabbitMQ
Switch branches/tags
v3.7.8-rc.4 v3.7.8-rc.3 v3.7.8-rc.2 v3.7.8-rc.1 v3.7.7 v3.7.7-rc.2 v3.7.7-rc.1 v3.7.7-beta.2 v3.7.7-beta.1 v3.7.6 v3.7.6-rc.2 v3.7.6-rc.1 v3.7.5 v3.7.5-rc.1 v3.7.5-beta.3 v3.7.5-beta.2 v3.7.5-beta.1 v3.7.4 v3.7.4-rc.4 v3.7.4-rc.3 v3.7.4-rc.2 v3.7.4-rc.1 v3.7.3 v3.7.3-rc.2 v3.7.3-rc.1 v3.7.2 v3.7.1 v3.7.1-beta.1 v3.7.0 v3.7.0-rc.2 rabbitmq_v3_7_0_milestone18 rabbitmq_v3_7_0_milestone17 rabbitmq_v3_7_0_milestone16 rabbitmq_v3_7_0_milestone15 rabbitmq_v3_7_0_milestone14 rabbitmq_v3_7_0_milestone13 rabbitmq_v3_7_0_milestone12 rabbitmq_v3_7_0_milestone11 rabbitmq_v3_7_0_milestone10 rabbitmq_v3_7_0_milestone9 rabbitmq_v3_7_0_milestone8 rabbitmq_v3_7_0_milestone7 rabbitmq_v3_7_0_milestone6 rabbitmq_v3_7_0_milestone5 rabbitmq_v3_7_0_milestone4 rabbitmq_v3_7_0_milestone3 rabbitmq_v3_7_0_milestone2 rabbitmq_v3_7_0_milestone1 rabbitmq_v3_6_14 rabbitmq_v3_6_13 rabbitmq_v3_6_13_rc2 rabbitmq_v3_6_13_rc1 rabbitmq_v3_6_13_milestone1 rabbitmq_v3_6_12 rabbitmq_v3_6_12_rc3 rabbitmq_v3_6_12_rc2 rabbitmq_v3_6_12_rc1 rabbitmq_v3_6_11 rabbitmq_v3_6_11_rc3 rabbitmq_v3_6_11_rc2 rabbitmq_v3_6_11_rc1 rabbitmq_v3_6_11_milestone5 rabbitmq_v3_6_11_milestone4 rabbitmq_v3_6_11_milestone3 rabbitmq_v3_6_11_milestone2 rabbitmq_v3_6_11_milestone1 rabbitmq_v3_6_10 rabbitmq_v3_6_10_rc2 rabbitmq_v3_6_10_rc1 rabbitmq_v3_6_10_milestone4 rabbitmq_v3_6_10_milestone3 rabbitmq_v3_6_10_milestone2 rabbitmq_v3_6_10_milestone1 rabbitmq_v3_6_9 rabbitmq_v3_6_8 rabbitmq_v3_6_7 rabbitmq_v3_6_7_rc3 rabbitmq_v3_6_7_rc2 rabbitmq_v3_6_7_rc1 rabbitmq_v3_6_7_milestone6 rabbitmq_v3_6_7_milestone5 rabbitmq_v3_6_7_milestone4 rabbitmq_v3_6_7_milestone3 rabbitmq_v3_6_7_milestone2 rabbitmq_v3_6_7_milestone1 rabbitmq_v3_6_6 rabbitmq_v3_6_6_rc2 rabbitmq_v3_6_6_rc1 rabbitmq_v3_6_6_milestone5 rabbitmq_v3_6_6_milestone4 rabbitmq_v3_6_6_milestone3 rabbitmq_v3_6_6_milestone2 rabbitmq_v3_6_6_milestone1 rabbitmq_v3_6_5 rabbitmq_v3_6_5_milestone2 rabbitmq_v3_6_5_milestone1 rabbitmq_v3_6_4 rabbitmq_v3_6_4_rc1 rabbitmq_v3_6_4_milestone2 rabbitmq_v3_6_4_milestone1
Nothing to show
Clone or download

README.md

Overview

This plugin provides the ability for your RabbitMQ server to perform authentication (determining who can log in) and authorisation (determining what permissions they have) by making requests to an HTTP server.

This plugin can put a significant amount of load on its backing service. We recommend using it together with rabbitmq_auth_backend_cache with a reasonable caching interval (e.g. 1-3 minutes).

Project Maturity

As of 3.7.0, this plugin is distributed with RabbitMQ.

RabbitMQ Version Requirements

As of 3.7.0, this plugin is distributed with RabbitMQ.

As with all authentication plugins, this one requires RabbitMQ server 2.3.1 or later.

Using with RabbitMQ 3.6.x

Install the corresponding .ez files from our Community Plugins page. Note that different releases of this plugin support different versions of RabbitMQ.

Enabling the Plugin

First enable the plugin using rabbitmq-plugins:

rabbitmq-plugins enable rabbitmq_auth_backend_http

Configuring the Plugin

To use this backend exclusively, use the following snippet in rabbitmq.conf (currently in master)

auth_backends.1 = http

Or, in the classic config format (rabbitmq.config, prior to 3.7.0) or advanced.config:

[{rabbit, [{auth_backends, [rabbit_auth_backend_http]}]}].

See RabbitMQ Configuration guide and Access Control guide for more information.

You need to configure the plugin to know which URIs to point at and which HTTP method to use.

Below is a minimal configuration file example.

In rabbitmq.conf:

auth_backends.1 = http
auth_http.user_path     = http://some-server/auth/user
auth_http.vhost_path    = http://some-server/auth/vhost
auth_http.resource_path = http://some-server/auth/resource
auth_http.topic_path    = http://some-server/auth/topic

In the classic config format (rabbitmq.config prior to 3.7.0 or advanced.config):

[
  {rabbit, [{auth_backends, [rabbit_auth_backend_http]}]},
  {rabbitmq_auth_backend_http,
   [{http_method,   post},
    {user_path,     "http(s)://some-server/auth/user"},
    {vhost_path,    "http(s)://some-server/auth/vhost"},
    {resource_path, "http(s)://some-server/auth/resource"},
    {topic_path,    "http(s)://some-server/auth/topic"}]}
].

By default http_method configuration is GET for backwards compatibility. It's recommended to use POST requests to avoid credentials logging.

What Must My Web Server Do?

This plugin requires that your web server respond to requests in a certain predefined format. It will make GET (by default) or POST requests against the URIs listed in the configuration file. It will add query string (for GET requests) or a URL-encoded request body (for POST requests) parameters as follows:

user_path

  • username - the name of the user
  • password - the password provided (may be missing if e.g. rabbitmq-auth-mechanism-ssl is used)

vhost_path

  • username - the name of the user
  • vhost - the name of the virtual host being accessed
  • ip - the client ip address

Note that you cannot create arbitrary virtual hosts using this plugin; you can only determine whether your users can see / access the ones that exist.

resource_path

  • username - the name of the user
  • vhost - the name of the virtual host containing the resource
  • resource - the type of resource (exchange, queue, topic)
  • name - the name of the resource
  • permission - the access level to the resource (configure, write, read) - see the Access Control guide for their meaning

topic_path

  • username - the name of the user
  • vhost - the name of the virtual host containing the resource
  • resource - the type of resource (topic in this case)
  • name - the name of the exchange
  • permission - the access level to the resource (write or read)
  • routing_key - the routing key of a published message (when the permission is write) or routing key of the queue binding (when the permission is read)

See topic authorisation for more information about topic authorisation.

Your web server should always return HTTP 200 OK, with a body containing:

  • deny - deny access to the user / vhost / resource
  • allow - allow access to the user / vhost / resource
  • allow [list of tags] - (for user_path only) - allow access, and mark the user as an having the tags listed

Using TLS/HTTPS

If your Web server uses HTTPS and certificate verification, you need to configure the plugin to use a CA and client certificate/key pair using the rabbitmq_auth_backend_http.ssl_options config variable:

[
  {rabbit, [{auth_backends, [rabbit_auth_backend_http]}]},
  {rabbitmq_auth_backend_http,
   [{http_method,   post},
    {user_path,     "https://some-server/auth/user"},
    {vhost_path,    "https://some-server/auth/vhost"},
    {resource_path, "https://some-server/auth/resource"},
    {topic_path,    "https://some-server/auth/topic"},
    {ssl_options,
     [{cacertfile, "/path/to/cacert.pem"},
      {certfile,   "/path/to/client/cert.pem"},
      {keyfile,    "/path/to/client/key.pem"},
      {verify,     verify_peer},
      {fail_if_no_peer_cert, true}]}]}
].

It is recommended to use TLS for authentication and enable peer verification.

Debugging

Check the RabbitMQ logs if things don't seem to be working properly. Look for log messages containing "rabbit_auth_backend_http failed".

Example Apps

There are example backend services available in Python, PHP, Spring Boot, ASP.NET Web API.

See examples README for more information.

Building from Source

You can build and install it like any other plugin (see the plugin development guide).

This plugin depends on the Erlang client (just to grab a URI parser).