This document describes general MySQL protocol authentication in MaxScale. For REST-api authentication, see theconfiguration guide and theREST-api guide.
Similar to the MariaDB Server, MaxScale uses authentication plugins to implement different authentication schemes for incoming clients. The same plugins also handle authenticating the clients to backend servers. The authentication plugins available in MaxScale arestandard MySQL password,GSSAPI andpluggable authentication modules (PAM).
Most of the authentication processing is performed on the protocol level, before handing it over to one of the plugins. This shared part is described in this document. For information on an individual plugin, see its documentation.
Every MaxScale service with a MariaDB protocol listener requires knowledge of the user accounts defined on the backend databases. The service maintains this information in an internal component called the user account manager (UAM). The UAM queries relevant data from the mysql-database of the backends and stores it. Typically, only the current master server is queried, as all servers are assumed to have the same users. The service settings user and password define the credentials used when fetching user accounts.
The service uses the stored data when authenticating clients, checking their passwords and database access rights. This results in an authentication process very similar to the MariaDB Server itself. Unauthorized users are generally detected already at the MaxScale level instead of the backend servers. This may not apply in some cases, for example if MaxScale is using old user account data.
If authentication fails, the UAM updates its data from a backend. MaxScale may attempt authenticating the client again with the refreshed data without communicating the first failure to the client. This transparent user data update does not always work, in which case the client should try to log in again.
As the UAM is shared between all listeners of a service, its settings are defined in the service configuration. For more information, search theconfiguration guide for users_refresh_time, users_refresh_interval andauth_all_servers. Other settings which affect how the UAM connects to backends are the global settings auth_connect_timeout and local_address, and the various server-level ssl-settings.
To properly fetch user account information, the MaxScale service user must be able to read from various tables in the mysql-database: user, db,tables_priv, columns_priv, procs_priv, proxies_priv and roles_mapping. The user should also have the SHOW DATABASES-grant.
CREATE USER 'maxscale'@'maxscalehost' IDENTIFIED BY 'maxscale-password';
GRANT SELECT ON mysql.user TO 'maxscale'@'maxscalehost';
GRANT SELECT ON mysql.db TO 'maxscale'@'maxscalehost';
GRANT SELECT ON mysql.tables_priv TO 'maxscale'@'maxscalehost';
GRANT SELECT ON mysql.columns_priv TO 'maxscale'@'maxscalehost';
GRANT SELECT ON mysql.procs_priv TO 'maxscale'@'maxscalehost';
GRANT SELECT ON mysql.proxies_priv TO 'maxscale'@'maxscalehost';
GRANT SELECT ON mysql.roles_mapping TO 'maxscale'@'maxscalehost';
GRANT SHOW DATABASES ON *.* TO 'maxscale'@'maxscalehost';If using MariaDB ColumnStore, the following grant is required:
GRANT ALL ON infinidb_vtable.* TO 'maxscale'@'maxscalehost';When a client logs in to MaxScale, MaxScale sees the client's IP address. When
MaxScale then connects the client to backends (using the client's username and
password), the backends see the connection coming from the IP address of
MaxScale. If the client user account is to a wildcard host ('alice'@'%'), this
is not an issue. If the host is restricted ('alice'@'123.123.123.123'),
authentication to backends will fail.
There are two primary ways to deal with this:
Duplicate user accounts. For every user account with a restricted hostname an
equivalent user account for MaxScale is added ('alice'@'maxscale-ip').
Use proxy protocol.
Option 1 limits the passwords for user accounts with shared usernames. Such accounts must use the same password since they will effectively share the MaxScale-to-backend user account. Option 2 requires server support.
SeeMaxScale Troubleshooting for additional information on how to solve authentication issues.
MaxScale supports wildcards _ and % for database-level grants. As with
MariaDB Server, grant select on test_.* to 'alice'@'%'; gives access totest_ as well as test1, test2 and so on. If the GRANT command escapes the
wildcard (grant select on test_.* to 'alice'@'%';) both MaxScale and the
MariaDB Server interpret it as only allowing access to test_. _ and %
are only interpreted as wildcards when the grant is to a database:grant select on test_.t1 to 'alice'@'%'; only grants access to thetest_.t1-table, not to test1.t1.
The listener configuration defines authentication options which only affect the listener. authenticator defines the authentication plugins to use.authenticator_options sets various options. These options may affect an individual authentication plugin or the authentication as a whole. The latter are explained below. Multiple options can be given as a comma-separated list.
authenticator_options=skip_authentication=true,lower_case_table_names=1skip_authenticationType: boolean
Mandatory: No
Dynamic: No
Default: false
If enabled, MaxScale will not check the passwords of incoming clients and just assumes that they are correct. Wrong passwords are instead detected when MaxScale tries to authenticate to the backend servers.
This setting is mainly meant for failure tolerance in situations where the password check is performed outside of MaxScale. If, for example, MaxScale cannot use an LDAP-server but the backend databases can, enabling this setting allows clients to log in. Even with this setting enabled, a user account matching the incoming client username and IP must exist on the backends for MaxScale to accept the client.
This setting is incompatible with standard MariaDB/MySQL authentication plugin (MariaDBAuth in MaxScale). If enabled, MaxScale cannot authenticate clients to backend servers using standard authentication.
authenticator_options=skip_authentication=truematch_hostType: boolean
Mandatory: No
Dynamic: No
Default: true
If disabled, MaxScale does not require that a valid user account entry for incoming clients exists on the backends. Specifically, only the client username needs to match a user account, hostname/IP is ignored.
This setting may be used to force clients to connect through MaxScale. Normally, creating the user jdoe@% will allow the user jdoe to connect from any IP-address. By disabling match_host and replacing the user withjdoe@maxscale-IP, the user can still connect from any client IP but will be forced to go through MaxScale.
authenticator_options=match_host=falselower_case_table_namesType: number
Mandatory: No
Dynamic: No
Default: 0
Controls database name matching for authentication when an incoming client logs in to a non-empty database. The setting functions similar to the MariaDB Server settinglower_case_table_names and should be set to the value used by the backends.
The setting accepts the values 0, 1 or 2:
0: case-sensitive matching (default)
1: convert the requested database name to lower case before using case-insensitive
matching. Assumes that database names on the server are stored in lower case.
2: use case-insensitive matching.
true and false are also accepted for backwards compatibility. These map to 1 and 0, respectively.
The identifier names are converted using an ASCII-only function. This means that non-ASCII characters will retain their case-sensitivity.
Starting with MaxScale versions 2.5.25, 6.4.6, 22.08.5 and 23.02.2, the behavior
of lower_case_table_names=1 is identical with how the MariaDB server
behaves. In older releases the comparisons were done in a case-sensitive manner
after the requested database name was converted into lowercase. Usinglower_case_table_names=2 will behave identically in all versions which makes
it a safe alternative to use when a mix of older and newer MaxScale versions is
being used.
authenticator_options=lower_case_table_names=0CC 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).
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.
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.
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
[Master-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 authetication_string-column. The matching PAM service in the operating system PAM config is used for authenticating the user. If theauthetication_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", depeding 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
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
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.
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.
CC BY-SA / Gnu FDL