RabbitMQ TLS (x509 certificate) authentication mechanism
Makefile Erlang
Switch branches/tags
v3.7.0-rc.1 v3.7.0-beta.20 v3.7.0-beta.19 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_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 rabbitmq_v3_6_3 rabbitmq_v3_6_3_rc3 rabbitmq_v3_6_3_rc2 rabbitmq_v3_6_3_rc1 rabbitmq_v3_6_3_milestone2 rabbitmq_v3_6_3_milestone1 rabbitmq_v3_6_2 rabbitmq_v3_6_2_rc4 rabbitmq_v3_6_2_rc3 rabbitmq_v3_6_2_rc2 rabbitmq_v3_6_2_rc1 rabbitmq_v3_6_2_milestone5 rabbitmq_v3_6_2_milestone4 rabbitmq_v3_6_2_milestone3 rabbitmq_v3_6_2_milestone2 rabbitmq_v3_6_2_milestone1 rabbitmq_v3_6_1 rabbitmq_v3_6_1_rc2 rabbitmq_v3_6_1_rc1 rabbitmq_v3_6_0 rabbitmq_v3_6_0_rc3 rabbitmq_v3_6_0_rc2 rabbitmq_v3_6_0_rc1 rabbitmq_v3_6_0_milestone3 rabbitmq_v3_6_0_milestone2 rabbitmq_v3_6_0_milestone1 rabbitmq_v3_5_8 rabbitmq_v3_5_7 rabbitmq_v3_5_7_rc2 rabbitmq_v3_5_7_rc1 rabbitmq_v3_5_6
Nothing to show

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:

[
  {rabbit, [
    {auth_mechanisms, ['PLAIN', 'AMQPLAIN', 'EXTERNAL']}
  ]}
].

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

[
  {rabbit, [
    {auth_mechanisms, ['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

Common Name

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

[
  {rabbit, [
    {auth_mechanisms, ['PLAIN', 'AMQPLAIN', '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

(c) Pivotal Software Inc., 2007 — 2017.

Released under the same license as RabbitMQ.