History

Loïc Hoguin bbfa066d79 Cleanup .gitignore files for the monorepo We don't need to duplicate so many patterns in so many files since we have a monorepo (and want to keep it). If I managed to miss something or remove something that should stay, please put it back. Note that monorepo-wide patterns should go in the top-level .gitignore file. Other .gitignore files are for application or folder- specific patterns.		2024-06-28 12:00:52 +02:00
..
src	Remove unused imports (thanks elp!)	2024-05-23 16:36:08 +02:00
BUILD.bazel	Use gazelle generated bazel files	2023-04-17 18:13:18 +02:00
CODE_OF_CONDUCT.md	Replace files with symlinks	2022-04-15 06:04:29 -07:00
CONTRIBUTING.md	Replace files with symlinks	2022-04-15 06:04:29 -07:00
LICENSE	Replace @rabbitmq.com addresses with rabbitmq-core@groups.vmware.com	2023-06-20 15:40:13 +04:00
LICENSE-MPL-RabbitMQ	Revert drop of Exhibit B on MPL 2.0	2020-07-20 16:57:32 +01:00
Makefile	Add a workflow to compare the bazel/erlang.mk output	2023-05-15 13:54:14 +02:00
README.md	Fixes #10649	2024-03-01 10:33:36 -05:00
app.bzl	Replace globs in bazel with explicit lists of files	2023-04-25 17:29:12 +02:00

README.md

x509 (TLS/SSL) certificate Authentication Mechanism for RabbitMQ

This plugin allows RabbitMQ clients authenticate using x509 certificates and TLS (PKI) peer verification mechanism instead of credentials (username/password pairs).

How it Works

When a client connects and performs TLS upgrade, the username is obtained from the client's TLS (x509) certificate. The user's password is not checked.

In order to use this mechanism the client must connect with TLS enabled, and present a client certificate.

Usage

This mechanism must also be enabled in RabbitMQ's configuration file, see Authentication Mechanisms and Configuration guides for more details.

A couple of examples:

auth_mechanisms.1 = PLAIN
auth_mechanisms.2 = AMQPLAIN
auth_mechanisms.3 = EXTERNAL

to allow this mechanism in addition to the defaults, or:

auth_mechanisms.1 = EXTERNAL

to allow only this mechanism and prohibit connections that use username and passwords.

For safety the server must be configured with the SSL option 'verify' set to 'verify_peer', to ensure that if an SSL client presents a certificate, it gets verified.

Username Extraction from Certificate

Distinguished Name

By default this will set the username to an RFC 4514-ish string form of the certificate's subject's Distinguished Name, similar to that produced by OpenSSL's "-nameopt RFC 2253" option.

You can obtain this string form from a certificate with a command like:

openssl x509 -in path/to/cert.pem -nameopt RFC2253 -subject -noout

or from an existing amqps connection with commands like:

rabbitmqctl list_connections peer_cert_subject

Subject Alternative Name

To extract username from a Subject Alternative Name (SAN) field, a few settings need to be configured. Since a certificate can have more than one SAN field and they can represent identities of different types, the type and the index of the field to use must be provided.

For example, to use the first SAN value of type DNS:

auth_mechanisms.1 = EXTERNAL

ssl_cert_login_from      = subject_alternative_name
ssl_cert_login_san_type  = dns
ssl_cert_login_san_index = 0

Or of type email:

auth_mechanisms.1 = EXTERNAL

ssl_cert_login_from      = subject_alternative_name
ssl_cert_login_san_type  = email
ssl_cert_login_san_index = 0

Common Name

To use the Common Name instead, set rabbit.ssl_cert_login_from to common_name:

auth_mechanisms.1 = EXTERNAL

ssl_cert_login_from = common_name

Note that the authenticated user will then be looked up in the configured authentication / authorisation backend(s). This will be the internal node database by default but could include other backends if so configured.

Copyright & License

Released under the same license as RabbitMQ.