Authentication Plugin - GSSAPI

This article gives instructions on configuring the GSSAPI authentication plugin for MariaDB for passwordless login.

On Unix systems, GSSAPI is usually synonymous with Kerberos authentication. Windows has a slightly different but very similar API called SSPI that, along with Kerberos, also supports NTLM authentication.

This plugin includes support for Kerberos on Unix, but can also be used for Windows authentication with or without domain environment.

Versions

Server-side preparation on Unix

To use the plugin, some preparation needs to be done on the server-side on Unix. MariaDB server will need read access to the Kerberos keytab file. This contains the service's principal name for the MariaDB server.

If you are using Unix Kerberos KDC (MIT,Heimdal)

• Create the service principal using kadmin tool

kadmin -q "addprinc -randkey mariadb/host.domain.com"

(replace host.domain.com with fully qualified DNS name for the server host)

• Export the newly created user to the keytab file

kadmin -q "ktadd -k /path/to/mariadb.keytab mariadb/host.domain.com"

More details can be found here and here

If you are using Windows Active Directory KDC you may need to create keytab using ktpass.exe tool on Windows and map the principal user to an existing domain user, as follows:

ktpass.exe /princ mariadb/[email protected] /mapuser someuser /pass MyPas$w0rd /out mariadb.keytab /crypto all /ptype KRB5_NT_PRINCIPAL /mapop set

and then transfer the keytab file to the Unix server. See Microsoft documentation for details.

Server-side preparation on Windows

Usually nothing need to be done. MariaDB server should to run on a domain joined machine, either as a NetworkService account (which is the default if it runs as service) or run under any other domain's account credentials.

Creating service principal is not required here (but you can still do it using the setspn tool)

Installing the plugin

• Start the server

• On Unix, edit the my.cnf/my.ini configuration file, set the parameter gssapi-keytab-path to point to the previously created keytab path.

gssapi-keytab-path=/path/to/mariadb.keytab

• Optionally on Unix, in case the service principal name differs from the default mariadb/host.domain.com@REALM, configure an alternative principal name with

gssapi-principal-name=alternative/principalname@REALM

• In the mysql command line client, execute

INSTALL SONAME 'auth_gssapi'

Creating users

Now you can create a user for GSSAPI/SSPI authentication. The CREATE USER command, for Kerberos users, would be like this (*long* form, see below for short one)

CREATE USER usr1 IDENTIFIED VIA gssapi AS '[email protected]';

(replace with real username and realm)

The part after AS is mechanism specific, and needs to be machine\\usr1 for Windows users identified with NTLM.

You may also use the alternative *short* form of CREATE USER

CREATE USER usr1 IDENTIFIED VIA gssapi;

If this syntax is used, the realm part is *not* used for comparison thus '[email protected]', '[email protected]' and 'mymachine\usr1' will all identify as 'usr1'.

Login as GSSAPI user with command line clients.

Using command line client, do

mysql --plugin-dir=/path/to/plugin-dir -u usr1

Plugin variables

• gssapi-keytab-path (Unix only) - Path to the server keytab file
• gssapi-principal-name - name of the service principal.
• gssapi-mech-name (Windows only) - Name of the SSPI package used by server. Can be either 'Kerberos' or 'Negotiate'. Defaults to 'Negotiate' (both Kerberos and NTLM users can connect) 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).

Using GSSAPI plugin from MariaDB Connector/J

MariaDB Connector/J has supported GSSAPI authentication since version 1.4. Current documentation can be found here.

Support in MySqlConnector ADO.NET data provider

MySqlConnector supports GSSAPI authentication since version 0.47

This driver also support GSSAPI specific ServerSPN connection string parameter, for mutual authentication(see Connection String Options )

.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 (add gssapi-principal-name=HOST/machine to my.ini file)
• Pass host-based SPN on client side ( i.e use ServerSPN=HOST/machine in the connection string)