docs/books/modules/user-guide/enabling-username-password-authentication.adoc

////
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements.  See the NOTICE file
distributed with this work for additional information
regarding copyright ownership.  The ASF licenses this file
to you 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

  http://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
////

// Module is included in the following assemblies:
//
// securing-incoming-client-connections.adoc

[id='enabling-username-password-authentication-{context}']
= Enabling user name and password authentication

You can use the SASL PLAIN mechanism to authenticate incoming client connections against a set of user names and passwords. You can use this method by itself, or you can combine it with SSL/TLS encryption.

.Prerequisites

* The `cyrus-sasl-plain` plugin is installed.
+
Cyrus SASL uses plugins to support specific SASL mechanisms. Before you can use a particular SASL mechanism, the relevant plugin must be installed.
+
--
// Note about searching for an installing SASL plugins.
include::{FragmentDir}/fragment-router-sasl-para.adoc[]
--

.Procedure

. If necessary, add the user names and passwords to the SASL database.
+
--
This example adds a new user (\user1@example.com) to the SASL database (qdrouterd.sasldb):

[options="nowrap",subs="+quotes"]
----
$ sudo saslpasswd2 -c -f qdrouterd.sasldb -u example.com user1
----

[NOTE]
====
The full user name is the user name you entered plus the domain name (`__<user-name>__`@`__<domain-name>__`). Providing a domain name is not required when you add a user to the database, but if you do not provide one, a default domain will be added automatically (the hostname of the machine on which the tool is running).
====
--

. Open the `/etc/sasl2/qdrouterd.conf` configuration file.
+
--
This example shows a `/etc/sasl2/qdrouterd.conf` configuration file:

[options="nowrap",subs="+quotes"]
----
pwcheck_method: auxprop
auxprop_plugin: sasldb
sasldb_path: qdrouterd.sasldb
mech_list: ANONYMOUS DIGEST-MD5 EXTERNAL PLAIN GSSAPI
----
--

. Verify that the `mech_list` attribute contains the `PLAIN` mechanism.

. Open the `{RouterConfigFile}` configuration file.

. In the `router` section, specify the path to the SASL configuration file.
+
--
[options="nowrap",subs="+quotes"]
----
router {
    mode: interior
    id: Router.A
    saslConfigDir: /etc/sasl2/
}
----
`saslConfigDir`:: The absolute path to the SASL configuration file that contains the path to the SASL database that stores the user names and passwords.
--

. Configure the `listener` for this connection to authenticate clients using SASL PLAIN.
+
--
This example configures basic user name and password authentication for a `listener`. In this case, no SSL/TLS encryption is being used.

[options="nowrap",subs="+quotes"]
----
listener {
    host: 0.0.0.0
    port: 5672
    authenticatePeer: yes
    saslMechanisms: PLAIN
    }
----
--