This document describes general MySQL protocol authentication in MaxScale. For REST-api authentication, see the configuration guide and the REST-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 are standard MySQL password, GSSAPI, ed25519, PARSEC and pluggable 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.

User account management

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 primary 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 the for users_refresh_time, users_refresh_interval and auth_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.

Required grants

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, global_priv and roles_mapping. The user should also have the SHOW DATABASES-grant.

The SET USER grant is optional but recommended if MaxScale is used with MariaDB version 12 or newer. Granting it to the service user allows the backend authentication to use the service credentials to log in after which the final user account is selected using the SET SESSION AUTHORIZATION command. For more information, refer to the documentation of the setting.

If using MariaDB ColumnStore, the following grant is required:

Limitations and troubleshooting

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:

1. Duplicate user accounts. For every user account with a restricted hostname an equivalent user account for MaxScale is added ('alice'@'maxscale-ip').

2. Use .

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.

See for additional information on how to solve authentication issues.

Wildcard database grants

MaxScale supports wildcards _ and % for database-level grants. As with MariaDB Server, grant select on test_.* to 'alice'@'%'; gives access to test_ 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 the test_.t1-table, not to test1.t1.

Settings

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.

skip_authentication

• Type:

• 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.

match_host

• Type:

• 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 with_jdoe@maxscale-IP_, the user can still connect from any client IP but will be forced to go through MaxScale.

lower_case_table_names

• Type: 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 setting 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. Using lower_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.

_{This page is licensed: CC BY-SA / Gnu FDL}

Overview

In MariaDB MaxScale, authenticators perform the following tasks:

• Authenticating clients that connect to MaxScale

• Authenticating connections to back-end MariaDB Enterprise Server and MariaDB Xpand nodes

• Deciding how authentication should be performed

Authenticators Supported by MaxScale

Overview

MaxScale's Native Authenticator is compatible with MariaDB Enterprise Server and MariaDB Xpand. It authenticates database users with the mysql_native_password .

_{This page is: Copyright © 2025 MariaDB. All rights reserved.}

Securing Your MaxScale Deployment

The following hardening steps are recommended before going into production:

• Encrypt plaintext passwords

• Secure GUI & Admin Interface Connections

• Change Admin User & Password

• Enable Audit Logging

• Encrypt Incoming Database Connections

• Encrypt Outgoing Database Connections

Encrypt Plaintext Passwords

MaxScale configuration includes credentials MaxScale uses to e.g. monitor database servers. By default, the passwords are written in plaintext in the configuration file, which exposes them to being accidentally shared. Reduce this risk by encrypting the passwords. Generate an encryption key with the maxkeys-command and then convert plaintext passwords to encrypted form with the maxpasswd-command.

Run maxkeys to generate a key file in /var/lib/maxscale. File ownership is given to the maxscale user and only the owner has read-permissions to the file.

Once generated, the key file can be relocated to a secure location. This key file serves a dual purpose: it enables the encryption of passwords and decrypting those encrypted passwords. Typically, the MaxScale administrator encrypts passwords and MaxScale itself decrypts them when required.

The key file must remain secure to maintain the security of the encrypted passwords. If an attacker can read the contents of the key file, they can also decrypt any passwords read from the configuration file. Use chown and chmod to restrict access.

Encrypt plaintext passwords used in MaxScale configuration with maxpasswd.

Replace the plaintext passwords in your MaxScale configuration (CNF) files with the encrypted versions. This enhances overall security by reducing the risk that passwords are accidentally shared.

See for more information regarding password encryption.

Secure GUI & Admin Interface Connections

MaxScale is managed during runtime through the REST-API admin interface. This interface is used by the GUI and the MaxCtrl utility. It can even be accessed using curl. By default, the admin interface only accepts local connections. If you need to allow external access, modify the admin_host setting to change the network the admin interface listens on. To mitigate the security risk of external access, you can change the listening port to a non-default value.

If you need to allow external access, ensure that the network is adequately secured and that only authorized users can access the MaxScale interface. Consult with your network administrator to determine the most appropriate and secure configuration.

Enable TLS Encryption

To properly secure the MaxScale REST-API, enable TLS encryption for data in transit. Follow these steps to configure SSL:

1. Generate SSL key and certificate:

• See for information on certificate creation.

• Move the generated files to a secure location MaxScale can access.

2. Update MaxScale configuration:

• Enable secure connections by setting admin_secure_gui to true.

• Specify the paths to the SSL certificate and key files in your CNF file:

3. Verify Encryption:

• Use maxctrl to verify that TLS encryption is functioning correctly:

Change Admin User & Password

The REST-API is initially configured to be accessed with username admin and password mariadb. Any attacker would try these credentials first, so create a new user account and delete the default one.

To create or delete REST-API users, use the maxctrl-command. To create a user with administrative privileges, run:

The password must be in cleartext.

To remove an existing user, such as the default admin user, use the following command:

After these commands, MaxCtrl will no longer work unless you define credentials either on the command line or in a config file. See for more information.

REST-API user accounts have one of two roles: admin and basic. admin allows full read and write access, basic only allows reading.

REST-API user accounts can also be managed through the GUI.

Enable Audit Logging

Admin auditing in MaxScale provides comprehensive tracking of all administrative activities, including logins, connections, and modifications. These activities are recorded in an audit file for enhanced security and traceability.

To enable admin auditing, add the following configuration to your MaxScale configuration file:

This configuration activates auditing and specifies the location of the audit file. Ensure that the specified directory exists before restarting MaxScale.

Implement log rotation to manage the size and number of audit files. This can be achieved using standard Linux log rotation tools. See

For manual log rotation, use the following MaxCtrl command:

Encrypt Incoming Database Connections

Incoming database connections are the connections clients make to MaxScale. Without encryption, an eavesdropper can listen to the client queries and server responses. To enable encryption, MaxScale listeners need to be configured for TLS.

1. Enable TLS:

Add ssl=true to the listener section in your MaxScale configuration file. This enforces encrypted connections from incoming clients. The listener also requires a certificate and its private key, configured with settings ssl_cert and ssl_key. If using a X509v3 certificate with extendedKeyUsage extension settings, the serverAuth flag should be set in the certificate.

The listener section should look like:

In MaxScale 25.10, the ssl_cert and ssl_key settings can be omitted, which causes MaxScale to generate a self-signed certificate during startup. Recent client versions (11.4 and later) can even verify this auto-generated certificate.

For more information on SSL settings, see

2. Verify client certificates

If you want MaxScale to verify client certificates against a CA-certificate, set ssl_verify_peer_certificate=true and define the CA-certificate with ssl_ca.

Encrypt Outgoing Database Connections

Outgoing database connections are the connections MaxScale makes to MariaDB Servers on behalf of incoming clients. If MaxScale and the servers are running in the same network, and you consider the network already secure, then encrypting these connections may not be necessary. If this is not the case, both MaxScale and the servers need to be configured to use TLS. To configure MariaDB Server for encryption, see .

To enable MaxScale to connect securely to MariaDB Servers:

1. Enable TLS:

Add ssl=true to each server section in your MaxScale configuration file. This enforces encrypted connections to the server.

2. Verify server certificate:

If you want MaxScale to verify the server certificate (to ensure it's signed by a trusted CA), add ssl_verify_peer_certificate=true. The CA certificate path is defined with ssl_ca. This prevents MaxScale from routing queries to a malicious server that has hijacked the address of the real server.

The server section in your MaxScale configuration file should look like:

If you are using MaxScale 25.10 and a recent MariaDB Server version, certificate verification no longer requires a ca-certificate. In this case, the ssl_ca setting can be omitted. See for more information.

3. Configure a pre-generated certificate for connecting to the server

If the MariaDB Server requires clients (such as MaxScale) to connect with a verified certificate, then such a certificate must be defined in the MaxScale configuration, with settings ssl_cert and ssl_key. If using a X509v3 certificate with extendedKeyUsage extension settings, the clientAuth flag should be set in the certificate.

_{This page is licensed: CC BY-SA / Gnu FDL}