<div id="docs-body">
 <div class="section">
  <div class="titlepage">
   <div>
    <div>
     <h4 class="title">
      <a name="kerberos-pluggable-authentication">
      </a>
      8.4.1.8 Kerberos Pluggable Authentication
     </h4>
    </div>
   </div>
  </div>
  <a class="indexterm" name="idm46045244659952">
  </a>
  <a class="indexterm" name="idm46045244658848">
  </a>
  <a class="indexterm" name="idm46045244657360">
  </a>
  <a class="indexterm" name="idm46045244656256">
  </a>
  <a class="indexterm" name="idm46045244654752">
  </a>
  <a class="indexterm" name="idm46045244653264">
  </a>
  <a class="indexterm" name="idm46045244651776">
  </a>
  <a class="indexterm" name="idm46045244650688">
  </a>
  <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
   <div class="admon-title">
    Note
   </div>
   <p>
    Kerberos pluggable authentication is an extension included in
          MySQL Enterprise Edition, a commercial product. To learn more about commercial
          products, see
    <a class="ulink" href="https://www.mysql.com/products/" target="_blank">
     https://www.mysql.com/products/
    </a>
    .
   </p>
  </div>
  <p>
   MySQL Enterprise Edition supports an authentication method that enables users to
        authenticate to MySQL Server using Kerberos, provided that
        appropriate Kerberos tickets are available or can be obtained.
  </p>
  <p>
   This authentication method is available in MySQL
        8.4 for MySQL servers and clients on Linux. It is
        useful in Linux environments where applications have access to
        Microsoft Active Directory, which has Kerberos enabled by
        default. The client-side plugin is supported on Windows as well.
        The server-side plugin is still supported only on Linux.
  </p>
  <p>
   Kerberos pluggable authentication provides these capabilities:
  </p>
  <div class="itemizedlist">
   <ul class="itemizedlist" style="list-style-type: disc; ">
    <li class="listitem">
     <p>
      External authentication: Kerberos authentication enables
            MySQL Server to accept connections from users defined
            outside the MySQL grant tables who have obtained the proper
            Kerberos tickets.
     </p>
    </li>
    <li class="listitem">
     <p>
      Security: Kerberos uses tickets together with symmetric-key
            cryptography, enabling authentication without sending
            passwords over the network. Kerberos authentication supports
            userless and passwordless scenarios.
     </p>
    </li>
   </ul>
  </div>
  <p>
   The following table shows the plugin and library file names. The
        file name suffix might differ on your system. The file must be
        located in the directory named by the
   <a class="link" href="server-system-variables.html#sysvar_plugin_dir">
    <code class="literal">
     plugin_dir
    </code>
   </a>
   system variable. For
        installation information, see
   <a class="xref" href="kerberos-pluggable-authentication.html#kerberos-pluggable-authentication-installation" title="Installing Kerberos Pluggable Authentication">
    Installing Kerberos Pluggable Authentication
   </a>
   .
  </p>
  <div class="table">
   <a name="idm46045244640384">
   </a>
   <p class="title">
    <b>
     Table 8.23 Plugin and Library Names for Kerberos Authentication
    </b>
   </p>
   <div class="table-contents">
    <table summary="Names for the plugins and library file used for Kerberos authentication.">
     <colgroup>
      <col style="width: 30%"/>
      <col style="width: 70%"/>
     </colgroup>
     <thead>
      <tr>
       <th>
        Plugin or File
       </th>
       <th>
        Plugin or File Name
       </th>
      </tr>
     </thead>
     <tbody>
      <tr>
       <td>
        Server-side plugin
       </td>
       <td>
        <code class="literal">
         authentication_kerberos
        </code>
       </td>
      </tr>
      <tr>
       <td>
        Client-side plugin
       </td>
       <td>
        <code class="literal">
         authentication_kerberos_client
        </code>
       </td>
      </tr>
      <tr>
       <td>
        Library file
       </td>
       <td>
        <code class="filename">
         authentication_kerberos.so
        </code>
        ,
        <code class="filename">
         authentication_kerberos_client.so
        </code>
       </td>
      </tr>
     </tbody>
    </table>
   </div>
  </div>
  <br class="table-break"/>
  <p>
   The server-side Kerberos authentication plugin is included only
        in MySQL Enterprise Edition. It is not included in MySQL community distributions.
        The client-side plugin is included in all distributions,
        including community distributions. This enables clients from any
        distribution to connect to a server that has the server-side
        plugin loaded.
  </p>
  <p>
   The following sections provide installation and usage
        information specific to Kerberos pluggable authentication:
  </p>
  <div class="itemizedlist">
   <ul class="itemizedlist" style="list-style-type: disc; ">
    <li class="listitem">
     <p>
      <a class="xref" href="kerberos-pluggable-authentication.html#kerberos-pluggable-authentication-prerequisites" title="Prerequisites for Kerberos Pluggable Authentication">
       Prerequisites for Kerberos Pluggable Authentication
      </a>
     </p>
    </li>
    <li class="listitem">
     <p>
      <a class="xref" href="kerberos-pluggable-authentication.html#kerberos-pluggable-authentication-process" title="How Kerberos Authentication of MySQL Users Works">
       How Kerberos Authentication of MySQL Users Works
      </a>
     </p>
    </li>
    <li class="listitem">
     <p>
      <a class="xref" href="kerberos-pluggable-authentication.html#kerberos-pluggable-authentication-installation" title="Installing Kerberos Pluggable Authentication">
       Installing Kerberos Pluggable Authentication
      </a>
     </p>
    </li>
    <li class="listitem">
     <p>
      <a class="xref" href="kerberos-pluggable-authentication.html#kerberos-pluggable-authentication-usage" title="Using Kerberos Pluggable Authentication">
       Using Kerberos Pluggable Authentication
      </a>
     </p>
    </li>
    <li class="listitem">
     <p>
      <a class="xref" href="kerberos-pluggable-authentication.html#kerberos-pluggable-authentication-debugging" title="Kerberos Authentication Debugging">
       Kerberos Authentication Debugging
      </a>
     </p>
    </li>
   </ul>
  </div>
  <p>
   For general information about pluggable authentication in MySQL,
        see
   <a class="xref" href="pluggable-authentication.html" title="8.2.17 Pluggable Authentication">
    Section 8.2.17, “Pluggable Authentication”
   </a>
   .
  </p>
  <div class="simplesect">
   <div class="titlepage">
    <div>
     <div class="simple">
      <h5 class="title">
       <a name="kerberos-pluggable-authentication-prerequisites">
       </a>
       Prerequisites for Kerberos Pluggable Authentication
      </h5>
     </div>
    </div>
   </div>
   <p>
    To use Kerberos pluggable authentication for MySQL, these
          prerequisites must be satisfied:
   </p>
   <div class="itemizedlist">
    <ul class="itemizedlist" style="list-style-type: disc; ">
     <li class="listitem">
      <p>
       A Kerberos service must be available for the Kerberos
              authentication plugins to communicate with.
      </p>
     </li>
     <li class="listitem">
      <p>
       Each Kerberos user (principal) to be authenticated by
              MySQL must be present in the database managed by the KDC
              server.
      </p>
     </li>
     <li class="listitem">
      <p>
       A Kerberos client library must be available on systems
              where either the server-side or client-side Kerberos
              authentication plugin is used. In addition, GSSAPI is used
              as the interface for accessing Kerberos authentication, so
              a GSSAPI library must be available.
      </p>
     </li>
    </ul>
   </div>
  </div>
  <div class="simplesect">
   <div class="titlepage">
    <div>
     <div class="simple">
      <h5 class="title">
       <a name="kerberos-pluggable-authentication-process">
       </a>
       How Kerberos Authentication of MySQL Users Works
      </h5>
     </div>
    </div>
   </div>
   <p>
    This section provides an overview of how MySQL and Kerberos
          work together to authenticate MySQL users. For examples
          showing how to set up MySQL accounts to use the Kerberos
          authentication plugins, see
    <a class="xref" href="kerberos-pluggable-authentication.html#kerberos-pluggable-authentication-usage" title="Using Kerberos Pluggable Authentication">
     Using Kerberos Pluggable Authentication
    </a>
    .
   </p>
   <p>
    Familiarity is assumed here with Kerberos concepts and
          operation. The following list briefly defines several common
          Kerberos terms. You may also find the Glossary section of
    <a class="ulink" href="https://tools.ietf.org/html/rfc4120" target="_blank">
     RFC
          4120
    </a>
    helpful.
   </p>
   <div class="itemizedlist">
    <ul class="itemizedlist" style="list-style-type: disc; ">
     <li class="listitem">
      <p>
       <a class="link" href="glossary.html#glos_principal" title="principal">
        Principal
       </a>
       : A named
              entity, such as a user or server. In this discussion,
              certain principal-related terms occur frequently:
      </p>
      <div class="itemizedlist">
       <ul class="itemizedlist" style="list-style-type: circle; ">
        <li class="listitem">
         <p>
          <a class="link" href="glossary.html#glos_service_principal_name" title="service principal name">
           SPN
          </a>
          :
                  Service principal name; the name of a principal that
                  represents a service.
         </p>
        </li>
        <li class="listitem">
         <p>
          <a class="link" href="glossary.html#glos_user_principal_name" title="user principal name">
           UPN
          </a>
          :
                  User principal name; the name of a principal that
                  represents a user.
         </p>
        </li>
       </ul>
      </div>
     </li>
     <li class="listitem">
      <p>
       <a class="link" href="glossary.html#glos_key_distribution_center" title="key distribution center">
        KDC
       </a>
       :
              The key distribution center, comprising the AS and TGS:
      </p>
      <div class="itemizedlist">
       <ul class="itemizedlist" style="list-style-type: circle; ">
        <li class="listitem">
         <p>
          <a class="link" href="glossary.html#glos_authentication_server" title="authentication server">
           AS
          </a>
          :
                  The authentication server; provides the initial
                  ticket-granting ticket needed to obtain additional
                  tickets.
         </p>
        </li>
        <li class="listitem">
         <p>
          <a class="link" href="glossary.html#glos_ticket_granting_server" title="ticket-granting server">
           TGS
          </a>
          :
                  The ticket-granting server; provides additional
                  tickets to Kerberos clients that possess a valid TGT.
         </p>
        </li>
       </ul>
      </div>
     </li>
     <li class="listitem">
      <p>
       <a class="link" href="glossary.html#glos_ticket_granting_ticket" title="ticket-granting ticket">
        TGT
       </a>
       :
              The ticket-granting ticket; presented to the TGS to obtain
              service tickets for service access.
      </p>
     </li>
     <li class="listitem">
      <p>
       <a class="link" href="glossary.html#glos_service_ticket" title="service ticket">
        ST
       </a>
       : A service
              ticket; provides access to a service such as that offered
              by a MySQL server.
      </p>
     </li>
    </ul>
   </div>
   <p>
    Authentication using Kerberos requires a KDC server, for
          example, as provided by Microsoft Active Directory.
   </p>
   <p>
    Kerberos authentication in MySQL uses Generic Security Service
          Application Program Interface (GSSAPI), which is a security
          abstraction interface. Kerberos is an instance of a specific
          security protocol that can be used through that abstract
          interface. Using GSSAPI, applications authenticate to Kerberos
          to obtain service credentials, then use those credentials in
          turn to enable secure access to other services.
   </p>
   <p>
    On Windows, the
    <code class="literal">
     authentication_kerberos_client
    </code>
    authentication plugin supports two modes, which the client
          user can set at runtime or specify in an option file:
   </p>
   <div class="itemizedlist">
    <ul class="itemizedlist" style="list-style-type: disc; ">
     <li class="listitem">
      <p>
       <code class="literal">
        SSPI
       </code>
       mode: Security Support Provider
              Interface (SSPI) implements GSSAPI (see
       <a class="link" href="kerberos-pluggable-authentication.html#kerberos-usage-win-sspi-client-commands">
        Commands for Windows Clients in SSPI Mode
       </a>
       ). SSPI,
              while being compatible with GSSAPI at the wire level, only
              supports the Windows single sign-on scenario and
              specifically refers to the logged-on user. SSPI is the
              default mode on most Windows clients.
      </p>
     </li>
     <li class="listitem">
      <p>
       <code class="literal">
        GSSAPI
       </code>
       mode: Supports GSSAPI through
              the MIT Kerberos library on Windows (see
       <a class="link" href="kerberos-pluggable-authentication.html#kerberos-usage-win-gssapi-client-commands">
        Commands for Windows Clients in GSSAPI Mode
       </a>
       ).
      </p>
     </li>
    </ul>
   </div>
   <p>
    With the Kerberos authentication plugins, applications and
          MySQL servers are able to use the Kerberos authentication
          protocol to mutually authenticate users and MySQL services.
          This way both the user and the server are able to verify each
          other's identity. No passwords are sent over the network
          and Kerberos protocol messages are protected against
          eavesdropping and replay attacks.
   </p>
   <p>
    Kerberos authentication follows these steps, where the
          server-side and client-side parts are performed using the
    <code class="literal">
     authentication_kerberos
    </code>
    and
    <code class="literal">
     authentication_kerberos_client
    </code>
    authentication plugins, respectively:
   </p>
   <div class="orderedlist">
    <ol class="orderedlist" type="1">
     <li class="listitem">
      <p>
       The MySQL server sends to the client application its
              service principal name. This SPN must be registered in the
              Kerberos system, and is configured on the server side
              using the
       <a class="link" href="pluggable-authentication-system-variables.html#sysvar_authentication_kerberos_service_principal">
        <code class="literal">
         authentication_kerberos_service_principal
        </code>
       </a>
       system variable.
      </p>
     </li>
     <li class="listitem">
      <p>
       Using GSSAPI, the client application creates a Kerberos
              client-side authentication session and exchanges Kerberos
              messages with the Kerberos KDC:
      </p>
      <div class="itemizedlist">
       <ul class="itemizedlist" style="list-style-type: disc; ">
        <li class="listitem">
         <p>
          The client obtains a ticket-granting ticket from the
                  authentication server.
         </p>
        </li>
        <li class="listitem">
         <p>
          Using the TGT, the client obtains a service ticket for
                  MySQL from the ticket-granting service.
         </p>
        </li>
       </ul>
      </div>
      <p>
       This step can be skipped or partially skipped if the TGT,
              ST, or both are already cached locally. The client
              optionally may use a client keytab file to obtain a TGT
              and ST without supplying a password.
      </p>
     </li>
     <li class="listitem">
      <p>
       Using GSSAPI, the client application presents the MySQL ST
              to the MySQL server.
      </p>
     </li>
     <li class="listitem">
      <p>
       Using GSSAPI, the MySQL server creates a Kerberos
              server-side authentication session. The server validates
              the user identity and the validity of the user request. It
              authenticates the ST using the service key configured in
              its service keytab file to determine whether
              authentication succeeds or fails, and returns the
              authentication result to the client.
      </p>
     </li>
    </ol>
   </div>
   <p>
    Applications are able to authenticate using a provided user
          name and password, or using a locally cached TGT or ST (for
          example, created using
    <span class="command">
     <strong>
      kinit
     </strong>
    </span>
    or similar).
          This design therefore covers use cases ranging from completely
          userless and passwordless connections, where Kerberos service
          tickets are obtained from a locally stored Kerberos cache, to
          connections where both user name and password are provided and
          used to obtain a valid Kerberos service ticket from a KDC, to
          send to the MySQL server.
   </p>
   <p>
    As indicated in the preceding description, MySQL Kerberos
          authentication uses two kinds of keytab files:
   </p>
   <a class="indexterm" name="idm46045244570544">
   </a>
   <div class="itemizedlist">
    <ul class="itemizedlist" style="list-style-type: disc; ">
     <li class="listitem">
      <p>
       On the client host, a client keytab file may be used to
              obtain a TGT and ST without supplying a password. See
       <a class="xref" href="kerberos-pluggable-authentication.html#kerberos-pluggable-authentication-mysql-client-config-parameters" title="Client Configuration Parameters for Kerberos Authentication">
        Client Configuration Parameters for Kerberos Authentication
       </a>
       .
      </p>
     </li>
     <li class="listitem">
      <p>
       On the MySQL server host, a server-side service keytab
              file is used to verify service tickets received by the
              MySQL server from clients. The keytab file name is
              configured using the
       <a class="link" href="pluggable-authentication-system-variables.html#sysvar_authentication_kerberos_service_key_tab">
        <code class="literal">
         authentication_kerberos_service_key_tab
        </code>
       </a>
       system variable.
      </p>
     </li>
    </ul>
   </div>
   <p>
    For information about keytab files, see
    <a class="ulink" href="https://web.mit.edu/kerberos/krb5-latest/doc/basic/keytab_def.html" target="_blank">
     https://web.mit.edu/kerberos/krb5-latest/doc/basic/keytab_def.html
    </a>
    .
   </p>
  </div>
  <div class="simplesect">
   <div class="titlepage">
    <div>
     <div class="simple">
      <h5 class="title">
       <a name="kerberos-pluggable-authentication-installation">
       </a>
       Installing Kerberos Pluggable Authentication
      </h5>
     </div>
    </div>
   </div>
   <p>
    This section describes how to install the server-side Kerberos
          authentication plugin. For general information about
          installing plugins, see
    <a class="xref" href="plugin-loading.html" title="7.6.1 Installing and Uninstalling Plugins">
     Section 7.6.1, “Installing and Uninstalling Plugins”
    </a>
    .
   </p>
   <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
    <div class="admon-title">
     Note
    </div>
    <p>
     The server-side plugin is supported only on Linux systems.
            On Windows systems, only the client-side plugin is
            supported, which can be used on a Windows system to connect
            to a Linux server that uses Kerberos authentication.
    </p>
   </div>
   <p>
    To be usable by the server, the plugin library file must be
          located in the MySQL plugin directory (the directory named by
          the
    <a class="link" href="server-system-variables.html#sysvar_plugin_dir">
     <code class="literal">
      plugin_dir
     </code>
    </a>
    system
          variable). If necessary, configure the plugin directory
          location by setting the value of
    <a class="link" href="server-system-variables.html#sysvar_plugin_dir">
     <code class="literal">
      plugin_dir
     </code>
    </a>
    at server startup.
   </p>
   <p>
    The server-side plugin library file base name is
    <code class="literal">
     authentication_kerberos
    </code>
    . The file name
          suffix for Unix and Unix-like systems is
    <code class="filename">
     .so
    </code>
    .
   </p>
   <p>
    To load the plugin at server startup, use the
    <a class="link" href="server-options.html#option_mysqld_plugin-load-add">
     <code class="option">
      --plugin-load-add
     </code>
    </a>
    option to
          name the library file that contains it. With this
          plugin-loading method, the option must be given each time the
          server starts. Also, specify values for any plugin-provided
          system variables you wish to configure. The plugin exposes
          these system variables, enabling its operation to be
          configured:
   </p>
   <div class="itemizedlist">
    <ul class="itemizedlist" style="list-style-type: disc; ">
     <li class="listitem">
      <p>
       <a class="link" href="pluggable-authentication-system-variables.html#sysvar_authentication_kerberos_service_principal">
        <code class="literal">
         authentication_kerberos_service_principal
        </code>
       </a>
       :
              The MySQL service principal name (SPN). This name is sent
              to clients that attempt to authenticate using Kerberos.
              The SPN must be present in the database managed by the KDC
              server. The default is
       <code class="literal">
        mysql/
        <em class="replaceable">
         <code>
          host_name
         </code>
        </em>
        @
        <em class="replaceable">
         <code>
          realm_name
         </code>
        </em>
       </code>
       .
      </p>
     </li>
     <li class="listitem">
      <p>
       <a class="link" href="pluggable-authentication-system-variables.html#sysvar_authentication_kerberos_service_key_tab">
        <code class="literal">
         authentication_kerberos_service_key_tab
        </code>
       </a>
       :
              The keytab file for authenticating tickets received from
              clients. This file must exist and contain a valid key for
              the SPN or authentication of clients will fail. The
              default is
       <code class="filename">
        mysql.keytab
       </code>
       in the data
              directory.
      </p>
      <a class="indexterm" name="idm46045244545872">
      </a>
     </li>
    </ul>
   </div>
   <p>
    For details about all Kerberos authentication system
          variables, see
    <a class="xref" href="pluggable-authentication-system-variables.html" title="8.4.1.13 Pluggable Authentication System Variables">
     Section 8.4.1.13, “Pluggable Authentication System Variables”
    </a>
    .
   </p>
   <p>
    To load the plugin and configure it, put lines such as these
          in your
    <code class="filename">
     my.cnf
    </code>
    file, using values for the
          system variables that are appropriate for your installation:
   </p>
   <div class="copytoclipboard-wrapper">
    <pre class="programlisting language-ini"><div class="docs-select-all right" id="sa35523648"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-ini"><span class="token selector">[mysqld]</span>
<span class="token constant">plugin-load-add</span><span class="token attr-value"><span class="token punctuation">=</span>authentication_kerberos.so</span>
<span class="token constant">authentication_kerberos_service_principal</span><span class="token attr-value"><span class="token punctuation">=</span>mysql/krbauth.example.com@MYSQL.LOCAL</span>
<span class="token constant">authentication_kerberos_service_key_tab</span><span class="token attr-value"><span class="token punctuation">=</span>/var/mysql/data/mysql.keytab</span></code></pre>
   </div>
   <p>
    After modifying
    <code class="filename">
     my.cnf
    </code>
    , restart the
          server to cause the new settings to take effect.
   </p>
   <p>
    Alternatively, to load the plugin at runtime, use this
          statement:
   </p>
   <div class="copytoclipboard-wrapper">
    <pre class="programlisting language-sql"><div class="docs-select-all right" id="sa94057788"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-sql"><span class="token keyword">INSTALL</span> <span class="token keyword">PLUGIN</span> authentication_kerberos
  <span class="token keyword">SONAME</span> <span class="token string">'authentication_kerberos.so'</span><span class="token punctuation">;</span></code></pre>
   </div>
   <p>
    <a class="link" href="install-plugin.html" title="15.7.4.4 INSTALL PLUGIN Statement">
     <code class="literal">
      INSTALL PLUGIN
     </code>
    </a>
    loads the plugin
          immediately, and also registers it in the
    <code class="literal">
     mysql.plugins
    </code>
    system table to cause the
          server to load it for each subsequent normal startup without
          the need for
    <a class="link" href="server-options.html#option_mysqld_plugin-load-add">
     <code class="option">
      --plugin-load-add
     </code>
    </a>
    .
   </p>
   <p>
    When you install the plugin at runtime without configuring its
          system variables in the
    <code class="filename">
     my.cnf
    </code>
    file, the
          system variable
    <a class="link" href="pluggable-authentication-system-variables.html#sysvar_authentication_kerberos_service_key_tab">
     <code class="literal">
      authentication_kerberos_service_key_tab
     </code>
    </a>
    is set to the default value of
    <code class="filename">
     mysql.keytab
    </code>
    in the data directory. The
          value of this system variable cannot be changed at runtime, so
          if you need to specify a different file, you need to add the
          setting to your
    <code class="filename">
     my.cnf
    </code>
    file then restart
          the MySQL server. For example:
   </p>
   <div class="copytoclipboard-wrapper">
    <pre class="programlisting language-ini"><div class="docs-select-all right" id="sa1548752"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-ini"><span class="token selector">[mysqld]</span>
<span class="token constant">authentication_kerberos_service_key_tab</span><span class="token attr-value"><span class="token punctuation">=</span>/var/mysql/data/mysql.keytab</span></code></pre>
   </div>
   <p>
    If the keytab file is not in the correct place or does not
          contain a valid SPN key, the MySQL server does not validate
          this, but clients return authentication errors until you fix
          the issue.
   </p>
   <p>
    The
    <a class="link" href="pluggable-authentication-system-variables.html#sysvar_authentication_kerberos_service_principal">
     <code class="literal">
      authentication_kerberos_service_principal
     </code>
    </a>
    system variable can be set and persisted at runtime without
          restarting the server, by using a
    <a class="link" href="set-variable.html" title="15.7.6.1 SET Syntax for Variable Assignment">
     <code class="literal">
      SET
          PERSIST
     </code>
    </a>
    statement:
   </p>
   <div class="copytoclipboard-wrapper">
    <pre class="programlisting one-line language-sql"><div class="docs-select-all right" id="sa45202989"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-sql"><span class="token keyword">SET</span> <span class="token keyword">PERSIST</span> authentication_kerberos_service_principal<span class="token operator">=</span><span class="token string">'mysql/krbauth.example.com@MYSQL.LOCAL'</span><span class="token punctuation">;</span></code></pre>
   </div>
   <p>
    <a class="link" href="set-variable.html" title="15.7.6.1 SET Syntax for Variable Assignment">
     <code class="literal">
      SET
          PERSIST
     </code>
    </a>
    sets a value for the running MySQL instance.
          It also saves the value, causing it to carry over to
          subsequent server restarts. To change a value for the running
          MySQL instance without having it carry over to subsequent
          restarts, use the
    <code class="literal">
     GLOBAL
    </code>
    keyword rather
          than
    <code class="literal">
     PERSIST
    </code>
    . See
    <a class="xref" href="set-variable.html" title="15.7.6.1 SET Syntax for Variable Assignment">
     Section 15.7.6.1, “SET Syntax for Variable Assignment”
    </a>
    .
   </p>
   <p>
    To verify plugin installation, examine the Information Schema
    <a class="link" href="information-schema-plugins-table.html" title="28.3.22 The INFORMATION_SCHEMA PLUGINS Table">
     <code class="literal">
      PLUGINS
     </code>
    </a>
    table or use the
    <a class="link" href="show-plugins.html" title="15.7.7.27 SHOW PLUGINS Statement">
     <code class="literal">
      SHOW PLUGINS
     </code>
    </a>
    statement (see
    <a class="xref" href="obtaining-plugin-information.html" title="7.6.2 Obtaining Server Plugin Information">
     Section 7.6.2, “Obtaining Server Plugin Information”
    </a>
    ). For example:
   </p>
   <div class="copytoclipboard-wrapper">
    <pre class="programlisting language-sql"><div class="docs-select-all right" id="sa51100850"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-sql"><span class="token prompt">mysql&gt;</span> <span class="token keyword">SELECT</span> PLUGIN_NAME<span class="token punctuation">,</span> PLUGIN_STATUS
       <span class="token keyword">FROM</span> INFORMATION_SCHEMA<span class="token punctuation">.</span><span class="token keyword">PLUGINS</span>
       <span class="token keyword">WHERE</span> PLUGIN_NAME <span class="token operator">=</span> <span class="token string">'authentication_kerberos'</span><span class="token punctuation">;</span>
<span class="token output"><span class="token punctuation">+</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">+</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">+</span></span>
<span class="token output"><span class="token punctuation">|</span> PLUGIN_NAME             <span class="token punctuation">|</span> PLUGIN_STATUS <span class="token punctuation">|</span></span>
<span class="token output"><span class="token punctuation">+</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">+</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">+</span></span>
<span class="token output"><span class="token punctuation">|</span> authentication_kerberos <span class="token punctuation">|</span> ACTIVE        <span class="token punctuation">|</span></span>
<span class="token output"><span class="token punctuation">+</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">+</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">+</span></span></code></pre>
   </div>
   <p>
    If a plugin fails to initialize, check the server error log
          for diagnostic messages.
   </p>
   <p>
    To associate MySQL accounts with the Kerberos plugin, see
    <a class="xref" href="kerberos-pluggable-authentication.html#kerberos-pluggable-authentication-usage" title="Using Kerberos Pluggable Authentication">
     Using Kerberos Pluggable Authentication
    </a>
    .
   </p>
  </div>
  <div class="simplesect">
   <div class="titlepage">
    <div>
     <div class="simple">
      <h5 class="title">
       <a name="kerberos-pluggable-authentication-usage">
       </a>
       Using Kerberos Pluggable Authentication
      </h5>
     </div>
    </div>
   </div>
   <p>
    This section describes how to enable MySQL accounts to connect
          to the MySQL server using Kerberos pluggable authentication.
          It is assumed that the server is running with the server-side
          plugin enabled, as described in
    <a class="xref" href="kerberos-pluggable-authentication.html#kerberos-pluggable-authentication-installation" title="Installing Kerberos Pluggable Authentication">
     Installing Kerberos Pluggable Authentication
    </a>
    ,
          and that the client-side plugin is available on the client
          host.
   </p>
   <div class="itemizedlist">
    <ul class="itemizedlist" style="list-style-type: disc; ">
     <li class="listitem">
      <p>
       <a class="xref" href="kerberos-pluggable-authentication.html#kerberos-usage-kerberos-setup" title="Verify Kerberos Availability">
        Verify Kerberos Availability
       </a>
      </p>
     </li>
     <li class="listitem">
      <p>
       <a class="xref" href="kerberos-pluggable-authentication.html#kerberos-usage-mysql-account-setup" title="Create a MySQL Account That Uses Kerberos Authentication">
        Create a MySQL Account That Uses Kerberos Authentication
       </a>
      </p>
     </li>
     <li class="listitem">
      <p>
       <a class="xref" href="kerberos-pluggable-authentication.html#kerberos-usage-mysql-client-usage" title="Use the MySQL Account to Connect to the MySQL Server">
        Use the MySQL Account to Connect to the MySQL Server
       </a>
      </p>
     </li>
     <li class="listitem">
      <p>
       <a class="xref" href="kerberos-pluggable-authentication.html#kerberos-pluggable-authentication-mysql-client-config-parameters" title="Client Configuration Parameters for Kerberos Authentication">
        Client Configuration Parameters for Kerberos Authentication
       </a>
      </p>
     </li>
    </ul>
   </div>
   <h6>
    <a name="kerberos-usage-kerberos-setup">
    </a>
    Verify Kerberos Availability
   </h6>
   <p>
    The following example shows how to test availability of
          Kerberos in Active Directory. The example makes these
          assumptions:
   </p>
   <div class="itemizedlist">
    <ul class="itemizedlist" style="list-style-type: disc; ">
     <li class="listitem">
      <p>
       Active Directory is running on the host named
       <code class="literal">
        krbauth.example.com
       </code>
       with IP address
       <code class="literal">
        198.51.100.11
       </code>
       .
      </p>
     </li>
     <li class="listitem">
      <p>
       MySQL-related Kerberos authentication uses the
       <code class="literal">
        MYSQL.LOCAL
       </code>
       domain, and also uses
       <code class="literal">
        MYSQL.LOCAL
       </code>
       as the realm name.
      </p>
     </li>
     <li class="listitem">
      <p>
       A principal named
       <code class="literal">
        karl@MYSQL.LOCAL
       </code>
       is
              registered with the KDC. (In later discussion, this
              principal name is associated with the MySQL account that
              authenticates to the MySQL server using Kerberos.)
      </p>
     </li>
    </ul>
   </div>
   <p>
    With those assumptions satisfied, follow this procedure:
   </p>
   <div class="orderedlist">
    <ol class="orderedlist" type="1">
     <li class="listitem">
      <p>
       Verify that the Kerberos library is installed and
              configured correctly in the operating system. For example,
              to configure a
       <code class="literal">
        MYSQL.LOCAL
       </code>
       domain and
              realm for use during MySQL authentication, the
       <code class="filename">
        /etc/krb5.conf
       </code>
       Kerberos configuration
              file should contain something like this:
      </p>
      <a class="indexterm" name="idm46045244492208">
      </a>
      <a class="indexterm" name="idm46045244490720">
      </a>
      <div class="copytoclipboard-wrapper">
       <pre class="programlisting language-ini"><div class="docs-select-all right" id="sa76524010"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-ini"><span class="token selector">[realms]</span>
<span class="token constant">  MYSQL.LOCAL</span> <span class="token attr-value"><span class="token punctuation">=</span> {</span>
<span class="token constant">    kdc</span> <span class="token attr-value"><span class="token punctuation">=</span> krbauth.example.com</span>
<span class="token constant">    admin_server</span> <span class="token attr-value"><span class="token punctuation">=</span> krbauth.example.com</span>
<span class="token constant">    default_domain</span> <span class="token attr-value"><span class="token punctuation">=</span> MYSQL.LOCAL</span>
  }</code></pre>
      </div>
     </li>
     <li class="listitem">
      <p>
       You may need to add an entry to
       <code class="filename">
        /etc/hosts
       </code>
       for the server host:
      </p>
      <div class="copytoclipboard-wrapper">
       <pre class="programlisting one-line language-simple"><div class="docs-select-all right" id="sa10955029"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-simple">198<span class="token punctuation">.</span>51<span class="token punctuation">.</span>100<span class="token punctuation">.</span>11 krbauth krbauth<span class="token punctuation">.</span>example<span class="token punctuation">.</span>com</code></pre>
      </div>
     </li>
     <li class="listitem">
      <p>
       Check whether Kerberos authentication works correctly:
      </p>
      <div class="orderedlist">
       <ol class="orderedlist" type="a">
        <li class="listitem">
         <p>
          Use
          <span class="command">
           <strong>
            kinit
           </strong>
          </span>
          to authenticate to
                  Kerberos:
         </p>
         <div class="copytoclipboard-wrapper">
          <pre class="programlisting language-terminal"><div class="docs-select-all right" id="sa56628315"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-terminal"><span class="token prompt">$&gt; </span><span class="token command">kinit</span> karl@MYSQL<span class="token punctuation">.</span>LOCAL
Password for karl@MYSQL<span class="token punctuation">.</span>LOCAL<span class="token punctuation">:</span> <span class="token punctuation"></span><em class="replaceable"><span class="token punctuation">(</span>enter password here<span class="token punctuation">)</span></em><span class="token punctuation"></span></code></pre>
         </div>
         <p>
          The command authenticates for the Kerberos principal
                  named
          <code class="literal">
           karl@MYSQL.LOCAL
          </code>
          . Enter the
                  principal's password when the command prompts for
                  it. The KDC returns a TGT that is cached on the client
                  side for use by other Kerberos-aware applications.
         </p>
        </li>
        <li class="listitem">
         <p>
          Use
          <span class="command">
           <strong>
            klist
           </strong>
          </span>
          to check whether the TGT
                  was obtained correctly. The output should be similar
                  to this:
         </p>
         <div class="copytoclipboard-wrapper">
          <pre class="programlisting language-terminal"><div class="docs-select-all right" id="sa53794313"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-terminal"><span class="token prompt">$&gt; </span><span class="token command">klist</span>
Ticket cache<span class="token punctuation">:</span> FILE<span class="token punctuation">:</span>/tmp/krb5cc_244306
Default principal<span class="token punctuation">:</span> karl@MYSQL<span class="token punctuation">.</span>LOCAL

Valid starting       Expires              Service principal
03/23/2021 08<span class="token punctuation">:</span>18<span class="token punctuation">:</span>33  03/23/2021 18<span class="token punctuation">:</span>18<span class="token punctuation">:</span>33  krbtgt/MYSQL<span class="token punctuation">.</span>LOCAL@MYSQL<span class="token punctuation">.</span>LOCAL</code></pre>
         </div>
        </li>
       </ol>
      </div>
     </li>
    </ol>
   </div>
   <h6>
    <a name="kerberos-usage-mysql-account-setup">
    </a>
    Create a MySQL Account That Uses Kerberos Authentication
   </h6>
   <p>
    MySQL authentication using the
    <code class="literal">
     authentication_kerberos
    </code>
    authentication
          plugin is based on a Kerberos user principal name (UPN). The
          instructions here assume that a MySQL user named
    <code class="literal">
     karl
    </code>
    authenticates to MySQL using Kerberos,
          that the Kerberos realm is named
    <code class="literal">
     MYSQL.LOCAL
    </code>
    , and that the user principal
          name is
    <code class="literal">
     karl@MYSQL.LOCAL
    </code>
    . This UPN must be
          registered in several places:
   </p>
   <div class="itemizedlist">
    <ul class="itemizedlist" style="list-style-type: disc; ">
     <li class="listitem">
      <p>
       The Kerberos administrator should register the user name
              as a Kerberos principal. This name includes a realm name.
              Clients use the principal name and password to
              authenticate with Kerberos and obtain a ticket-granting
              ticket (TGT).
      </p>
     </li>
     <li class="listitem">
      <p>
       The MySQL DBA should create an account that corresponds to
              the Kerberos principal name and that authenticates using
              the Kerberos plugin.
      </p>
     </li>
    </ul>
   </div>
   <p>
    Assume that the Kerberos user principal name has been
          registered by the appropriate service administrator, and that,
          as previously described in
    <a class="xref" href="kerberos-pluggable-authentication.html#kerberos-pluggable-authentication-installation" title="Installing Kerberos Pluggable Authentication">
     Installing Kerberos Pluggable Authentication
    </a>
    ,
          the MySQL server has been started with appropriate
          configuration settings for the server-side Kerberos plugin. To
          create a MySQL account that corresponds to a Kerberos UPN of
    <code class="literal">
     <em class="replaceable">
      <code>
       user
      </code>
     </em>
     @
     <em class="replaceable">
      <code>
       realm_name
      </code>
     </em>
    </code>
    ,
          the MySQL DBA uses a statement like this:
   </p>
   <div class="copytoclipboard-wrapper">
    <pre class="programlisting language-sql"><div class="docs-select-all right" id="sa48834019"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-sql"><span class="token keyword">CREATE</span> <span class="token keyword">USER</span> <span class="token keyword"><em class="replaceable">user</em></span>
  <span class="token keyword">IDENTIFIED</span> <span class="token keyword">WITH</span> authentication_kerberos
  <span class="token keyword">BY</span> <span class="token string">'<em class="replaceable">realm_name</em>'</span><span class="token punctuation">;</span></code></pre>
   </div>
   <p>
    The account named by
    <em class="replaceable">
     <code>
      user
     </code>
    </em>
    can
          include or omit the host name part. If the host name is
          omitted, it defaults to
    <code class="literal">
     %
    </code>
    as usual. The
    <em class="replaceable">
     <code>
      realm_name
     </code>
    </em>
    is stored as the
    <code class="literal">
     authentication_string
    </code>
    value for the account
          in the
    <code class="literal">
     mysql.user
    </code>
    system table.
   </p>
   <p>
    To create a MySQL account that corresponds to the UPN
    <code class="literal">
     karl@MYSQL.LOCAL
    </code>
    , use this statement:
   </p>
   <div class="copytoclipboard-wrapper">
    <pre class="programlisting language-sql"><div class="docs-select-all right" id="sa83172145"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-sql"><span class="token keyword">CREATE</span> <span class="token keyword">USER</span> <span class="token string">'karl'</span>
  <span class="token keyword">IDENTIFIED</span> <span class="token keyword">WITH</span> authentication_kerberos
  <span class="token keyword">BY</span> <span class="token string">'MYSQL.LOCAL'</span><span class="token punctuation">;</span></code></pre>
   </div>
   <p>
    If MySQL must construct the UPN for this account, for example,
          to obtain or validate tickets (TGTs or STs), it does so by
          combining the account name (ignoring any host name part) and
          the realm name. For example, the full account name resulting
          from the preceding
    <a class="link" href="create-user.html" title="15.7.1.3 CREATE USER Statement">
     <code class="literal">
      CREATE USER
     </code>
    </a>
    statement is
    <code class="literal">
     'karl'@'%'
    </code>
    . MySQL constructs
          the UPN from the user name part
    <code class="literal">
     karl
    </code>
    (ignoring the host name part) and the realm name
    <code class="literal">
     MYSQL.LOCAL
    </code>
    to produce
    <code class="literal">
     karl@MYSQL.LOCAL
    </code>
    .
   </p>
   <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
    <div class="admon-title">
     Note
    </div>
    <p>
     Observe that when creating an account that authenticates
            using
     <code class="literal">
      authentication_kerberos
     </code>
     , the
     <a class="link" href="create-user.html" title="15.7.1.3 CREATE USER Statement">
      <code class="literal">
       CREATE USER
      </code>
     </a>
     statement does
            not include the UPN realm as part of the user name. Instead,
            specify the realm (
     <code class="literal">
      MYSQL.LOCAL
     </code>
     in this
            case) as the authentication string in the
     <code class="literal">
      BY
     </code>
     clause. This differs from creating
            accounts that use the
     <code class="literal">
      authentication_ldap_sasl
     </code>
     SASL LDAP
            authentication plugin with the GSSAPI/Kerberos
            authentication method. For such accounts, the
     <a class="link" href="create-user.html" title="15.7.1.3 CREATE USER Statement">
      <code class="literal">
       CREATE USER
      </code>
     </a>
     statement does
            include the UPN realm as part of the user name. See
     <a class="xref" href="ldap-pluggable-authentication.html#ldap-gssapi-mysql-account-setup" title="Create a MySQL Account That Uses GSSAPI/Kerberos for LDAP Authentication">
      Create a MySQL Account That Uses GSSAPI/Kerberos for LDAP Authentication
     </a>
     .
    </p>
   </div>
   <p>
    With the account set up, clients can use it to connect to the
          MySQL server. The procedure depends on whether the client host
          runs Linux or Windows, as indicated in the following
          discussion.
   </p>
   <p>
    Use of
    <code class="literal">
     authentication_kerberos
    </code>
    is subject
          to the restriction that UPNs with the same user part but a
          different realm part are not supported. For example, you
          cannot create MySQL accounts that correspond to both these
          UPNs:
   </p>
   <div class="copytoclipboard-wrapper">
    <pre class="programlisting language-sql"><div class="docs-select-all right" id="sa52485206"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-sql">kate<span class="token variable">@MYSQL.LOCAL</span>
kate<span class="token variable">@EXAMPLE.COM</span></code></pre>
   </div>
   <p>
    Both UPNs have a user part of
    <code class="literal">
     kate
    </code>
    but
          differ in the realm part (
    <code class="literal">
     MYSQL.LOCAL
    </code>
    versus
    <code class="literal">
     EXAMPLE.COM
    </code>
    ). This is disallowed.
   </p>
   <h6>
    <a name="kerberos-usage-mysql-client-usage">
    </a>
    Use the MySQL Account to Connect to the MySQL Server
   </h6>
   <p>
    After a MySQL account that authenticates using Kerberos has
          been set up, clients can use it to connect to the MySQL server
          as follows:
   </p>
   <div class="orderedlist">
    <ol class="orderedlist" type="1">
     <li class="listitem">
      <p>
       Authenticate to Kerberos with the user principal name
              (UPN) and its password to obtain a ticket-granting ticket
              (TGT).
      </p>
     </li>
     <li class="listitem">
      <p>
       Use the TGT to obtain a service ticket (ST) for MySQL.
      </p>
     </li>
     <li class="listitem">
      <p>
       Authenticate to the MySQL server by presenting the MySQL
              ST.
      </p>
     </li>
    </ol>
   </div>
   <p>
    The first step (authenticating to Kerberos) can be performed
          various ways:
   </p>
   <div class="itemizedlist">
    <ul class="itemizedlist" style="list-style-type: disc; ">
     <li class="listitem">
      <p>
       Prior to connecting to MySQL:
      </p>
      <div class="itemizedlist">
       <ul class="itemizedlist" style="list-style-type: circle; ">
        <li class="listitem">
         <p>
          On Linux or on Windows in
          <code class="literal">
           GSSAPI
          </code>
          mode, invoke
          <span class="command">
           <strong>
            kinit
           </strong>
          </span>
          to obtain the
                  TGT and save it in the Kerberos credentials cache.
         </p>
        </li>
        <li class="listitem">
         <p>
          On Windows in
          <code class="literal">
           SSPI
          </code>
          mode,
                  authentication may already have been done at login
                  time, which saves the TGT for the logged-in user in
                  the Windows in-memory cache.
          <span class="command">
           <strong>
            kinit
           </strong>
          </span>
          is not used and there is no Kerberos cache.
         </p>
        </li>
       </ul>
      </div>
     </li>
     <li class="listitem">
      <p>
       When connecting to MySQL, the client program itself can
              obtain the TGT, if it can determine the required Kerberos
              UPN and password:
      </p>
      <div class="itemizedlist">
       <ul class="itemizedlist" style="list-style-type: circle; ">
        <li class="listitem">
         <p>
          That information can come from sources such as command
                  options or the operating system.
         </p>
        </li>
        <li class="listitem">
         <p>
          On Linux, clients also can use a keytab file or the
          <code class="filename">
           /etc/krb5.conf
          </code>
          configuration
                  file. Windows clients in
          <code class="literal">
           GSSAPI
          </code>
          mode use a configuration file. Windows clients in
          <code class="literal">
           SSPI
          </code>
          mode use neither.
         </p>
        </li>
       </ul>
      </div>
     </li>
    </ul>
   </div>
   <p>
    Details of the client commands for connecting to the MySQL
          server differ for Linux and Windows, so each host type is
          discussed separately, but these command properties apply
          regardless of host type:
   </p>
   <div class="itemizedlist">
    <ul class="itemizedlist" style="list-style-type: disc; ">
     <li class="listitem">
      <p>
       Each command shown includes the following options, but
              each one may be omitted under certain conditions:
      </p>
      <div class="itemizedlist">
       <ul class="itemizedlist" style="list-style-type: circle; ">
        <li class="listitem">
         <p>
          The
          <a class="link" href="connection-options.html#option_general_default-auth">
           <code class="option">
            --default-auth
           </code>
          </a>
          option specifies the name of the client-side
                  authentication plugin
                  (
          <code class="literal">
           authentication_kerberos_client
          </code>
          ).
                  This option may be omitted when the
          <a class="link" href="connection-options.html#option_general_user">
           <code class="option">
            --user
           </code>
          </a>
          option is
                  specified because in that case MySQL can determine the
                  plugin from the user account information sent by MySQL
                  server.
         </p>
        </li>
        <li class="listitem">
         <p>
          The
          <a class="link" href="connection-options.html#option_general_plugin-dir">
           <code class="option">
            --plugin-dir
           </code>
          </a>
          option indicates to the client program the location of
                  the
          <code class="literal">
           authentication_kerberos_client
          </code>
          plugin. This option may be omitted if the plugin is
                  installed in the default (compiled-in) location.
         </p>
        </li>
       </ul>
      </div>
     </li>
     <li class="listitem">
      <p>
       Commands should also include any other options such as
       <a class="link" href="connection-options.html#option_general_host">
        <code class="option">
         --host
        </code>
       </a>
       or
       <a class="link" href="connection-options.html#option_general_port">
        <code class="option">
         --port
        </code>
       </a>
       that are required
              to specify which MySQL server to connect to.
      </p>
     </li>
     <li class="listitem">
      <p>
       Enter each command on a single line. If the command
              includes a
       <a class="link" href="connection-options.html#option_general_password">
        <code class="option">
         --password
        </code>
       </a>
       option to solicit a password, enter the password of the
              Kerberos UPN associated with the MySQL user when prompted.
      </p>
     </li>
    </ul>
   </div>
   <p>
    <span class="strong">
     <a name="kerberos-usage-linux-client-commands">
     </a>
     <strong>
      Connection
          Commands for Linux Clients
     </strong>
    </span>
   </p>
   <p>
    On Linux, the appropriate client command for connecting to the
          MySQL server varies depending on whether the command
          authenticates using a TGT from the Kerberos cache, or based on
          command options for the MySQL user name and the UPN password:
   </p>
   <div class="itemizedlist">
    <ul class="itemizedlist" style="list-style-type: disc; ">
     <li class="listitem">
      <p>
       Prior to invoking the MySQL client program, the client
              user can obtain a TGT from the KDC independently of MySQL.
              For example, the client user can use
       <span class="command">
        <strong>
         kinit
        </strong>
       </span>
       to authenticate to Kerberos by
              providing a Kerberos user principal name and the principal
              password:
      </p>
      <div class="copytoclipboard-wrapper">
       <pre class="programlisting language-terminal"><div class="docs-select-all right" id="sa46768751"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-terminal"><span class="token prompt">$&gt; </span><span class="token command">kinit</span> karl@MYSQL<span class="token punctuation">.</span>LOCAL
Password for karl@MYSQL<span class="token punctuation">.</span>LOCAL<span class="token punctuation">:</span> <span class="token punctuation"></span><em class="replaceable"><span class="token punctuation">(</span>enter password here<span class="token punctuation">)</span></em><span class="token punctuation"></span></code></pre>
      </div>
      <p>
       The resulting TGT for the UPN is cached and becomes
              available for use by other Kerberos-aware applications,
              such as programs that use the client-side Kerberos
              authentication plugin. In this case, invoke the client
              without specifying a user-name or password option:
      </p>
      <div class="copytoclipboard-wrapper">
       <pre class="programlisting language-terminal"><div class="docs-select-all right" id="sa55840832"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-terminal">mysql
  <span class="token constant">--default-auth</span><span class="token attr-value"><span class="token punctuation">=</span>authentication_kerberos_client</span>
  <span class="token constant">--plugin-dir</span><span class="token attr-value"><span class="token punctuation">=</span><em class="replaceable">path/to/plugin/directory</em></span></code></pre>
      </div>
      <p>
       The client-side plugin finds the TGT in the cache, uses it
              to obtain a MySQL ST, and uses the ST to authenticate to
              the MySQL server.
      </p>
      <p>
       As just described, when the TGT for the UPN is cached,
              user-name and password options are not needed in the
              client command. If the command includes them anyway, they
              are handled as follows:
      </p>
      <div class="itemizedlist">
       <ul class="itemizedlist" style="list-style-type: circle; ">
        <li class="listitem">
         <p>
          This command includes a user-name option:
         </p>
         <div class="copytoclipboard-wrapper">
          <pre class="programlisting language-terminal"><div class="docs-select-all right" id="sa57899421"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-terminal">mysql
  <span class="token constant">--default-auth</span><span class="token attr-value"><span class="token punctuation">=</span>authentication_kerberos_client</span>
  <span class="token constant">--plugin-dir</span><span class="token attr-value"><span class="token punctuation">=</span><em class="replaceable">path/to/plugin/directory</em></span>
  <span class="token constant">--user</span><span class="token attr-value"><span class="token punctuation">=</span>karl</span></code></pre>
         </div>
         <p>
          In this case, authentication fails if the user name
                  specified by the option does not match the user name
                  part of the UPN in the TGT.
         </p>
        </li>
        <li class="listitem">
         <p>
          This command includes a password option, which you
                  enter when prompted:
         </p>
         <div class="copytoclipboard-wrapper">
          <pre class="programlisting language-terminal"><div class="docs-select-all right" id="sa22498145"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-terminal">mysql
  <span class="token constant">--default-auth</span><span class="token attr-value"><span class="token punctuation">=</span>authentication_kerberos_client</span>
  <span class="token constant">--plugin-dir</span><span class="token attr-value"><span class="token punctuation">=</span><em class="replaceable">path/to/plugin/directory</em></span>
  <span class="token property">--password</span></code></pre>
         </div>
         <p>
          In this case, the client-side plugin ignores the
                  password. Because authentication is based on the TGT,
                  it can succeed
          <span class="emphasis">
           <em>
            even if the user-provided
                  password is incorrect
           </em>
          </span>
          . For this reason, the
                  plugin produces a warning if a valid TGT is found that
                  causes a password to be ignored.
         </p>
        </li>
       </ul>
      </div>
     </li>
     <li class="listitem">
      <p>
       If the Kerberos cache contains no TGT, the client-side
              Kerberos authentication plugin itself can obtain the TGT
              from the KDC. Invoke the client with options for the MySQL
              user name and the password, then enter the UPN password
              when prompted:
      </p>
      <div class="copytoclipboard-wrapper">
       <pre class="programlisting language-terminal"><div class="docs-select-all right" id="sa2023431"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-terminal">mysql <span class="token constant">--default-auth</span><span class="token attr-value"><span class="token punctuation">=</span>authentication_kerberos_client</span>
  <span class="token constant">--plugin-dir</span><span class="token attr-value"><span class="token punctuation">=</span><em class="replaceable">path/to/plugin/directory</em></span>
  <span class="token constant">--user</span><span class="token attr-value"><span class="token punctuation">=</span>karl</span>
  <span class="token property">--password</span></code></pre>
      </div>
      <p>
       The client-side Kerberos authentication plugin combines
              the user name (
       <code class="literal">
        karl
       </code>
       ) and the realm
              specified in the user account
              (
       <code class="literal">
        MYSQL.LOCAL
       </code>
       ) to construct the UPN
              (
       <code class="literal">
        karl@MYSQL.LOCAL
       </code>
       ). The client-side
              plugin uses the UPN and password to obtain a TGT, uses the
              TGT to obtain a MySQL ST, and uses the ST to authenticate
              to the MySQL server.
      </p>
      <p>
       Or, suppose that the Kerberos cache contains no TGT and
              the command specifies a password option but no user-name
              option:
      </p>
      <div class="copytoclipboard-wrapper">
       <pre class="programlisting language-terminal"><div class="docs-select-all right" id="sa6035891"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-terminal">mysql <span class="token constant">--default-auth</span><span class="token attr-value"><span class="token punctuation">=</span>authentication_kerberos_client</span>
  <span class="token constant">--plugin-dir</span><span class="token attr-value"><span class="token punctuation">=</span><em class="replaceable">path/to/plugin/directory</em></span>
  <span class="token property">--password</span></code></pre>
      </div>
      <p>
       The client-side Kerberos authentication plugin uses the
              operating system login name as the MySQL user name. It
              combines that user name and the realm in the user'
              MySQL account to construct the UPN. The client-side plugin
              uses the UPN and the password to obtain a TGT, uses the
              TGT to obtain a MySQL ST, and uses the ST to authenticate
              to the MySQL server.
      </p>
     </li>
    </ul>
   </div>
   <p>
    If you are uncertain whether a TGT exists, you can use
    <span class="command">
     <strong>
      klist
     </strong>
    </span>
    to check.
   </p>
   <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
    <div class="admon-title">
     Note
    </div>
    <p>
     When the client-side Kerberos authentication plugin itself
            obtains the TGT, the client user may not want the TGT to be
            reused. As described in
     <a class="xref" href="kerberos-pluggable-authentication.html#kerberos-pluggable-authentication-mysql-client-config-parameters" title="Client Configuration Parameters for Kerberos Authentication">
      Client Configuration Parameters for Kerberos Authentication
     </a>
     ,
            the local
     <code class="literal">
      /etc/krb5.conf
     </code>
     file can be used
            to cause the client-side plugin to destroy the TGT when done
            with it.
    </p>
   </div>
   <p>
    <span class="strong">
     <a name="kerberos-usage-win-sspi-client-commands">
     </a>
     <strong>
      Connection
          Commands for Windows Clients in SSPI Mode
     </strong>
    </span>
   </p>
   <p>
    On Windows, using the default client-side plugin option
          (SSPI), the appropriate client command for connecting to the
          MySQL server varies depending on whether the command
          authenticates based on command options for the MySQL user name
          and the UPN password, or instead uses a TGT from the Windows
          in-memory cache. For details about GSSAPI mode on Windows, see
    <a class="link" href="kerberos-pluggable-authentication.html#kerberos-usage-win-gssapi-client-commands">
     Commands for Windows Clients in GSSAPI Mode
    </a>
    .
   </p>
   <p>
    A command can explicitly specify options for the MySQL user
          name and the UPN password, or the command can omit those
          options:
   </p>
   <div class="itemizedlist">
    <ul class="itemizedlist" style="list-style-type: disc; ">
     <li class="listitem">
      <p>
       This command includes options for the MySQL user name and
              UPN password:
      </p>
      <div class="copytoclipboard-wrapper">
       <pre class="programlisting language-terminal"><div class="docs-select-all right" id="sa56152124"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-terminal">mysql <span class="token constant">--default-auth</span><span class="token attr-value"><span class="token punctuation">=</span>authentication_kerberos_client</span>
  <span class="token constant">--plugin-dir</span><span class="token attr-value"><span class="token punctuation">=</span><em class="replaceable">path/to/plugin/directory</em></span>
  <span class="token constant">--user</span><span class="token attr-value"><span class="token punctuation">=</span>karl</span>
  <span class="token property">--password</span></code></pre>
      </div>
      <p>
       The client-side Kerberos authentication plugin combines
              the user name (
       <code class="literal">
        karl
       </code>
       ) and the realm
              specified in the user account
              (
       <code class="literal">
        MYSQL.LOCAL
       </code>
       ) to construct the UPN
              (
       <code class="literal">
        karl@MYSQL.LOCAL
       </code>
       ). The client-side
              plugin uses the UPN and password to obtain a TGT, uses the
              TGT to obtain a MySQL ST, and uses the ST to authenticate
              to the MySQL server.
      </p>
      <p>
       Any information in the Windows in-memory cache is ignored;
              the user-name and password option values take precedence.
      </p>
     </li>
     <li class="listitem">
      <p>
       This command includes an option for the UPN password but
              not for the MySQL user name:
      </p>
      <div class="copytoclipboard-wrapper">
       <pre class="programlisting language-terminal"><div class="docs-select-all right" id="sa55821074"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-terminal">mysql
  <span class="token constant">--default-auth</span><span class="token attr-value"><span class="token punctuation">=</span>authentication_kerberos_client</span>
  <span class="token constant">--plugin-dir</span><span class="token attr-value"><span class="token punctuation">=</span><em class="replaceable">path/to/plugin/directory</em></span>
  <span class="token property">--password</span></code></pre>
      </div>
      <p>
       The client-side Kerberos authentication plugin uses the
              logged-in user name as the MySQL user name and combines
              that user name and the realm in the user's MySQL
              account to construct the UPN. The client-side plugin uses
              the UPN and the password to obtain a TGT, uses the TGT to
              obtain a MySQL ST, and uses the ST to authenticate to the
              MySQL server.
      </p>
     </li>
     <li class="listitem">
      <p>
       This command includes no options for the MySQL user name
              or UPN password:
      </p>
      <div class="copytoclipboard-wrapper">
       <pre class="programlisting language-terminal"><div class="docs-select-all right" id="sa65959498"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-terminal">mysql
  <span class="token constant">--default-auth</span><span class="token attr-value"><span class="token punctuation">=</span>authentication_kerberos_client</span>
  <span class="token constant">--plugin-dir</span><span class="token attr-value"><span class="token punctuation">=</span><em class="replaceable">path/to/plugin/directory</em></span></code></pre>
      </div>
      <p>
       The client-side plugin obtains the TGT from the Windows
              in-memory cache, uses the TGT to obtain a MySQL ST, and
              uses the ST to authenticate to the MySQL server.
      </p>
      <p>
       This approach requires the client host to be part of the
              Windows Server Active Directory (AD) domain. If that is
              not the case, help the MySQL client discover the IP
              address for the AD domain by manually entering the AD
              server and realm as the DNS server and prefix:
      </p>
      <div class="orderedlist">
       <ol class="orderedlist" type="1">
        <li class="listitem">
         <p>
          Start
          <code class="literal">
           console.exe
          </code>
          and select
          <span class="guilabel">
           Network and Sharing Center
          </span>
          .
         </p>
        </li>
        <li class="listitem">
         <p>
          From the sidebar of the Network and Sharing Center
                  window, select
          <span class="guilabel">
           Change adapter
                  settings
          </span>
          .
         </p>
        </li>
        <li class="listitem">
         <p>
          In the Network Connections window, right-click the
                  network or VPN connection to configure and select
          <span class="guimenuitem">
           Properties
          </span>
          .
         </p>
        </li>
        <li class="listitem">
         <p>
          From the
          <span class="guilabel">
           Network
          </span>
          tab, locate and
                  click
          <span class="guilabel">
           Internet Protocol Version 4
                  (TCP/IPv4)
          </span>
          , and then click
          <span class="guibutton">
           Properties
          </span>
          .
         </p>
        </li>
        <li class="listitem">
         <p>
          Click
          <span class="guibutton">
           Advanced
          </span>
          in the Internet
                  Protocol Version 4 (TCP/IPv4) Properties dialog. The
                  Advanced TCP/IP Settings dialog opens.
         </p>
        </li>
        <li class="listitem">
         <p>
          From the
          <span class="guilabel">
           DNS
          </span>
          tab, add the Active
                  Directory server and realm as a DNS server and prefix.
         </p>
        </li>
       </ol>
      </div>
     </li>
     <li class="listitem">
      <p>
       This command includes an option for the MySQL user name
              but not for the UPN password:
      </p>
      <div class="copytoclipboard-wrapper">
       <pre class="programlisting language-terminal"><div class="docs-select-all right" id="sa70067522"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-terminal">mysql
  <span class="token constant">--default-auth</span><span class="token attr-value"><span class="token punctuation">=</span>authentication_kerberos_client</span>
  <span class="token constant">--plugin-dir</span><span class="token attr-value"><span class="token punctuation">=</span><em class="replaceable">path/to/plugin/directory</em></span>
  <span class="token constant">--user</span><span class="token attr-value"><span class="token punctuation">=</span>karl</span></code></pre>
      </div>
      <p>
       The client-side Kerberos authentication plugin compares
              the name specified by the user-name option against the
              logged-in user name. If the names are the same, the plugin
              uses the logged-in user TGT for authentication. If the
              names differ, authentication fails.
      </p>
     </li>
    </ul>
   </div>
   <p>
    <span class="strong">
     <a name="kerberos-usage-win-gssapi-client-commands">
     </a>
     <strong>
      Connection
          Commands for Windows Clients in GSSAPI Mode
     </strong>
    </span>
   </p>
   <p>
    On Windows, the client user must specify
    <code class="literal">
     GSSAPI
    </code>
    mode explicitly using the
    <code class="literal">
     plugin_authentication_kerberos_client_mode
    </code>
    plugin option to enable support through the MIT Kerberos
          library. The default mode is
    <code class="literal">
     SSPI
    </code>
    (see
    <a class="link" href="kerberos-pluggable-authentication.html#kerberos-usage-win-sspi-client-commands">
     Commands
          for Windows Clients in SSPI Mode
    </a>
    ).
   </p>
   <a class="indexterm" name="idm46045244339984">
   </a>
   <a class="indexterm" name="idm46045244338528">
   </a>
   <p>
    It is possible to specify
    <code class="literal">
     GSSAPI
    </code>
    mode:
   </p>
   <div class="itemizedlist">
    <ul class="itemizedlist" style="list-style-type: disc; ">
     <li class="listitem">
      <p>
       Prior to invoking the MySQL client program in an option
              file. The plugin variable name is valid using either
              underscores or dashes:
      </p>
      <div class="copytoclipboard-wrapper">
       <pre class="programlisting language-ini"><div class="docs-select-all right" id="sa65254352"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-ini"><span class="token selector">[mysql]</span>
<span class="token constant">plugin_authentication_kerberos_client_mode</span><span class="token attr-value"><span class="token punctuation">=</span>GSSAPI</span></code></pre>
      </div>
      <p>
       Or:
      </p>
      <div class="copytoclipboard-wrapper">
       <pre class="programlisting language-ini"><div class="docs-select-all right" id="sa47453159"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-ini"><span class="token selector">[mysql]</span>
<span class="token constant">plugin-authentication-kerberos-client-mode</span><span class="token attr-value"><span class="token punctuation">=</span>GSSAPI</span></code></pre>
      </div>
     </li>
     <li class="listitem">
      <p>
       At runtime from the command line using the
       <a class="link" href="mysql.html" title="6.5.1 mysql — The MySQL Command-Line Client">
        <span class="command">
         <strong>
          mysql
         </strong>
        </span>
       </a>
       or
       <a class="link" href="mysqldump.html" title="6.5.4 mysqldump — A Database Backup Program">
        <span class="command">
         <strong>
          mysqldump
         </strong>
        </span>
       </a>
       client programs. For example, the following commands (with
              underscores or dashes) causes
       <a class="link" href="mysql.html" title="6.5.1 mysql — The MySQL Command-Line Client">
        <span class="command">
         <strong>
          mysql
         </strong>
        </span>
       </a>
       to
              connect to the server through the MIT Kerberos library on
              Windows.
      </p>
      <div class="copytoclipboard-wrapper">
       <pre class="programlisting one-line language-terminal"><div class="docs-select-all right" id="sa80472590"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-terminal">mysql <span class="token punctuation"></span><em class="replaceable"><span class="token punctuation">[</span>connection-options<span class="token punctuation">]</span></em><span class="token punctuation"></span> <span class="token constant">--plugin_authentication_kerberos_client_mode</span><span class="token attr-value"><span class="token punctuation">=</span>GSSAPI</span></code></pre>
      </div>
      <p>
       Or:
      </p>
      <div class="copytoclipboard-wrapper">
       <pre class="programlisting one-line language-terminal"><div class="docs-select-all right" id="sa85431522"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-terminal">mysql <span class="token punctuation"></span><em class="replaceable"><span class="token punctuation">[</span>connection-options<span class="token punctuation">]</span></em><span class="token punctuation"></span> <span class="token constant">--plugin-authentication-kerberos-client-mode</span><span class="token attr-value"><span class="token punctuation">=</span>GSSAPI</span></code></pre>
      </div>
     </li>
     <li class="listitem">
      <p>
       Client users can select
       <code class="literal">
        GSSAPI
       </code>
       mode
              from MySQL Workbench and some MySQL connectors. On client
              hosts running Windows, you can override the default
              location of:
      </p>
      <div class="itemizedlist">
       <ul class="itemizedlist" style="list-style-type: circle; ">
        <li class="listitem">
         <p>
          The Kerberos configuration file by setting the
          <code class="literal">
           KRB5_CONFIG
          </code>
          environment variable.
         </p>
        </li>
        <li class="listitem">
         <p>
          The default credential cache name with the
          <code class="literal">
           KRB5CCNAME
          </code>
          environment variable
                  (for example,
          <code class="literal">
           KRB5CCNAME=DIR:/mydir/
          </code>
          ).
         </p>
        </li>
       </ul>
      </div>
      <p>
       For specific client-side plugin information, see the
              documentation at
       <a class="ulink" href="/doc/" target="_top">
        https://dev.mysql.com/doc/
       </a>
       .
      </p>
     </li>
    </ul>
   </div>
   <p>
    The appropriate client command for connecting to the MySQL
          server varies depending on whether the command authenticates
          using a TGT from the MIT Kerberos cache, or based on command
          options for the MySQL user name and the UPN password. GSSAPI
          support through the MIT library on Windows is similar to
          GSSAPI on Linux (see
    <a class="link" href="kerberos-pluggable-authentication.html#kerberos-usage-linux-client-commands">
     Commands
          for Linux Clients
    </a>
    ), with the following exceptions:
   </p>
   <div class="itemizedlist">
    <ul class="itemizedlist" style="list-style-type: disc; ">
     <li class="listitem">
      <p>
       Tickets are always retrieved from or placed into the MIT
              Kerberos cache on hosts running Windows.
      </p>
     </li>
     <li class="listitem">
      <p>
       <span class="command">
        <strong>
         kinit
        </strong>
       </span>
       runs with Functional Accounts on
              Windows that have narrow permissions and specific roles.
              The client user does not know the
       <span class="command">
        <strong>
         kinit
        </strong>
       </span>
       password. For an overview, see
       <a class="ulink" href="https://docs.oracle.com/en/java/javase/11/tools/kinit.html" target="_blank">
        https://docs.oracle.com/en/java/javase/11/tools/kinit.html
       </a>
       .
      </p>
     </li>
     <li class="listitem">
      <p>
       If the client user supplies a password, the MIT Kerberos
              library on Windows decides whether to use it or rely on
              the existing ticket.
      </p>
     </li>
     <li class="listitem">
      <p>
       The
       <code class="literal">
        destroy_tickets
       </code>
       parameter,
              described in
       <a class="xref" href="kerberos-pluggable-authentication.html#kerberos-pluggable-authentication-mysql-client-config-parameters" title="Client Configuration Parameters for Kerberos Authentication">
        Client Configuration Parameters for Kerberos Authentication
       </a>
       ,
              is not supported because the MIT Kerberos library on
              Windows does not support the required API member
              (
       <code class="code">
        get_profile_boolean
       </code>
       ) to read its value from
              configuration file.
      </p>
     </li>
    </ul>
   </div>
   <h6>
    <a name="kerberos-pluggable-authentication-mysql-client-config-parameters">
    </a>
    Client Configuration Parameters for Kerberos Authentication
   </h6>
   <p>
    This section applies only for client hosts running Linux, not
          client hosts running Windows.
   </p>
   <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
    <div class="admon-title">
     Note
    </div>
    <p>
     A client host running Windows with the
     <code class="literal">
      authentication_kerberos_client
     </code>
     client-side Kerberos plugin set to
     <code class="literal">
      GSSAPI
     </code>
     mode does support client configuration parameters, in
            general, but the MIT Kerberos library on Windows does not
            support the
     <code class="literal">
      destroy_tickets
     </code>
     parameter
            described in this section.
    </p>
   </div>
   <p>
    If no valid ticket-granting ticket (TGT) exists at the time of
          MySQL client application invocation, the application itself
          may obtain and cache the TGT. If during the Kerberos
          authentication process the client application causes a TGT to
          be cached, any such TGT that was added can be destroyed after
          it is no longer needed, by setting the appropriate
          configuration parameter.
   </p>
   <p>
    The
    <code class="literal">
     authentication_kerberos_client
    </code>
    client-side Kerberos plugin reads the local
    <code class="filename">
     /etc/krb5.conf
    </code>
    file. If this file is
          missing or inaccessible, an error occurs. Assuming that the
          file is accessible, it can include an optional
    <code class="literal">
     [appdefaults]
    </code>
    section to provide
          information used by the plugin. Place the information within
          the
    <code class="literal">
     mysql
    </code>
    part of the section. For example:
   </p>
   <a class="indexterm" name="idm46045244297312">
   </a>
   <a class="indexterm" name="idm46045244295824">
   </a>
   <a class="indexterm" name="idm46045244294336">
   </a>
   <a class="indexterm" name="idm46045244292832">
   </a>
   <div class="copytoclipboard-wrapper">
    <pre class="programlisting language-ini"><div class="docs-select-all right" id="sa11158014"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-ini"><span class="token selector">[appdefaults]</span>
<span class="token constant">  mysql</span> <span class="token attr-value"><span class="token punctuation">=</span> {</span>
<span class="token constant">    destroy_tickets</span> <span class="token attr-value"><span class="token punctuation">=</span> true</span>
  }</code></pre>
   </div>
   <p>
    The client-side plugin recognizes these parameters in the
    <code class="literal">
     mysql
    </code>
    section:
   </p>
   <div class="itemizedlist">
    <ul class="itemizedlist" style="list-style-type: disc; ">
     <li class="listitem">
      <p>
       The
       <code class="literal">
        destroy_tickets
       </code>
       value indicates
              whether the client-side plugin destroys the TGT after
              obtaining and using it. By default,
       <code class="literal">
        destroy_tickets
       </code>
       is
       <code class="literal">
        false
       </code>
       , but can be set to
       <code class="literal">
        true
       </code>
       to avoid TGT reuse. (This setting
              applies only to TGTs created by the client-side plugin,
              not TGTs created by other plugins or externally to MySQL.)
      </p>
     </li>
    </ul>
   </div>
   <a class="indexterm" name="idm46045244284768">
   </a>
   <p>
    On the client host, a client keytab file may be used to obtain
          a TGT and TS without supplying a password. For information
          about keytab files, see
    <a class="ulink" href="https://web.mit.edu/kerberos/krb5-latest/doc/basic/keytab_def.html" target="_blank">
     https://web.mit.edu/kerberos/krb5-latest/doc/basic/keytab_def.html
    </a>
    .
   </p>
  </div>
  <div class="simplesect">
   <div class="titlepage">
    <div>
     <div class="simple">
      <h5 class="title">
       <a name="kerberos-pluggable-authentication-debugging">
       </a>
       Kerberos Authentication Debugging
      </h5>
     </div>
    </div>
   </div>
   <a class="indexterm" name="idm46045244280704">
   </a>
   <a class="indexterm" name="idm46045244279664">
   </a>
   <p>
    The
    <code class="literal">
     AUTHENTICATION_KERBEROS_CLIENT_LOG
    </code>
    environment variable enables or disables debug output for
          Kerberos authentication.
   </p>
   <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
    <div class="admon-title">
     Note
    </div>
    <p>
     Despite
     <code class="literal">
      CLIENT
     </code>
     in the name
     <code class="literal">
      AUTHENTICATION_KERBEROS_CLIENT_LOG
     </code>
     , the
            same environment variable applies to the server-side plugin
            as well as the client-side plugin.
    </p>
   </div>
   <p>
    On the server side, the permitted values are 0 (off) and 1
          (on). Log messages are written to the server error log,
          subject to the server error-logging verbosity level. For
          example, if you are using priority-based log filtering, the
    <a class="link" href="server-system-variables.html#sysvar_log_error_verbosity">
     <code class="literal">
      log_error_verbosity
     </code>
    </a>
    system
          variable controls verbosity, as described in
    <a class="xref" href="error-log-priority-based-filtering.html" title="7.4.2.5 Priority-Based Error Log Filtering (log_filter_internal)">
     Section 7.4.2.5, “Priority-Based Error Log Filtering (log_filter_internal)”
    </a>
    .
   </p>
   <p>
    On the client side, the permitted values are from 1 to 5 and
          are written to the standard error output. The following table
          shows the meaning of each log-level value.
   </p>
   <div class="informaltable">
    <table summary="Permitted client-side AUTHENTICATION_KERBEROS_CLIENT_LOG log levels and corresponding meanings">
     <colgroup>
      <col style="width: 40%"/>
      <col style="width: 40%"/>
     </colgroup>
     <thead>
      <tr>
       <th>
        Log Level
       </th>
       <th>
        Meaning
       </th>
      </tr>
     </thead>
     <tbody>
      <tr>
       <td>
        1 or not set
       </td>
       <td>
        No logging
       </td>
      </tr>
      <tr>
       <td>
        2
       </td>
       <td>
        Error messages
       </td>
      </tr>
      <tr>
       <td>
        3
       </td>
       <td>
        Error and warning messages
       </td>
      </tr>
      <tr>
       <td>
        4
       </td>
       <td>
        Error, warning, and information messages
       </td>
      </tr>
      <tr>
       <td>
        5
       </td>
       <td>
        Error, warning, information, and debug messages
       </td>
      </tr>
     </tbody>
    </table>
   </div>
  </div>
 </div>
 <br/>
</div>
