<commit_before><!--
Copyright (c) 2007-2020 VMware, Inc. or its affiliates.

All rights reserved. This program and the accompanying materials
are made available under the terms of the under the Apache License,
Version 2.0 (the "License”); you may not use this file except in compliance
with the License. You may obtain a copy of the License at

https://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->

# Authentication, Authorisation, Access Control

## <a id="overview" class="anchor" href="#overview">Overview</a>

This document describes [authentication](#authentication) and [authorisation](#authorisation) features
in RabbitMQ. Together they allow the operator to control access to the system.
Different users can be granted access only to specific [virtual hosts](/vhosts.html). Their
permissions in each virtual hosts also can be limited.

RabbitMQ supports two major [authentication mechanisms](#mechanisms)
as well as several [authentication and authorisation backends](#backends).

[Password-based](/passwords.html) authentication has a companion guide.
A closely related topic of [TLS support](/ssl.html) is also covered in a dedicated guide.

Other topics discussed in this guide include:

 * [Access control essentials](#the-basics)
 * [Default virtual host and user](#default-state)
 * [Connectivity limitations](#loopback-users) imposed on the default user
 * How to [manage users and permissions](#user-management) using CLI tools
 * How to [pre-create users](#seeding) and their permissions
 * Troubleshooting of [authentication](#troubleshooting-authn) and [authorisation failures](#troubleshooting-authz)

## <a id="terminology-and-definitions" class="anchor" href="#terminology-and-definitions">Terminology and Definitions</a>

Authentication and authorisation are often confused or used
interchangeably. That's wrong and in RabbitMQ, the two are
separated. For the sake of simplicity, we'll define
authentication as "identifying who the user is" and
authorisation as "determining what the user is and isn't allowed to do."


## <a id="basics" class="anchor" href="#basics">The Basics</a>

Clients use RabbitMQ features to [connecting](/connections.html) to it. Every connection has
an associated user which is authenticated. It also targets a [virtual host](/vhosts.html) for which
the user must have a certain set of permissions.

User credentials, target virtual host and (optionally) client [certificate](/ssl.html) are specified at connection
initiation time.

There is a default pair of credentials called the [default user](#default-state). This user can only
be [used for **host-local connections**](#loopback-users) by default. Remote connections that use
it will be refused.

[Production environments](/production-checklist.html) should not use the default user and create
new user accounts with generated credentials instead.


## <a id="default-state" class="anchor" href="#default-state">Default Virtual Host and User</a>

When the server first starts running, and detects that its
database is uninitialised or has been deleted, it
initialises a fresh database with the following resources:

 * a [virtual host](/vhosts.html) named <code>/</code> (a slash)
 * a user named <code>guest</code> with a default password of <code>guest</code>, granted full access to the <code>/</code> virtual host

It is advisable to [delete](rabbitmqctl.8.html#delete_user)
the <code>guest</code> user or at least [change its password](rabbitmqctl.8.html#change_password)
to reasonably secure generated value that won't be known to the public.


## <a id="authentication" class="anchor" href="#authentication">Authentication: Who Do You Say You Are?</a>

After an application connects to RabbitMQ and before it can perform operations, it must
authenticate, that is, present and prove its identity. With that identity, RabbitMQ nodes can
look up its permissions and [authorize](#authorisation) access to resources
such as [virtual hosts](/vhosts.html), queues, exchanges, and so on.

Two primary ways of authenticating a client are [username/password pairs](/passwords.html)
and [X.509 certificates](https://en.wikipedia.org/wiki/X.509). Username/password pairs
can be used with a variety of [authentication backends](#backends) that verify the credentials.

Connections that fail to authenticate will be closed with an error message in the [server log](/logging.html).

To authenticate client connections using X.509 certificate a built-in plugin,
[rabbitmq-auth-mechanism-ssl](https://github.com/rabbitmq/rabbitmq-auth-mechanism-ssl),
must be enabled and clients must be [configured to use the EXTERNAL mechanism](#mechanisms).
With this mechanism, any client-provided password will be ignored.


## <a id="loopback-users" class="anchor" href="#loopback-users">"guest" user can only connect from localhost</a>

By default, the <code>guest</code> user is prohibited from
connecting from remote hosts; it can only connect over
a loopback interface (i.e. <code>localhost</code>). This
applies to [connections regardless of the protocol](/connections.html).
Any other users will not (by default) be restricted in this way.

The recommended way to address this in production systems
is to create a new user or set of users with the permissions
to access the necessary virtual hosts. This can be done
using [CLI tools](/cli.html), [HTTP API or definitions import](/management.html).

This is configured via the <code>loopback_users</code> item
in the [configuration file](configure.html#configuration-file).

It is possible to allow the <code>guest</code> user to connect
from a remote host by setting the
<code>loopback_users</code> configuration to
<code>none</code>.

A minimalistic [RabbitMQ config file](/configure.html)
which allows remote connections for <code>guest</code> looks like so:

<pre class="lang-ini">
# DANGER ZONE!
#
# allowing remote connections for default user is highly discouraged
# as it dramatically decreases the security of the system. Delete the user
# instead and create a new one with generated secure credentials.
loopback_users = none
</pre>


## <a id="user-management" class="anchor" href="#user-management">Managing Users and Permissions</a>

Users and permissions can be managed using [CLI tools](/cli.html) and definition import (covered below).

### Adding a User

To add a user, use `rabbitmqctl add_user`. It has multiple ways of specifying a [password](/passwords.html):

<pre class="lang-bash">
# will prompt for password, only use this option interactively
rabbitmqctl add_user "username"
</pre>

<pre class="lang-bash">
# Password is provided via standard input.
# Note that certain characters such as $, &, #, and so on must be escaped to avoid
# special interpretation by the shell.
echo '<PASSWORD>' | rabbitmqctl add_user 'username'
</pre>

<pre class="lang-bash">
# Password is provided as a command line argument.
# Note that certain characters such as $, &, #, and so on must be escaped to avoid
# special interpretation by the shell.
rabbitmqctl add_user 'username' '<PASSWORD>'
</pre>

On Windows, `rabbitmqctl` becomes `rabbitmqctl.bat` and shell escaping would be different:

<pre class="lang-powershell">
# password is provided as a command line argument
rabbitmqctl.bat add_user 'username' '<PASSWORD>'
</pre>

### Listing Users

To list users in a cluster, use `rabbitmqctl list_users`:

<pre class="lang-bash">
rabbitmqctl list_users
</pre>

<pre class="lang-powershell"><commit_msg>Make sure to escape $, & and so on in shell examples<commit_after><!--
Copyright (c) 2007-2020 VMware, Inc. or its affiliates.

All rights reserved. This program and the accompanying materials
are made available under the terms of the under the Apache License,
Version 2.0 (the "License”); you may not use this file except in compliance
with the License. You may obtain a copy of the License at

https://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->

# Authentication, Authorisation, Access Control

## <a id="overview" class="anchor" href="#overview">Overview</a>

This document describes [authentication](#authentication) and [authorisation](#authorisation) features
in RabbitMQ. Together they allow the operator to control access to the system.
Different users can be granted access only to specific [virtual hosts](/vhosts.html). Their
permissions in each virtual hosts also can be limited.

RabbitMQ supports two major [authentication mechanisms](#mechanisms)
as well as several [authentication and authorisation backends](#backends).

[Password-based](/passwords.html) authentication has a companion guide.
A closely related topic of [TLS support](/ssl.html) is also covered in a dedicated guide.

Other topics discussed in this guide include:

 * [Access control essentials](#the-basics)
 * [Default virtual host and user](#default-state)
 * [Connectivity limitations](#loopback-users) imposed on the default user
 * How to [manage users and permissions](#user-management) using CLI tools
 * How to [pre-create users](#seeding) and their permissions
 * Troubleshooting of [authentication](#troubleshooting-authn) and [authorisation failures](#troubleshooting-authz)

## <a id="terminology-and-definitions" class="anchor" href="#terminology-and-definitions">Terminology and Definitions</a>

Authentication and authorisation are often confused or used
interchangeably. That's wrong and in RabbitMQ, the two are
separated. For the sake of simplicity, we'll define
authentication as "identifying who the user is" and
authorisation as "determining what the user is and isn't allowed to do."


## <a id="basics" class="anchor" href="#basics">The Basics</a>

Clients use RabbitMQ features to [connecting](/connections.html) to it. Every connection has
an associated user which is authenticated. It also targets a [virtual host](/vhosts.html) for which
the user must have a certain set of permissions.

User credentials, target virtual host and (optionally) client [certificate](/ssl.html) are specified at connection
initiation time.

There is a default pair of credentials called the [default user](#default-state). This user can only
be [used for **host-local connections**](#loopback-users) by default. Remote connections that use
it will be refused.

[Production environments](/production-checklist.html) should not use the default user and create
new user accounts with generated credentials instead.


## <a id="default-state" class="anchor" href="#default-state">Default Virtual Host and User</a>

When the server first starts running, and detects that its
database is uninitialised or has been deleted, it
initialises a fresh database with the following resources:

 * a [virtual host](/vhosts.html) named <code>/</code> (a slash)
 * a user named <code>guest</code> with a default password of <code>guest</code>, granted full access to the <code>/</code> virtual host

It is advisable to [delete](rabbitmqctl.8.html#delete_user)
the <code>guest</code> user or at least [change its password](rabbitmqctl.8.html#change_password)
to reasonably secure generated value that won't be known to the public.


## <a id="authentication" class="anchor" href="#authentication">Authentication: Who Do You Say You Are?</a>

After an application connects to RabbitMQ and before it can perform operations, it must
authenticate, that is, present and prove its identity. With that identity, RabbitMQ nodes can
look up its permissions and [authorize](#authorisation) access to resources
such as [virtual hosts](/vhosts.html), queues, exchanges, and so on.

Two primary ways of authenticating a client are [username/password pairs](/passwords.html)
and [X.509 certificates](https://en.wikipedia.org/wiki/X.509). Username/password pairs
can be used with a variety of [authentication backends](#backends) that verify the credentials.

Connections that fail to authenticate will be closed with an error message in the [server log](/logging.html).

To authenticate client connections using X.509 certificate a built-in plugin,
[rabbitmq-auth-mechanism-ssl](https://github.com/rabbitmq/rabbitmq-auth-mechanism-ssl),
must be enabled and clients must be [configured to use the EXTERNAL mechanism](#mechanisms).
With this mechanism, any client-provided password will be ignored.


## <a id="loopback-users" class="anchor" href="#loopback-users">"guest" user can only connect from localhost</a>

By default, the <code>guest</code> user is prohibited from
connecting from remote hosts; it can only connect over
a loopback interface (i.e. <code>localhost</code>). This
applies to [connections regardless of the protocol](/connections.html).
Any other users will not (by default) be restricted in this way.

The recommended way to address this in production systems
is to create a new user or set of users with the permissions
to access the necessary virtual hosts. This can be done
using [CLI tools](/cli.html), [HTTP API or definitions import](/management.html).

This is configured via the <code>loopback_users</code> item
in the [configuration file](configure.html#configuration-file).

It is possible to allow the <code>guest</code> user to connect
from a remote host by setting the
<code>loopback_users</code> configuration to
<code>none</code>.

A minimalistic [RabbitMQ config file](/configure.html)
which allows remote connections for <code>guest</code> looks like so:

<pre class="lang-ini">
# DANGER ZONE!
#
# allowing remote connections for default user is highly discouraged
# as it dramatically decreases the security of the system. Delete the user
# instead and create a new one with generated secure credentials.
loopback_users = none
</pre>


## <a id="user-management" class="anchor" href="#user-management">Managing Users and Permissions</a>

Users and permissions can be managed using [CLI tools](/cli.html) and definition import (covered below).

### Adding a User

To add a user, use `rabbitmqctl add_user`. It has multiple ways of specifying a [password](/passwords.html):

<pre class="lang-bash">
# will prompt for password, only use this option interactively
rabbitmqctl add_user "username"
</pre>

<pre class="lang-bash">
# Password is provided via standard input.
# Note that certain characters such as &#36;, &amp;, &#38;, &#35;, and so on must be escaped to avoid
# special interpretation by the shell.
echo '<PASSWORD>' | rabbitmqctl add_user 'username'
</pre>

<pre class="lang-bash">
# Password is provided as a command line argument.
# Note that certain characters such as &#36;, &amp;, &#38;, &#35;, and so on must be escaped to avoid
# special interpretation by the shell.
rabbitmqctl add_user 'username' '<PASSWORD>'
</pre>

On Windows, `rabbitmqctl` becomes `rabbitmqctl.bat` and shell escaping would be different:

<pre class="lang-powershell">
# password is provided as a command line argument
rabbitmqctl.bat add_user 'username' '<PASSWORD>'
</pre>

### Listing Users

To list users in a cluster, use `rabbitmqctl list_users`:

<pre class="lang-bash">
rabbitmqctl list_users
</pre>

<pre class="lang-powershell">
{'fraction_non_alphanumeric': 0.09299788203581284, 'fraction_numerical': 0.003722482510750273, 'mean_word_length': 5.329000812347685, 'pattern_counts': {'":': 0, '<': 113, '<?xml version=': 0, '>': 113, 'https://': 6, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7283192', 'n_tokens_mistral': 4315, 'n_tokens_neox': 4060, 'n_words': 1898}