Authentication Plugin - GSSAPI
MariaDB starting with 10.1.11
The gssapi
authentication plugin was first released in MariaDB 10.1.11.
The gssapi
authentication plugin allows the user to authenticate with services that use the Generic Security Services Application Program Interface (GSSAPI). Windows has a slightly different but very similar API called Security Support Provider Interface (SSPI). The GSSAPI is a standardized API described in RFC2743 and RFC2744. The client and server negotiate using a standardized protocol described in RFC7546.
On Windows, this authentication plugin supports Kerberos and NTLM authentication. Windows authentication is supported regardless of whether a domain is used in the environment.
On Unix systems, the most dominant GSSAPI service is Kerberos. However, it is less commonly used on Unix systems than it is on Windows. Regardless, this authentication plugin also supports Kerberos authentication on Unix.
The gssapi
authentication plugin is most often used for authenticating with Microsoft Active Directory.
This article gives instructions on configuring the gssapi
authentication plugin
for MariaDB for passwordless login.
Contents
If the MariaDB server is running on Windows, then GSSAPI authentication should work with no special configuration, as long as the following is true:
- The Windows server is joined to a domain.
- The MariaDB server process is running as either a NetworkService Account or a Domain User Account.
Unlike on Unix, a service principal is not needed to use GSSAPI authentication on Windows. However, if you want to use one anyway, then one can be created with the setspn
utility.
Creating a Keytab File on a Unix Server
If the MariaDB server is running on Unix, then the KDC server will need to create a keytab file for the MariaDB server. The keytab file contains the service's principal name, which is the identity that the MariaDB server will use to communicate with the KDC server. The keytab will need to be transferred to the MariaDB server, and the mysqld
server process will need read access to this keytab file.
How this keytab file is generated depends on whether the KDC server is MIT Kerberos KDC or Microsoft Active Directory KDC.
Creating a Keytab File with MIT Kerberos
If you are using MIT Kerberos KDC, then you can create a keytab file using the kadmin
utility. To do so, follow the steps listed below.
In the following steps, be sure to replace ${HOST}
with the fully qualified DNS name for the MariaDB server host.
First, create the service principal using the kadmin
utility. For example:
kadmin -q "addprinc -randkey mariadb/${HOST}"
Then, export the newly created user to the keytab file using the kadmin
utility. For example:
kadmin -q "ktadd -k /path/to/mariadb.keytab mariadb/${HOST}"
More details can be found at the following links:
- Create a service principal using MIT Kerberos
- Add a host or service principal to a keytab using MIT Kerberos
Creating a Keytab File with Microsoft Active Directory
If you are using Microsoft Active Directory KDC, then you may need to create a keytab using the ktpass.exe
utility on a Windows host. The service principal will need to be mapped to an existing domain user. To do so, follow the steps listed below.
Be sure to replace the following items in the step below:
- Replace
${HOST}
with the fully qualified DNS name for the MariaDB server host. - Replace
${DOMAIN}
with the Active Directory domain. - Replace
${AD_USER}
with the existing domain user. - Replace
${PASSWORD}
with the password for the service principal.
To create the service principal, execute the following:
ktpass.exe /princ mariadb/${HOST}@${DOMAIN} /mapuser ${AD_USER} /pass ${PASSWORD} /out mariadb.keytab /crypto all /ptype KRB5_NT_PRINCIPAL /mapop set
Installing the Plugin's Package
The gssapi
authentication plugin's shared library is included in MariaDB packages as the auth_gssapi.so
or auth_gssapi.dll
shared library on systems where it can be built. The plugin was first included in MariaDB 10.1.11.
Installing on Linux
The gssapi
authentication plugin is included in binary tarballs on Linux.
Installing with a Package Manager
The gssapi
authentication plugin can also be installed via a package manager on Linux. In order to do so, your system needs to be configured to install from one of the MariaDB repositories.
You can configure your package manager to install it from MariaDB Corporation's MariaDB Package Repository by using the MariaDB Package Repository setup script.
You can also configure your package manager to install it from MariaDB Foundation's MariaDB Repository by using the MariaDB Repository Configuration Tool.
Installing with yum/dnf
On RHEL, CentOS, Fedora, and other similar Linux distributions, it is highly recommended to install the relevant RPM package from MariaDB's
repository using yum
or dnf
. Starting with RHEL 8 and Fedora 22, yum
has been replaced by dnf
, which is the next major version of yum
. However, yum
commands still work on many systems that use dnf
. For example:
sudo yum install MariaDB-gssapi-server
Installing with apt-get
On Debian, Ubuntu, and other similar Linux distributions, it is highly recommended to install the relevant DEB package from MariaDB's
repository using apt-get
. For example:
sudo apt-get install mariadb-plugin-gssapi-server
Installing with zypper
On SLES, OpenSUSE, and other similar Linux distributions, it is highly recommended to install the relevant RPM package from MariaDB's repository using zypper
. For example:
sudo zypper install MariaDB-gssapi-server
Installing on Windows
The gssapi
authentication plugin is included in MSI and ZIP packages on Windows.
Installing the Plugin
Although the plugin's shared library is distributed with MariaDB by default, the plugin is not actually installed by MariaDB by default. There are two methods that can be used to install the plugin with MariaDB.
The first method can be used to install the plugin without restarting the server. You can install the plugin dynamically by executing INSTALL SONAME
or INSTALL PLUGIN
. For example:
INSTALL SONAME 'auth_gssapi';
The second method can be used to tell the server to load the plugin when it starts up. The plugin can be installed this way by providing the --plugin-load
or the --plugin-load-add
options. This can be specified as a command-line argument to mysqld
or it can be specified in a relevant server option group in an option file. For example:
[mariadb] ... plugin_load_add = auth_gssapi
Uninstalling the Plugin
You can uninstall the plugin dynamically by executing UNINSTALL SONAME
or UNINSTALL PLUGIN
. For example:
UNINSTALL SONAME 'auth_gssapi';
If you installed the plugin by providing the --plugin-load
or the --plugin-load-add
options in a relevant server option group in an option file, then those options should be removed to prevent the plugin from being loaded the next time the server is restarted.
Configuring the Plugin
Configuring the Plugin on Unix
Some additional things need to be configured in order to use the plugin on Unix systems.
First, set the gssapi_keytab_path
option in the server's option file to the path of the previously created keytab file.
[mariadb] ... gssapi_keytab_path=/path/to/mariadb.keytab
Next, if the service principal name differs from the default mariadb/host.domain.com@REALM, then
configure an alternative principal name by setting the gssapi_principal_name
option in the server's option file as well.
[mariadb] ... gssapi_principal_name=alternative/principalname@REALM
Creating Users
To create a user account via CREATE USER
, specify the name of the plugin in the IDENTIFIED VIA
clause. For example:
CREATE USER username@hostname IDENTIFIED VIA gssapi;
If SQL_MODE
does not have NO_AUTO_CREATE_USER
set, then you can also create the user account via GRANT
. For example:
GRANT SELECT ON db.* TO username@hostname IDENTIFIED VIA gssapi;
You can also specify the user's realm for MariaDB with the USING
clause. For example:
CREATE USER username@hostname IDENTIFIED VIA gssapi USING '[email protected]';
The format of the realm depends on the specific authentication mechanism that is used. For example, the format would need to be machine\\username
for Windows users authenticating with NTLM.
If the realm is not provided in the user account's definition, then the realm is not used for comparison. Therefore, '[email protected]', '[email protected]' and 'mymachine\usr1' would all identify as the following user account:
CREATE USER usr1@hostname IDENTIFIED VIA gssapi;
Client Authentication Plugins
For clients that use the libmysqlclient
or MariaDB Connector/C libraries, MariaDB provides one client authentication plugin that is compatible with the gssapi
authentication plugin:
auth_gssapi_client
When connecting with a client or utility to a server as a user account that authenticates with the gssapi
authentication plugin, you may need to tell the client where to find the relevant client authentication plugin by specifying the --plugin-dir
option. For example:
mysql --plugin-dir=/usr/local/mysql/lib64/mysql/plugin --user=alice
auth_gssapi_client
The auth_gssapi_client
client authentication plugin receives the principal name from the server, and then uses either the gss_init_sec_context
function (on Unix) or the InitializeSecurityContext
function (on Windows) to establish a security context on the client.
Support in Client Libraries
Using the Plugin with MariaDB Connector/C
MariaDB Connector/C supports gssapi
authentication using the client authentication plugins mentioned in the previous section since MariaDB Connector/C 3.0.1.
Using the Plugin with MariaDB Connector/ODBC
MariaDB Connector/ODBC supports gssapi
authentication using the client authentication plugins mentioned in the previous section since MariaDB Connector/ODBC 3.0.0.
Using the Plugin with MariaDB Connector/J
MariaDB Connector/J supports gssapi
authentication since MariaDB Connector/J 1.4.0. Current documentation can be found here.
Using the Plugin with MariaDB Connector/Node.js
MariaDB Connector/Node.js does not yet support gssapi
authentication. See CONJS-72 for more information.
Using the Plugin with MySqlConnector for .NET
MySqlConnector for ADO.NET supports gssapi
authentication since MySqlConnector 0.47.0.
The support is transparent. Normally, the connector only needs to be provided the correct user name, and no other parameters are required.
However, this connector also supports the ServerSPN
connection string parameter, which can be used for mutual authentication.
.NET specific problems/workarounds
When connecting from Unix client to Windows server with ADO.NET, in an Active Directory domain environment, be aware that .NET Core on Unix does not support principal names in UPN(User Principal Name) form, which is default on Windows (e.g [email protected]) . Thus, upon encountering an authentication exception with "server not found in Kerberos database", use one of workarounds below
- Force host-based SPN on server side.
- For example, this can be done by setting the
gssapi_principal_name
system variable toHOST/machine
in a server option group in an option file.
- For example, this can be done by setting the
- Pass host-based SPN on client side.
- For example, this can be done by setting the connector's
ServerSPN
connection string parameter toHOST/machine
.
- For example, this can be done by setting the connector's
Versions
Version | Status | Introduced |
---|---|---|
1.0 | Stable | MariaDB 10.1.15 |
1.0 | Beta | MariaDB 10.1.11 |
System Variables
gssapi_keytab_path
- Description: Defines the path to the server's keytab file.
- This system variable is only meaningful on Unix.
- See Creating a Keytab File on a Unix Server for more information.
- Commandline:
--gssapi-keytab-path
- Scope: Global
- Dynamic: No
- Data Type:
string
- Default Value: ''
- Introduced: MariaDB 10.1.11
gssapi_principal_name
- Description: Name of the service principal.
- Commandline:
--gssapi-principal-name
- Scope: Global
- Dynamic: No
- Data Type:
string
- Default Value: ''
- Introduced: MariaDB 10.1.11
gssapi_mech_name
- Description: Name of the SSPI package used by server. Can be either 'Kerberos' or 'Negotiate'. Set it to 'Kerberos', to prevent less secure NTLM in domain environments, but leave it as default (Negotiate) to allow non-domain environments (e.g if server does not run in a domain environment).
- This system variable is only meaningful on Windows.
- Commandline:
--gssapi-mech-name
- Scope: Global
- Dynamic: No
- Data Type:
enumerated
- Default Value:
Negotiate
- Valid Values:
Kerberos
,Negotiate
- Introduced: MariaDB 10.1.11
Options
gssapi
- Description: Controls how the server should treat the plugin when the server starts up.
- Valid values are:
OFF
- Disables the plugin without removing it from themysql.plugins
table.ON
- Enables the plugin. If the plugin cannot be initialized, then the server will still continue starting up, but the plugin will be disabled.FORCE
- Enables the plugin. If the plugin cannot be initialized, then the server will fail to start with an error.FORCE_PLUS_PERMANENT
- Enables the plugin. If the plugin cannot be initialized, then the server will fail to start with an error. In addition, the plugin cannot be uninstalled withUNINSTALL SONAME
orUNINSTALL PLUGIN
while the server is running.
- See Plugin Overview: Configuring Plugin Activation at Server Startup for more information.
- Valid values are:
- Commandline:
--gssapi=value
- Data Type:
enumerated
- Default Value:
ON
- Valid Values:
OFF
,ON
,FORCE
,FORCE_PLUS_PERMANENT
- Introduced: MariaDB 10.1.11