GSSAPI / Kerberos authentication for Axigen installed on Linux

Authentication / Authorization

Updated: July 9, 2021

About GSSAPI / Kerberos

The GSSAPI (Generic Security Services API) is a common interface for accessing the Kerberos security system used by Microsoft Windows.

Enabling GSSAPI / Kerberos authentication in Axigen will allow single-sign-on – i.e. authentication without using the standard username and password for clients that are part of an Active Directory domain.

Before Start

Check that all nodes (Domain Controller, Axigen Server, Windows Clients) have their clock synchronized, for example with the same NTP source.

On the Domain Controller

  • Create an auxiliary account named axigen_<serviceName> in Active Directory corresponding to each service you want to authenticate on from Axigen. This account will be used for creating a SPN (service principal name). Three accounts will be used for all Axigen supported services: axigen_smtp, axigen_imap, and axigen_pop.

  • Start "Command Prompt" as Administrator and use the KTPASS utility to export the keytab file for each service

    • Generate a key for the SMTP service: ktpass -princ smtp/<axigen.hostname>@<REALM> -mapuser axigen_smtp -pass <PASSWORD> -out axigen-smtp.keytab -ptype KRB5_NT_PRINCIPAL

    • Generate a key for the IMAP service: ktpass -princ imap/<axigen.hostname>@<REALM> -mapuser axigen_imap -pass <PASSWORD> -out axigen-imap.keytab -ptype KRB5_NT_PRINCIPAL

    • Generate keys for the POP3 service: ktpass -princ pop/<axigen.hostname>@<REALM> -mapuser axigen_pop -pass <PASSWORD> -out axigen-pop.keytab -ptype KRB5_NT_PRINCIPAL

In all commands shown above, you need to replace:

<axigen.hostname> with the hostname.domain of machine where Axigen service is running
<REALM> with the Kerberos realm, which is the uppercase name of the Active Directory domain (which should be the same with the Axigen domain name)
<PASSWORD> with the password for the corresponding "axigen_SERVICE" account, which you have previously created.

Please note that the Axigen IP address must have the PTR DNS record set to the same hostname you have specified above as "axigen.hostname". 

Example

On the Axigen server

  • Install Kerberos programs using your OS package manager:

    • Cent OS 7: yum install krb5-workstation

    • RedHat 7: yum install krb5-workstation

    • Ubuntu 18.04: apt install krb5-user

    • OpenSUSE: zypper install krb5-client

  • Copy the exported key files on the Axigen machine in the /etc directory and merge them using the "ktutil" application. Simply type "ktutil" and issue the following commands in the application's subshell:

    • Load the needed "keytab" files, according to the services you want to use GSSAPI authentication with:

    • Write the new /etc/krb5.keytab file:

    • Exit the "ktutil" shell:

  • Set the proper permissions on the generated file (/etc/krb5.keytab) with the command:

  • Edit the /etc/krb5.conf file and make sure you have the following lines:

In this configuration file, you need to replace:

<REALM> with the Kerberos realm, which is the uppercase name of the Active Directory domain (which should be the same with the Axigen domain name)
<domain.tld> with the domain name that will be used in Axigen

Example

Client Configuration

Using the Thunderbird email client, add a new account and choose as authentication type to "Kerberos / GSSAPI" (could be on a plain or SSL enabled listener).

When adding the account into the email client, configure it using the account name (without the domain part) – like john.doe (tick) and not john.doe@domain.lan (error)

To check if the "Kerberos / GSSAPI" for is working properly set the log level to Protocol Communication, open the Thunderbird client and search for authentication session similar with:

IMAP

POP3

SMTP

Documentation updates

This documentation was first validated on CentOS 7.2. As newer versions of Kerberos packages have been provided by the latest CentOS 7 and RHEL 8, this document will include the necessary updates to be taken into consideration.

Update #1

  • For errors like:

    • sasl_server_step error: 'SASL(-1): generic failure: GSSAPI Error: Unspecified GSS failure. Minor code may provide more information (Permission denied)'

      • check the permissions for /etc/krb5.keytab

    • sasl_server_step error: 'SASL(-13): authentication failure: GSSAPI Failure: gss_accept_sec_context

      • check permitted_enctypes

    • sasl_server_step error: 'SASL(-13): authentication failure: Requested identity not authenticated identity'

      • check how the account is configured in the email client

  • For RHEL 8 and similar: add the arcfour-hmac-md5 encryption type into permitted_enctypes from /etc/krb5.conf.d/crypto-policies