How to set up SSO (Single Sign-On) in IceWarp

This guide will help you setup SSO from the very beginning. The prerequisite for successful setup is to set up Active Directory Domain Services.

IMPORTANT: An issue has been identified with keytab authentication on Windows Server 2019 due to changes in supported encryption ciphers. It is now necessary to enable AES 256 Encryption for the four SSO users used for authentication. Although AES 128 is an option, AES 256 is preferred for enhanced security. Without this, SSO will not function correctly. This can be configured by accessing the SSO accounts on the domain controller, navigating to Properties > Accounts, and selecting the appropriate encryption settings (refer to the "User Creation" section in the Step-by-Step Setup Guide for screenshots). This issue is indicated in Icewarp’s Kerberos log by the error message “Encryption type not permitted.”

Example of the error in Kerberos log:

SYSTEM          [00007FF633974700] 17:50:55 SSO Auth, Token=YIIGgwYGKw.., VHost=mail.infra.com mail.infra.com@INFRA.LOC->Err (gss_accept_sec_context() failed: Unspecified GSS failure.  Minor code may provide more information (, Encryption type not permitted)[851968;100005]), trying next domains,  matching domain not found in IW

• IW server hostname: example.somewhere.com
• email domain: examplesomewhere.com
• AD domain: SOMEWHERE.LOCAL

Keytab Creation Process

1. Create Domain Users:

   • For each keytab, create a corresponding domain user in the default OU

     OU=USERS,DC=SOMEWHERE,DC=LOCAL

   • Assign an appropriate password, e.g., somepass1234.

        The required users are:

icewarp_http
icewarp_imap
icewarp_xmpp
icewarp_smtp

2. Generate Keytabs:

• Open cmd.exe as an administrator on the Active Directory (AD) server and run the following commands for each service user:

ktpass /out HTTP#example.somewhere.com@SOMEWHERE.LOCAL /princ HTTP/example.somewhere.
com@SOMEWHERE.LOCAL /mapuser icewarp_http / crypto all /ptype KRB5_NT_PRINCIPAL /
pass somepass1234
ktpass /out imap#example.somewhere.com@SOMEWHERE.LOCAL /princ imap/example.somewhere.
com@SOMEWHERE.LOCAL /mapuser icewarp_imap /crypto all /ptype KRB5_NT_PRINCIPAL /
pass somepass1234
ktpass /out xmpp#example.somewhere.com@SOMEWHERE.LOCAL /princ xmpp/example.somewhere.
com@SOMEWHERE.LOCAL /mapuser icewarp_xmpp /crypto all /ptype KRB5_NT_PRINCIPAL /
pass somepass1234
ktpass /out smtp#example.somewhere.com@SOMEWHERE.LOCAL /princ smtp/example.somewhere.
com@SOMEWHERE.LOCAL /mapuser icewarp_smtp /crypto all /ptype KRB5_NT_PRINCIPAL 
/pass somepass1234

Checklist:

• Verify the hostname in the keytab matches the Icewarp server hostname.
• Ensure GSSAPI is enabled in Icewarp under System > Advanced .
• Confirm that in the domain (examplesomewhere.com ) in Directory Service settings of Icewarp, the Kerberos/GSSAPI/SSO service name matches the keytab (example.somewhere.com@SOMEWHERE.LOCAL)
• Ensure valid certificates are present for example.somewhere.com a autodiscover.examplesomewhere.com
• Verify SRV records:

Note: Windows ignores KVNO versions.

Debug Commands on Windows:

• List Kerberos tokens on the client computer:

klist

• List Service Principal Names (SPN):

setspn -Q */*

__________________________________________________________________________

Step-by-Step SSO Setup (Server Perspective)

This guide assists in setting up SSO from scratch, assuming Active Directory Domain Services (AD DS) are already configured. You'll need access to a Domain Controller, Icewarp server (via SSH or RDP), and possibly the DNS server (often the Domain Controller).

Setting up SSO on Icewarp requires prior directory synchronization and that users are set to authenticate against the Domain Controller used to create keytabs. Users who do not authenticate against the domain cannot use SSO.

Note: Remote users without VPN or domain login cannot use SSO.

For detailed instructions on setting up Active Directory synchronization, refer to our Documentation: Directory Service.

Important: Initial directory synchronization is necessary to set the authentication 
type to "LDAP/Active Directory" and fill out authentication strings. Although SSO can 
work without ongoing directory synchronization, the initial sync is critical.

User Creation for SSO Authentication

Create Service Accounts:

• Create accounts for the services you wish to authenticate (e.g., HTTP, SMTP, IMAP, XMPP). If you only need web client access, create icewarp_http and icewarp_xmpp. For full functionality (Outlook sync, IWDC), all four accounts are required.
  • Open Active Directory Users and Computers from the Start menu.

•  
  • In the default domain (e.g., infra.loc), navigate to OU= Users.
  • Select "Create a new user in the current container" and fill in the necessary details.

•  
  • In the user creation process, enter the "Last name" and "User logon name" fields as shown in the screenshot. Ensure that the user is being created in the correct domain and container, as indicated at the top of the window. Once all details are filled in, click "Next" to proceed.
  •  
  • Set a complex password, ensure "Password never expires" is checked, and "User must change password at next logon" is unchecked. Complete the process by clicking "Finish."

•  
  • Repeat the above steps for the other accounts (icewarp_smtp, icewarp_imap, icewwarp_xmpp)

Allow AES 256 Encryption:

•  
  • For each SSO account, go to Properties > Account and enable "This account supports Kerberos AES 256-bit encryption."
  • Apply the settings for all relevant accounts.

Keytab Creation

Keytabs are encrypted files used by the server to authenticate against the domain without being in the domain itself. Each service (HTTP, SMTP, IMAP, XMPP) requires its keytab. Note that HTTP must be in uppercase as per Microsoft naming conventions.

Example Command:

ktpass out c:\HTTP#mail.server.com@DOMAIN.LOC -princ HTTP/mail.server.com@DOMAIN.LOC -
mapUser sso_user@ad_domain.loc mapOp set pass * -ptype KRB5_NT_PRINCIPAL /crypto all

Important: If a mistake is made during keytab creation, delete the associated account and recreate it, as the Domain Controller retains hidden metadata that can cause issues.

_________________________________________________________________________

Some explanations are necessary:

ktpass - command for creating keytabs

out - path and name of file (e.g. how the keytab file will be named)

-princ - principal name of the service (HTTP), mail server (mail.infra.com) and AD domain name (INFRA.LOC). 

Note: Name of AD domain MUST be in UPPER case in this field

-mapuser - which user will be used to authenticate the service/keytab

-ptype - type of keytab file

mapOp set pass * - will ask you for password interactively to avoid showing the SSO 
user's password on the command line

/crypto - specifying cipthers supported, in this all available

<mail.server.com> - replace with your actual mail server FQDN - e.g. mail.infra.com

<DOMAIN.LOC> - replace with your actual AD domain name (please note that it must be in 
UPPER case) - e.g. INFRA.LOC

<service_name> - can be HTTP, smtp, imap or xmpp (please note upper case on HTTP - 
this is necessary)

<sso_user@ad_domain.com> - replace with actual SSO user for a specific service, 
e.g. icewarp_http@infra.loc. MUST be linked with one of the service_names (e.g. HTTP). 
Please note that this is the user in AD, not on your mail server

Setting Up SSO on Icewarp

1. Copy Keytabs to Icewarp Server:

    

   • Place the keytab files in the icewarp/config/_keytabs directory. Create the directory if it doesn't exist.
   • Ensure correct ownership and group permissions are set, especially if using Linux

(e.g., if you run icewarp services under user and not root, don't forget to change the ownership via chown command on both the folder and the files)

chown -Rv icewarp:icewarp /opt/icewarp/config/_keytabs/

Note: If you are using a different account than icewarp to run services, replace the user in the above command with the correct account. This does not apply for Windows OS.

1.  

   1. Configure Icewarp:

•  
  • In the Icewarp administration console, go to the relevant domain's Directory service tab and fill in the Kerberos/GSSAPI/SSO service name with <mail.server.com>@<DOMAIN.LOC> (e.g., mail.infra.com@INFRA.LOC).
  • Set "Remote account matching" to "Match with alias."

1.  
   • Enable GSSAPI SASL under System > Advanced > Protocol.

1. Browser Configuration for SSO:

   • Add the webmail address to the trusted sites list in your browser.
   • To test, log in to the AD domain, open a browser, and navigate to:
    

   https://<mail.server.com>/webmail/sso
   

   If configured correctly, you should be redirected to your webmail without need to enter credentials.

2. SSO/Kerberos Autodiscover with IWDC:
   • Ensure the above setup is complete.
   • Create a local DNS zone, an A record for the mail server, and an MX record pointing to the A record.

IMPORTANT: Do not create an autodiscover.somewhere.com in local DNS to avoid 
authentication issues.

Additional Information on Kerberos/SSO

• The email address of the AD user is irrelevant for SSO authentication.
• The domain the user is logged into matters.
• It’s possible for users to log into multiple domains if the same keytab is used across domains, which can be risky.
• The hostname used must match the SPN and be consistent with the keytab's service name.
• Multiple SPNs on a single service account are generally unnecessary for Icewarp’s current version.

Troubleshooting Tips

If you have direct access to the domain controller and are permitted to install a browser there, but the customer cannot provide a testing station, you may need to log in and launch applications as a different user synced to the IceWarp server, without logging out of the admin account. Typically, the domain controller administrator account is not synced to IceWarp and cannot authenticate via AD using the keytab. Therefore, you'll want to log in as a regular user while remaining logged into the domain controller as an administrator.

To achieve this, you can launch Windows applications as a different domain user without logging out. Here are a few methods:

1. Run Application as Another User:

   • Open "Run" from the Start menu (or press  Windows key + R).

   • Type the following command:

     runas /u:<username>@<ad_domain> /p:<password> <path_to_exe>
     

     Example:

     runas /u:marek@infra.loc /p:Merak-123 "C:\Program Files\Mozilla Firefox\firefox.exe"
     

   • To avoid displaying the password in plain text, omit /p:  and you'll be prompted for the password. You can also omit  <ad_domain>to default to the domain.

   Note: If any error occurs, the command window may close immediately, making it 
   difficult to diagnose the problem. More experienced administrators might recognize <username>@<ad_domain> as the User Principal Name (UPN).

2. Run Command Prompt as Another User:

   • Open "Run" and launch cmd as a different user:

     runas /u:marek@infra.loc /p:Merak-123 cmd
     

   • From this command prompt, you can launch any application, such as  firefox.exe . If errors occur, they will be visible in this window, though login issues may still be hidden.
3. Nested Command Prompts (Preferred Method):
   • Launch cmd as the currently logged-in user

   • From this prompt, launch another instance of cmd as a different user:

     runas /u:marek@infra.loc /p:Merak-123 cmd
     

   • Navigate to the application directory and run the application:

     cd "C:\Program Files\Mozilla Firefox\" firefox.exe
     

   • This approach displays all errors, including access credential failures.

From here, you can attempt to access the Webmail SSO URL:

https://mail.infra.com/webmail/sso

Checking and Deleting Kerberos Tickets:

• Use the klist command to list Kerberos tickets.  (More information about command here .)
• Use klist purge to delete all tickets, which can help resolve issues caused by cached tickets with incorrect SPNs. 

For further debugging, enable Kerberos logs in Remote Console under  System > Logging > Debug > Kerberos (extended).