docs/books/modules/user-guide/connecting-using-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-outgoing-connections.adoc

[id='connecting-using-username-password-authentication-{context}']
= Connecting using user name and password authentication

You can use the SASL PLAIN mechanism to connect to an external AMQP container that requires a user name and password. 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

include::{FragmentDir}/fragment-router-open-config-file-step.adoc[]

. Configure the `connector` for this connection to provide user name and password credentials to the external AMQP container.
+
--
[options="nowrap",subs="+quotes"]
----
connector {
    host: 192.0.2.1
    port: 5672
    role: route-container
    saslMechanisms: PLAIN
    saslUsername: user
    saslPassword: file:/path/to/file/password.txt
    }
----
`saslPassword`:: The password to connect to the peer. By using different prefixes, you can specify the password several different ways depending on your security requirements:
+
* Specify the absolute path to a file that contains the password. This is the most secure option, because you can set permissions on the file that contains the password. For example:
+
[options="nowrap",subs="+quotes"]
----
password: file:/path/to/file/password.txt
----

* Specify an environment variable that stores the password. Use this option with caution, because the environment of other processes is visible on certain platforms. For example:
+
[options="nowrap",subs="+quotes"]
----
password: env:PASSWORD
----

* Specify the password in clear text. This option is insecure, so it should only be used if security is not a concern. For example:
+
[options="nowrap",subs="+quotes"]
----
password: pass:mypassword
----
--