MaxScale 2.5 GSSAPI Client Authenticator
GSSAPI Client Authenticator
GSSAPI is an authentication protocol that is commonly implemented with Kerberos on Unix or Active Directory on Windows. This document describes the GSSAPI authentication in MaxScale.
Preparing the GSSAPI system
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 the GSSAPI 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
The location of the keytab file can be changed with the KRB5_KTNAME environment variable: https://web.mit.edu/kerberos/krb5-latest/doc/basic/keytab_def.html
To take GSSAPI authentication into use, add the following to the listener.
Change the principal name to the same value you configured for the MariaDB server.
The client side GSSAPIAuth authenticator supports one option, the service principal name that MaxScale sends to the client. The backend authenticator module has no options.
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. The default value for this option is mariadb/localhost.localdomain.
This parameter must be the same as the principal name that the backend MariaDB server uses.
Read 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
The client will then request a token for this service from the GSSAPI server and send the token to the database server. The database server will verify the authenticity of the token by contacting the GSSAPI server and if the token is authentic, the server sends the final OK packet.
Client side GSSAPI authentication is only supported when the backend connections also use GSSAPI authentication. MaxScale will automatically use the correct authentication mechanism based on what the client authenticates with.
See the Limitations document for more details.
Building the module
The GSSAPI authenticator modules require the GSSAPI development libraries (krb5-devel on CentOS 7).