Thank you to all the people building the future with us.
Thank you to all the people building the future with us.
This guide covers a variety of topics related to credentials and passwords used by the internal authentication backend. If a different authentication backend is used, most material in this guide will not be applicable.
RabbitMQ supports multiple authentication mechanisms. Some of them use username/password pairs. These credential pairs are then handed over to an authentication backends that perform authentication. One of the backends, known as internal or built-in, uses internal RabbitMQ data store to store user credentials. When a new user is added using rabbitmqctl, her password is combined with a salt value and hashed.
As of version 3.6.0, RabbitMQ can be configured to use several password hashing functions:
It is possible to change what algorithm is used via RabbitMQ configuration file, for example, to use SHA-512:
password_hashing_module = rabbit_password_hashing_sha512Or, using the classic config format:
[
{rabbit, [{password_hashing_module, rabbit_password_hashing_sha512}]}
].
Out of the box, the following hashing modules are provided:
Updated hashing algorithm will be applied to newly created users or when password is changed using rabbitmqctl.
When upgrading from a pre-3.6 version to RabbitMQ 3.6.1 or later, all existing users are marked as using the legacy password hashing function, therefore they will be able to authenticate. No upgrade steps are required.
When importing definitions exported from versions earlier than 3.6.0 into a 3.6.1 or later release, existing user records will use MD5 for password hashing. In order to migrate them to a more secure algorithm, use rabbitmqctl to update their passwords.
When upgrading from a pre-3.6 version to RabbitMQ 3.6.0 (but not later versions), all existing users are marked as using the legacy password hashing function, therefore they will be able to authenticate. No upgrade steps are required.
If you'd like to avoid using MD5 for existing users, you need to update passwords for all users using rabbitmqctl after upgrading.
When importing definitions exported from versions earlier than 3.6.0, it is possible to go back to MD5 (as a temporary measure) by setting this to rabbit_password_hashing_md5:
The above steps are only necessary for those who perform an export on a pre-3.6.0 node and then an import to 3.6.0. Those who upgrade "in place" or move definitions from a 3.6.0+ node to another 3.6.0+ node do not need to do anything.
The most secure thing to do is to update passwords for all existing users, if possible, to avoid relying on MD5 for anything.
Starting with version 3.6.7 it is possible to define a credential validator. It only has effect on the internal authentication backend and kicks in when a new user is added or password of an existing user is changed.
Validators are modules that implement a validation function. To use a validator, it is necessary to specify it and its additional settings in the config file. There are three credential validators available out of the box:
The following example demonstrates how rabbit_credential_validator_min_password_length is used:
credential_validator.validation_backend = rabbit_credential_validator_min_password_length
credential_validator.min_length = 30
In the classic config format that would be
[
{rabbit, [
{credential_validator, [{validation_backend,
rabbit_credential_validator_min_password_length},
{min_length, 30}]}
]}
].
The following example demonstrates how rabbit_credential_validator_password_regexp is used:
credential_validator.validation_backend = rabbit_credential_validator_password_regexp
credential_validator.regexp = ^[a-bA-Z0-9$]{20,100}
which becomes
[
{rabbit, [
{credential_validator, [{validation_backend,
rabbit_credential_validator_password_regexp},
{regexp, <<"^[a-bA-Z0-9$]{20,100}">>}]}
]}
].
in the classic config format.
Every credential validator is a module that implements a single function behaviour, rabbit_credential_validator. Plugins therefore can provide more implementations.
Credential validators can also validate usernames or apply any other logic (e.g. make sure that provided username and password are not identical).
Internal authentication backend allows for users without a password or with a blank one (assuming credential validator also allows it). Such users are only mean to be used with passwordless authentication mechanisms such as authentication using x509 certificates.
In order to create a passwordless user, create one with any password that passes validation and clear the password using rabbitmqctl's clear_password command:
rabbitmqctl add_user passwordless-user "pa$$wordless"
rabbitmqctl clear_password passwordless-user
# don't forget to grant the user virtual host access permissions using set_permissions
# ...
Starting with versions 3.6.15 and 3.7.3, authentication attempts that use a blank password will be unconditionally rejected by the internal authentication backend with a distinctive error message in the server log. Connections that authenticate using x509 certificates or use an external service for authentication (e.g. LDAP) can use blank passwords.
It is possible to authenticate connections using x509 certificates and avoid using passwords entirely. The authentication process then will rely on TLS peer certificate chain validation.
To do so:
In order to update a user's password hash via the HTTP API, the password hash must be generated using the following algorithm:
If you have questions about the contents of this guide or any other topic related to RabbitMQ, don't hesitate to ask them on the RabbitMQ mailing list.
Documentation feedback is also very welcome on the list. If you'd like to contribute an improvement to the site, its source is available on GitHub.
Copyright © 2007-Present Pivotal Software, Inc. All rights reserved. Terms of Use, Privacy and Trademark Guidelines