X
Search
Products
Services
Resources
About
Contact
Login
Copyright © 2019 MariaDB. All rights reserved.
Knowledge Base
Contact
Login
Search
Products
Services
Pricing
Resources
About Us
Download
Home
»
Resources
»
Knowledge Base
»
Library
»
MariaDB Server Documentation
»
Columns, Storage Engines, and Plugins
»
Plugins
»
Authentication Plugins
»
Authentication Plugin - GSSAPI
Authentication Plugin - GSSAPI - Source
Revision
78239
User
Vladislav Vaintroub
Date
2019-01-19 00:43
<<product mariadb from=10.1.11>> The ##gssapi## authentication plugin was first released in MariaDB 10.1.11. <</product>> The ##gssapi## authentication plugin allows the user to authenticate with services that use the [[https://en.wikipedia.org/wiki/Generic_Security_Services_Application_Program_Interface|Generic Security Services Application Program Interface (GSSAPI)]]. Windows has a slightly different but very similar API called [[https://docs.microsoft.com/en-us/windows/desktop/secauthn/sspi|Security Support Provider Interface (SSPI)]]. On Windows, this authentication plugin supports [[https://docs.microsoft.com/en-us/windows/desktop/secauthn/microsoft-kerberos|Kerberos]] and [[https://docs.microsoft.com/en-us/windows/desktop/secauthn/microsoft-ntlm|NTLM]] authentication. Windows authentication is supported regardless of whether a [[https://en.wikipedia.org/wiki/Windows_domain|domain]] is used in the environment. On Unix systems, the most dominant GSSAPI service is [[https://en.wikipedia.org/wiki/Kerberos_(protocol)|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. This article gives instructions on configuring the GSSAPI authentication plugin for MariaDB for passwordless login. <<toc>> == Preparing the Server === Preparing a Windows Server Usually nothing need to be done to prepare a server running Windows to use GSSAPI authentication. MariaDB server should run on a server that is joined to a domain, 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 [[https://technet.microsoft.com/en-us/library/cc731241.aspx| setspn tool]]) === Preparing a Unix Server 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 [[http://www.microhowto.info/howto/create_a_service_principal_using_mit_kerberos.html|here]] and [[http://www.microhowto.info/howto/add_a_host_or_service_principal_to_a_keytab_using_mit_kerberos.html|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/host.domain.com@DOMAIN.COM /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 [[https://technet.microsoft.com/en-us/library/cc753771.aspx|Microsoft documentation]] for details. == 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|INSTALL SONAME]]## or ##[[install-plugin|INSTALL PLUGIN]]##. For example: <<sql>> INSTALL SONAME 'auth_gssapi'; <</sql>> 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 ##[[mysqld-options/#-plugin-load|--plugin-load]]## or the ##[[mysqld-options/#-plugin-load-add|--plugin-load-add]]## options. This can be specified as a command-line argument to ##[[mysqld-options|mysqld]]## or it can be specified in a relevant server [[configuring-mariadb-with-option-files/#option-groups|option group]] in an [[configuring-mariadb-with-option-files|option file]]. For example: <<code>> [mariadb] ... plugin_load_add = auth_gssapi <</code>> == Uninstalling the Plugin You can uninstall the plugin dynamically by executing ##[[uninstall-soname|UNINSTALL SONAME]]## or ##[[uninstall-plugin|UNINSTALL PLUGIN]]##. For example: <<sql>> UNINSTALL SONAME 'auth_gssapi'; <</sql>> If you installed the plugin by providing the ##[[mysqld-options/#-plugin-load|--plugin-load]]## or the ##[[mysqld-options/#-plugin-load-add|--plugin-load-add]]## options in a relevant server [[configuring-mariadb-with-option-files/#option-groups|option group]] in an [[configuring-mariadb-with-option-files|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|gssapi_keytab_path]]## option in the server's [[configuring-mariadb-with-option-files|option file]] to the path of the previously created keytab file. <<code>> [mariadb] ... gssapi_keytab_path=/path/to/mariadb.keytab <</code>> 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|gssapi_principal_name]]## option in the server's [[configuring-mariadb-with-option-files|option file]] as well. <<code>> [mariadb] ... gssapi_principal_name=alternative/principalname@REALM <</code>> == Creating Users To create a user account via ##[[create-user|CREATE USER]]##, specify the name of the plugin in the ##[[create-user/#identified-viawith-authentication_plugin|IDENTIFIED VIA]]## clause. For example: <<sql>> CREATE USER username@hostname IDENTIFIED VIA gssapi; <</sql>> If ##[[sql-mode|SQL_MODE]]## does not have ##NO_AUTO_CREATE_USER## set, then you can also create the user account via ##[[grant|GRANT]]##. For example: <<sql>> GRANT SELECT ON db.* TO username@hostname IDENTIFIED VIA gssapi; <</sql>> You can also specify the user's [[https://docs.microsoft.com/en-us/windows-server/networking/technologies/nps/nps-crp-realm-names|realm]] for MariaDB with the ##USING## clause. For example: <<sql>> CREATE USER username@hostname IDENTIFIED VIA gssapi USING 'username@EXAMPLE.COM'; <</sql>> 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, 'usr1@EXAMPLE.COM', 'usr1@EXAMPLE.CO.UK' and 'mymachine\usr1' would all identify as the following user account: <<sql>> CREATE USER usr1@hostname IDENTIFIED VIA gssapi; <</sql>> == Using the Plugin with Command-line Clients When connecting with a command-line client to a server that uses GSSAPI authentication, you may need to tell the client where to find the client plugin by specifying the ##--plugin-dir## option. For example: {{{ mysql --plugin-dir=/path/to/plugin-dir -u usr1 }}} == Using the Plugin with MariaDB Connector/J [[mariadb-connector-j|MariaDB Connector/J]] has supported GSSAPI authentication since version 1.4. Current documentation can be found [[gssapi-authentication-with-mariadb-connectorj|here]]. == Using the Plugin with .NET [[https://github.com/mysql-net/MySqlConnector|MySqlConnector]] driver supports GSSAPI authentication since version 0.47 The support is transparent, i.e normally no other parameters needs to be passed to the connector, except the correct user name. This driver also support GSSAPI specific ServerSPN connection string parameter, for mutual authentication(see [[https://mysql-net.github.io/MySqlConnector/connection-options|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 machine$@domain.com) . 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) == Versions <<style class="darkheader-nospace-borders" >> |= Version |= Status |= Introduced | 1.0 | Stable | MariaDB 10.1.15 | 1.0 | Beta | MariaDB 10.1.11 <</style>> == System Variables === ##gssapi_keytab_path## * **Description:** Available on Unix only. Path to the server keytab file. * **Commandline:** <<code>>--gssapi-keytab-path<</code>> * **Scope:** Global * **Dynamic:** No * **Data Type:** ##string## * **Default Value:** '' * **Introduced:** MariaDB 10.1.11 ---- === ##gssapi_principal_name## * **Description:** Name of the service principal. * **Commandline:** <<code>>--gssapi-principal-name<</code>> * **Scope:** Global * **Dynamic:** No * **Data Type:** ##string## * **Default Value:** '' * **Introduced:** MariaDB 10.1.11 ---- === ##gssapi_mech_name## * **Description:** Available on Windows only. 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). * **Commandline:** <<code>>--gssapi-mech-name<</code>> * **Scope:** Global * **Dynamic:** No * **Data Type:** ##enumerated## * **Default Value:** ##Negotiate## * **Valid Values:** ##Kerberos##, ##Negotiate## * **Introduced:** MariaDB 10.1.11 ----
