Secure your MariaDB MaxScale deployment with authenticators. These modules manage client authentication with backend servers, supporting diverse mechanisms for enhanced security.
Ed25519 is a highly secure authentication method based on public key cryptography. It is used with the auth_ed25519-plugin of MariaDB Server.
When a client authenticates via ed25519, MaxScale first sends them a random message. The client signs the message using their password as private key and sends the signature back. MaxScale then checks the signature using the public key fetched from the mysql.user-table. The client password or an equivalent token is never exposed. For more information, seeserver documentation.
The security of this authentication scheme presents a problem for a proxy such as MaxScale since MaxScale needs to log in to backend servers on behalf of the client. Since each server will generate their own random messages, MaxScale cannot simply forward the original signature. Either the real password is required, or a different authentication scheme must be used between MaxScale and backends. The MaxScale ed25519auth-plugin supports both alternatives.
To begin, add "ed25519auth" to the list of authenticators for a listener.
[Read-Write-Listener]
type=listener
address=::
service=Read-Write-Service
authenticator=ed25519authMaxScale will now authenticate incoming clients with ed25519 if their user account has plugin set to "ed25519" in the mysql.user-table. However, routing queries will fail since MaxScale cannot authenticate to backends. To continue, either use a mapping file or enable sha256-mode. Sha256-mode is enabled with the following settings.
ed_modeThis setting defines the authentication mode used. Two values are supported:
ed25519 (default) Digital signature based authentication. Requires mapping
for backend support.
sha256 Authenticate client with caching_sha2_password-plugin instead.
Requires either SSL or configured RSA-keys.
authenticator_options=ed_mode=sha256ed_rsa_privkey_path and ed_rsa_pubkey_pathDefines the RSA-keys used for encrypting the client password if SSL is not in use. Should point to files with the private and public keys.
authenticator_options=ed_mode=sha256,
ed_rsa_privkey_path=/tmp/sha_private_key.pem,
ed_rsa_pubkey_path=/tmp/sha_public_key.pemTo enable MaxScale to authenticate to backends,user mapping can be used. The mapping and backend passwords are given in a json-file. The client can map to an identical username or to another user, and the backend authentication scheme can be something else than ed25519.
The following example maps user "alpha" to "beta" and MaxScale then uses standard authentication to log into backends as "beta". User "alpha" authenticates to MaxScale using whatever method configured in the server. User "gamma" does not map to another user, just the password is given.
MaxScale configuration:
[Read-Write-Listener]
type=listener
address=::
service=Read-Write-Service
authenticator=ed25519auth,mariadbauth
user_mapping_file=/home/joe/mapping.json/home/joe/mapping.json:
{
"user_map": [
{
"original_user": "alpha",
"mapped_user": "beta"
},
{
"original_user": "gamma",
"mapped_user": "gamma"
}
],
"server_credentials": [
{
"mapped_user": "beta",
"password": "hunter2",
"plugin": "mysql_native_password"
},
{
"mapped_user": "gamma",
"password": "letmein",
"plugin": "ed25519"
}
]
}The mapping-based solution requires the DBA to maintain a file with user passwords, which has security and upkeep implications. To avoid this, MaxScale can instead use the caching_sha2_password-plugin to authenticate the client. This authentication scheme transmits the client password to MaxScale in full, allowing MaxScale to log into backends using ed25519. MaxScale effectively lies to the client about its authentication plugin and then uses the correct plugin with the backends. Enable sha256-authentication by setting authentication option ed_mode to "sha256".
sha256-authentication is best used with encrypted connections. The example below shows a listener configured for sha256-mode and SSL.
[Read-Write-Listener]
type=listener
address=::
service=Read-Write-Service
authenticator=ed25519auth
authenticator_options=ed_mode=sha256
ssl=true
ssl_key=/tmp/my-key.pem
ssl_cert=/tmp/my-cert.pem
ssl_ca=/tmp/myCA.pemIf SSL is not in use, caching_sha2_password transmits the password using RSA-encryption. In this case, MaxScale needs the public and private RSA-keys. MaxScale sends the public key to the client if they don't already have it and the client uses it to encrypt the password. MaxScale then uses the private key to decrypt the password. The example below shows a listener configured for sha256-mode without SSL.
[Read-Write-Listener]
type=listener
address=::
service=Read-Write-Service
authenticator=ed25519auth
authenticator_options=ed_mode=sha256,
ed_rsa_privkey_path=/tmp/sha_private_key.pem,
ed_rsa_pubkey_path=/tmp/sha_public_key.pemThe keyfiles can be generated with OpenSSL using the following commands.
openssl genrsa -out sha_private_key.pem 2048
openssl rsa -in sha_private_key.pem -pubout -out sha_public_key.pemThis page is licensed: CC BY-SA / Gnu FDL
GSSAPI is an authentication protocol that is commonly implemented with Kerberos on Unix or Active Directory on Windows. This document describes GSSAPI authentication in MaxScale. The authentication module name in MaxScale isGSSAPIAuth.
For Unix systems, the usual GSSAPI implementation is Kerberos. This is a short guide on how to set up Kerberos for MaxScale.
The first step is to configure MariaDB to use GSSAPI authentication. The MariaDB documentation for theGSSAPI Authentication Plugin is a good example on how to set it up.
The next step is to copy the keytab file from the server where MariaDB is
installed to the server where MaxScale is located. The keytab file must be
placed in the configured default location which almost always is/etc/krb5.keytab. Alternatively, the keytab filepath can be given as an
authenticator option.
The location of the keytab file can be changed with the KRB5_KTNAME environment variable: keytab_def.html
To take GSSAPI authentication into use, add the following to the listener.
authenticator=GSSAPIAuth
authenticator_options=principal_name=mariadb/localhost.localdomain@EXAMPLE.COMThe principal name should be the same as on the MariaDB servers.
principal_nameType: string
Mandatory: No
Dynamic: No
Default: mariadb/localhost.localdomain
The service principal name to send to the client. This parameter is a string parameter which is used by the client to request the token.
This parameter must be the same as the principal name that the backend MariaDB server uses.
gssapi_keytab_pathType: path
Mandatory: No
Dynamic: No
Default: Kerberos Default
Keytab file location. This should be an absolute path to the file containing the
keytab. If not defined, Kerberos will search from a default location, usually/etc/krb5.keytab. This path is set to an environment variable. This means that
multiple listeners with GSSAPIAuth will override each other. If using multiple
GSSAPI authenticators, either do not set this option or use the same value for
all listeners.
authenticator_options=principal_name=mymariadb@EXAMPLE.COM,gssapi_keytab_path=/home/user/mymariadb.keytabRead the Authentication Modules document for more details on how authentication modules work in MaxScale.
The GSSAPI plugin authentication starts when the database server sends the
service principal name in the AuthSwitchRequest packet. The principal name will
usually be in the form service@REALM.COM.
The client searches its local cache for a token for the service or may request it from the GSSAPI server. If found, the client sends the token to the database server. The database server verifies the authenticity of the token using its keytab file and sends the final OK packet to the client.
The GSSAPI authenticator modules require the GSSAPI development libraries (krb5-devel on CentOS 7).
This page is licensed: CC BY-SA / Gnu FDL
The MariaDBAuth-module implements the client and backend authentication for the server plugin mysql_native_password. This is the default authentication plugin used by both MariaDB and MySQL.
The following settings may be given in the authenticator_options of the listener.
clear_pw_passthroughBoolean, default value is "false". Activates passthrough-mode. In this mode, MaxScale does not check client credentials at all and defers authentication to the backend server. It may be useful in any situation where MaxScale cannot check the existence of client user account nor authenticate the client.
When a client connects to a listener with this setting enabled, MaxScale will change authentication method to "mysql_clear_password", causing the client to send their cleartext password to MaxScale. MaxScale will then attempt to use the password to authenticate to backends. The authentication result of the first backend to respond will be sent to the client. The backend may ask MaxScale for either cleartext password or standard ("mysql_native_password") authentication token. MaxScale can work with both backend plugins since it has the original password.
This feature is incompatible with service setting lazy_connect. Either leave
it unspecified or set lazy_connect=false in the linked service. Also,
multiple client authenticators are not allowed on the listener when
passthrough-mode is on.
Because passwords are sent in cleartext, the listener should be configured for ssl.
[MyListener]
type=listener
authenticator=mariadbauth
authenticator_options=clear_pw_passthrough=true
ssl=true
<other options>log_password_mismatchType: boolean
Mandatory: No
Dynamic: No
Default: false
The service setting log_auth_warnings must also be enabled for this setting to have effect. When both settings are enabled, password hashes are logged if a client gives a wrong password. This feature may be useful when diagnosing authentication issues. It should only be enabled on a secure system as the logging of password hashes may be a security risk.
cache_dirDeprecated and ignored.
inject_service_userDeprecated and ignored.
This page is licensed: CC BY-SA / Gnu FDL
Pluggable authentication module (PAM) is a general purpose authentication API.
An application using PAM can authenticate a user without knowledge about the
underlying authentication implementation. The actual authentication scheme is
defined in the operating system PAM config (e.g. /etc/pam.d/), and can be
quite elaborate. MaxScale supports a very limited form of the PAM protocol,
which this document details.
The MaxScale PAM module requires little configuration. All that is required is to change the listener authenticator module to "PAMAuth".
[Read-Write-Listener]
type=listener
address=::
service=Read-Write-Service
authenticator=PAMAuth
[Primary-Server]
type=server
address=123.456.789.10
port=12345MaxScale uses the PAM authenticator plugin to authenticate users with plugin set to "pam" in the mysql.user-table. The PAM service name of a user is read from the authentication_string-column. The matching PAM service in the operating system PAM config is used for authenticating the user. If theauthentication_string for a user is empty, the fallback service "mysql" is used.
PAM service configuration is out of the scope of this document, seeThe Linux-PAM System Administrators' Guide for more information. A simple service definition used for testing this module is below.
auth required pam_unix.so
account required pam_unix.sopam_use_cleartext_pluginType: boolean
Mandatory: No
Dynamic: No
Default: false
If enabled, MaxScale communicates with the client as if usingmysql_clear_password. This setting has no effect on MaxScale-to-backend communication, which adapts to either "dialog" or "mysql_clear_password", depending on which one the backend suggests. This setting is meant to be used with the similarly named MariaDB Server setting.
authenticator_options=pam_use_cleartext_plugin=1pam_modeType: enumeration
Mandatory: No
Dynamic: No
Values: password, password_2FA, suid
Default: password
This setting defines the authentication mode used. Two values are supported:
password Normal password-based authentication
password_2FA Password + 2FA-code based authentication
suid Authenticate using suid sandbox subprocess
authenticator_options=pam_mode=password_2FAIf set to password_2FA, any users authenticating via PAM will be asked two passwords ("Password" and "Verification code") during login. MaxScale uses the normal password when either the local PAM api or a backend asks for "Password". MaxScale answers any other password prompt (e.g. "Verification code") with the second password. Seethe limitations section for more details. Two-factor mode is incompatible withpam_use_cleartext_plugin.
If set to suid, MaxScale will launch a separate subprocess for every client to
handle pam authentication. This subprocess runs the binarymaxscale_pam_auth_tool (installed in the binary directory), which calls the
system pam libraries. The binary is installed with the SUID bit set, which means
that it runs with root-privileges regardless of the user launching it. This
should bypass any file grant issues (e.g. reading etc/shadow) that may arise
with the password or password_2FA options. The suid-option may also
perform faster if many clients authenticate with pam simultaneously due
to better separation of clients. It may also resist buggy pam plugins crashing,
as the crash would be limited to the subprocess only. The MariaDB Server uses
a similar pam authentication scheme. suid-mode supports two-factor
authentication.
pam_backend_mappingType: enumeration
Mandatory: No
Dynamic: No
Values: none, mariadb
Default: none
Defines backend authentication mapping, i.e. switch of authentication method between client-to-MaxScale and MaxScale-to-backend. Supported values:
none No mapping
mariadb Map users to normal MariaDB accounts
authenticator_options=pam_backend_mapping=mariadbIf set to "mariadb", MaxScale will authenticate clients to backends using
standard MariaDB authentication. Authentication to MaxScale itself still uses
PAM. MaxScale asks the local PAM system if the client username was mapped
to another username during authentication, and use the mapped username when
logging in to backends. Passwords for the mapped users can be given in a file,
see pam_mapped_pw_file below. If passwords are not given, MaxScale will try to
authenticate without a password. Because of this, normal PAM users and mapped
users cannot be used on the same listener.
Because the client still needs to authenticate to MaxScale normally, an anonymous user may be required. If the backends do not allow such a user, one can be manually added using the service settinguser_accounts_file.
To map usernames, the PAM service needs to use a module such aspam_user_map.so. This module is not a standard Linux component and needs to be installed separately. It is included in recent MariaDB Server packages and can also be compiled from source. Seeuser mapping for more information on how to configure the module. If the goal is to only map users from PAM to MariaDB in MaxScale, then configuring user mapping on just the machine running MaxScale is enough.
Instead of using pam_backend_mapping, consider using the listener settinguser_mapping_file,
as it is easier to configure. pam_backend_mapping should only be used when
the user mapping needs to be defined by pam.
pam_mapped_pw_fileType: path
Mandatory: No
Dynamic: No
Default: None
Path to a json-text file with user passwords. Default value is empty, which disables the feature.
authenticator_options=pam_mapped_pw_file=/home/root/passwords.json,pam_backend_mapping=mariadbThis feature only works together with pam_backend_mapping=mariadb. The file is
only read during listener creation (typically MaxScale start) or when a listener
is modified during runtime. The file should contain passwords for the mapped
users. When a client is authenticating, MaxScale searches the password data for a
matching username. If one is found, MaxScale uses the supplied password when
logging in to backends. Otherwise, MaxScale tries to authenticate without a
password.
One array, "users_and_passwords", is read from the file. Each array element in the array must define the following fields:
"user": String. Mapped client username.
"password": String. Backend server password. Can be encrypted with maxpasswd.
An example file is below.
{
"users_and_passwords": [
{
"user": "my_mapped_user1",
"password": "my_mapped_pw1"
},
{
"user": "my_mapped_user2",
"password": "A6D4C53619FFFF4DF252A0E595EDB0A12CA44E16AF154D0ED08F687E81604BFF42218B4EBA9F3EF8D907CF35E74ABDAA"
}
]
}When backend authenticator mapping is not in use
(authenticator_options=pam_backend_mapping=none), the PAM authenticator
supports a limited version ofuser mapping.
It requires less configuration but is also less accurate than proper mapping.
Anonymous mapping is enabled in MaxScale if the following user exists:
Empty username (e.g. ''@'%' or ''@'myhost.com')
plugin = 'pam'
Proxy grant is on (The query SHOW GRANTS FOR user@host; returns at least one
row with GRANT PROXY ON ...)
When the authenticator detects such users, anonymous account mapping is enabled
for the hosts of the anonymous users. To verify this, enable the info log
(log_info=1 in MaxScale config file). When a client is logging in using the
anonymous user account, MaxScale will log a message starting with "Found
matching anonymous user ...".
When mapping is on, the MaxScale PAM authenticator does not require client
accounts to exist in the mysql.user-table received from the backend. MaxScale
only requires that the hostname of the incoming client matches the host field of
one of the anonymous users (comparison performed using LIKE). If a match is
found, MaxScale attempts to authenticate the client to the local machine with
the username and password supplied. The PAM service used for authentication is
read from the authentication_string-field of the anonymous user. If
authentication was successful, MaxScale then uses the username and password to
log to the backends.
Anonymous mapping is only attempted if the client username is not found in themysql.user-table as explained in Configuration. This means,
that if a user is found and the authentication fails, anonymous authentication
is not attempted even when it could use a different PAM service with a different
outcome.
Setting up PAM group mapping for the MariaDB server is a more involved process as the server requires details on which Unix user or group is mapped to which MariaDB user. Seethis guide for more details. Performing all the steps in the guide also on the MaxScale machine is not required, as the MaxScale PAM plugin only checks that the client host matches an anonymous user and that the client (with the username and password it provided) can log into the local PAM configuration. If using normal password authentication, simply generating the Unix user and password should be enough.
The general PAM authentication scheme is difficult for a proxy such as MaxScale. An application using the PAM interface needs to define a conversation function to allow the OS PAM modules to communicate with the client, possibly exchanging multiple messages. This works when a client logs in to a normal server, but not with MaxScale since it needs to autonomously log into multiple backends. For MaxScale to successfully log into the servers, the messages and answers need to be predefined. The passwords given to MaxScale need to work as is when MaxScale logs into the backends. This requirement prevents the use of one-time passwords.
The MaxScale PAM authentication module supports two password modes. In normal mode, client authentication begins with MaxScale sending an AuthSwitchRequest packet. In addition to the command, the packet contains the client plugin name ("dialog" or "mysql_clear_password"), a message type byte (4) and the message "Password: ". In the next packet, the client should send the password, which MaxScale will forward to the PAM api running on the local machine. If the password is correct, an OK packet is sent to the client. If the local PAM api asks for additional credentials as is typical in two-factor authentication schemes, authentication fails. Informational messages such as password expiration notifications are allowed. These are simply printed to the log.
On the backend side, MaxScale expects the servers to act as MaxScale did towards the client. The servers should send an AuthSwitchRequest packet as defined above, MaxScale responds with the password received by the client authenticator and finally backend replies with OK. Informational messages from backends are only printed to the info-log.
MaxScale supports a limited form of two-factor authentication with thepam_mode=password_2FA-option. Since MaxScale uses the 2FA-code given by the
client to log in to the local PAM api as well as all the backends, the code must
be reusable. This prevents the use of any kind of centrally checked one-use
codes. Time-based codes work, assuming the backends are checking the codes
independently of each other. Automatic reconnection features (e.g.
readwritesplit-router) will not work, as the code has likely changed since
original authentication.
Optionally, the PAM configuration on the backend servers can be weakened such that the servers only asks for the normal password. This way, MaxScale will check the 2FA-code of the incoming client, while MaxScale logs into the backends using only the password.
Due to technical reasons, MaxScale does not forward the password prompts from the PAM api to the client. MaxScale will always ask for "Password" and "Verification code", even if the PAM api asks for other items. This prevents the use of authentication schemes where a specific question must be answered (e.g. "Input code Nr. 5"). This is not a significant limitation, as such schemes would not work with backend servers anyway.
MaxScale binary directory contains the test_pam_login-executable. This simple program asks for a username, password and PAM service and then uses the given credentials to login to the given service. test_pam_login uses the same code as MaxScale itself to communicate with the OS PAM interface and may be useful for diagnosing PAM login issues.
This page is licensed: CC BY-SA / Gnu FDL