Configuring SPNEGO Single Sign-On

The SPNEGO protocol mechanism can be configured on {product-abbrev} for single sign-on authentication to the {product-short} {web-client}, and to the Zimbra Connector for Outlook (ZCO). For ZCO configuration see Setting Up Single Sign-On Options for ZCO.

When users have authenticated to their Intranet through Active Directory, they can enter their {product-short} mailbox using {either-web-client} without having to re-authenticate.

The {product-abbrev} server configuration will redirect users attempting to log on to the {either-web-client} to a URL under SPNEGO protection. The server asks for authentication with Kerberos through SPNEGO, and redirects users to their {product-short} mailbox. When users log out, they get redirected to a logout URL that displays a btn:[Launch] button. When users click it, they get directed to the {product-short} login page.

Note	When users log on to their {product-short} accounts from the Internet, the {product-short} login page displays and they must enter their {product-short} password to log on.

Important

With SPNEGO SSO enabled on a domain, corresponding browser configuration is essential. See Configure Your Browser. Improperly configured browsers may bypass SPNEGO by opening an authentication dialog, thereby allowing a user to log in to the Zimbra mailbox by entering their correct AD domain username/password. Some other browsers may display a "401 Unauthorized" error in that situation.

Configuration Process

Create the Kerberos keytab file.
- Create an Active Directory service account. You use this account to generate the Kerberos keytab file.
- Add the service Principal Names (SPN) directory property for an Active Directory service account.
- Create the keytab file.
Enable and configure the SPNEGO protocol on the {product-abbrev} server.
Configure browsers

Create the Kerberos Keytab File

Create an Active Directory service Domain account for each mailstore server.

Create an Active Directory service account. You use this account to generate the Kerberos keytab file to add to the Zimbra server.
1. Go to the Active Directory Start → Programs → Administrative Tools → Active Directory Users and Computers console.
2. To create the service account, click the AD Domain name and from the expanded content right-click Users and select New → User. Complete the New Object – User dialog.
  - Full name: Enter the user display name for the AD service account. We recommend using the {product-abbrev} mailbox server name as the full name.
    
    Example: Zimbra SPNEGO.
  - User Logon Name: This name is the value set for the zimbraSpnegoAuthTargetName server attribute in LDAP. Write it down.
    
    Example: zimbraspnego/zimbralab.local.
  - User Logon Name (pre-Windows2000): This name is used for the –mapUser parameter in the setspn and ktpass commands.
    
    Example: ZIMBRALAB\zimbraspnego.
  - Click btn:[Next].
3. Enter and confirm the password for the –pass {AD-user-password} parameter in the ktpass command, configured below.
4. Check Password never expires and User cannot change password, and click btn:[Next].
5. Click btn:[Finish] to create the user. The service account name displays in the Users directory.
Use the setspn command to map the mailbox server name to the user account as the Service Principal Name (SPN). The SPN features in the process of mutual authentication between the client and the server hosting a particular service.
1. From the command prompt, type setspn –a {userlogonname} {serviceaccountname}
  Example 1. Map mailbox server name as servie Principal Names to user account
  setspn –a HTTP/mail1.example.com mail1
2. To verify that the SPN is registered, type C:\>setspn –l {accountname}
  A list of registered SPNs is displayed.

Create the keytab file used when signing into the Kerberos domain. Use the ktpass tool from the Windows Server toolkit to create the Kerberos keytab.

Note	A Kerberos keytab file contains a list of keys that are analogous to user passwords. Restrict and monitor permissions on any keytab files you create.

The command to type follows:

ktpass -out {keytab-file-to-produce} -princ {Service-Principal-Name}@\{the-kerberos-realm} -mapUser {AD-user} -mapOp set -pass {AD-user-password} -crypto RC4-HMAC-NT -pType KRB5_NT_PRINCIPAL

`ktpass -out`	The key is written to this output file. Enter the directory location and keytab file name. The keytab file name is `jetty.keytab`. For example, `C:\Temp\spengo\jetty.keytab`.
`-princ`	The principal name. Enter the service Principal Name as used in Step 2 of Create the Kerberos Keytab File. For example, `HTTP/mail1.example.com@MY_COMPANY.COM`.
`-mapUser`	Maps the principal name from the `-princ` parameter to this user account. Enter the name of the AD service account previously set as the User Logon Name (pre-Windows2000) in Step 1.b of Create the Kerberos Keytab File.
`-mapOp`	This option sets the mapping. The value for this parameter is set.
`-pass`	Specifies the password to use with the `-princ` account. Enter the password entered in the User Logon Name (pre-Windows2000) set in Step 1.c of Create the Kerberos Keytab File.
`-crypto`	The cryptosystem to use. Enter RC4-HMAC-NT.
`-pType`	Enter KRB5_NT_PRINCIPAL. To avoid warning messages from the toolkit, enter this value.

Example 2. Using ktpass to create a jetty.keytab file

ktpass -out C: \Temp\spengo\jetty.keytab -princ HTTP/mail1.example.com@MY_COMPANY.COM -mapUser mail1 -mapOp set - pass password123 -crypto RC4-HMAC-NT -pType KRB5_NT_PRINCIPAL

The command confirmation comes with something similar to the example below.

Targeting domain controller:
   ...

    Using legacy password setting method
    Successfully mapped HTTP/mail1.example.com to mail1.
    Key created.
    Output keytab to c:\Temp\spengo\jetty.keytab:
    Keytab version: 0x502

    keysize 71 HTTP HTTP/mail1.example.com@MY_COMPANY.COM ptype 1 (KRB5_NT_PRINCIPAL) vno3 etype 0x17 (RC4-HMAC) keylength 16 (0xc383f6a25f1e195d5aef495c980c2bfe)

Transfer the keytab file (jetty.keytab) to the Zimbra server. Copy the file created in step 3 to the following Zimbra server location: /opt/zimbra/data/mailboxd/spnego/jetty.keytab.

Important

Do not rename the jetty.keytab file. Many configuration files reference this filename.

Repeat steps 1 to 4 to create an create the keytab file (jetty.keytab) for each Zimbra mailstore server.

Configure {product-abbrev}

SPNEGO attributes get configured in Global Config and on each Zimbra server, and domain pre-authentication gets configured for the domain. Use the zmprov command to modify the Zimbra server.

Note	A {product-abbrev} installation may support only one Kerberos REALM.

Modify the following global config attributes, with the zmprov mcf command.

`zimbraSpnegoAuthEnabled`	Set to TRUE.
`zimbraSpnegoAuthErrorURL`	This value is the URL that users get redirected to when SPNEGO auth fails. Setting it to `/zimbra/?ignoreLoginURL=1` redirects the user to the regular Zimbra login page, where the user enters their {product-short} user name and password.
`zimbraSpnegoAuthRealm`	The Kerberos realm in the domain controller; the domain name in the Active Directory. (`MY_COMPANY.COM`)

To modify the global config attributes, type:

zmprov mcf zimbraSpnegoAuthEnabled TRUE
zmprov mcf zimbraSpnegoAuthErrorURL '/zimbra/?ignoreLoginURL=1'
zmprov mcf zimbraSpnegoAuthRealm <MY_COMPANY.COM>

On each Zimbra server, modify the following global config attributes with the zmprov ms command.

zimbraSpnegoAuthTargetName

This is the user logon name from Step 1 B, User Logon Name.

zimbraSpnegoAuthPrincipal

Enter the user logon name set in zimbraSpnegoAuthTargetName and the address set in global config zimbraSpnegoAuthRealm.

Type as zimbraSpnegoAuthTargetName@zimbraSpnegoAuthRealm.

For example, HTTP/mail1.example.com@MY_COMPANY.COM.

To modify the server global config attributes, type:

zmprov ms mail1.example.com zimbraSpnegoAuthTargetName HTTP/mail1.example.com
zmprov ms mail1.example.com zimbraSpnegoAuthPrincipal HTTP/mail1.example.com@MY_COMPANY.COM

Set up the following for the domain.
- Kerberos Realm
- Virtual host
- Web client login URL and UAs
- Web client logout URL and UAs
  1. Set up the Kerberos Realm for the domain as the same realm set in the global config attribute zimbraSpnegoAuthRealm. Type zmprov md {domain} zimbraAuthKerberos5Realm {kerberosrealm}.
  2. Set up the virtual hosts for the domain. Virtual-hostname-* are the hostnames you can browse to for the {product-short} {web-client} UI. Type:
    
    zmprov md {domain} +zimbraVirtualHostname {virtual-hostname-1} +zimbraVirtualHostname {virtual-hostname-2} ...
  3. Setup the web client login URL, and UAs allowed for the login URL on the domain.
    
    Set the login URL. The login URL is the URL to redirect users to when the Zimbra auth token is expired. zmprov md {domain} zimbraWebClientLoginURL '../service/spnego'.
    
    Honor only supported platforms and browsers.
    
    zimbraWebClientLoginURLAllowedUA is a multi-valued attribute,values are regex. If this is not set, all UAs are allowed. If multiple values are set, an UA is allowed as long as it matches any one of the values.
    
    zmprov md {domain} +zimbraWebClientLoginURLAllowedUA {UA-regex-1} +zimbraWebClientLoginURLAllowedUA {UA-regex-2} ...
    
    For example, to honor zimbraWebClientLoginURL only for Firefox, Internet Explorer, Chrome, and Safari on computers running Windows, and Safari on Apple Mac computers, type the following commands.
    
    zmprov md {domain} +zimbraWebClientLoginURLAllowedUA '._Windows._Firefox/3.*' zmprov md {domain} +zimbraWebClientLoginURLAllowedUA '._MSIE._Windows.*' zmprov md {domain} +zimbraWebClientLoginURLAllowedUA '._Windows._Chrome.*' zmprov md {domain} +zimbraWebClientLoginURLAllowedUA '._Windows._Safari.*' zmprov md {domain} +zimbraWebClientLoginURLAllowedUA '._Macintosh._Safari.*'
  4. Setup the web client logout URL and UAs allowed for the logout URL on the domain.
    
    Set the logout URL. The logout URL is the URL to redirect users to when users click btn:[Logout].
    
    zmprov md {domain} zimbraWebClientLogoutURL '../?sso=1'
    
    Honor only supported platforms and browsers. zimbraWebClientLogoutURLAllowedUA is a multi-valued attribute, where the accepted values are regex. If this attribute has no set value, all UAs are allowed. When it has multiple values, a UA is allowed as long as it matches any one of the values.
    
    zmprov md {domain} +zimbraWebClientLogoutURLAllowedUA {UA-regex-1} +zimbraWebClientLogoutURLAllowedUA {UA-regex-2} ...
    
    For example, to honor zimbraWebClientLogoutURL only for Firefox, Internet Explorer, Chrome, and Safari on computers running Windows, and Safari on Apple Mac computers, type the following commands.
    
    zmprov md {domain} +zimbraWebClientLogoutURLAllowedUA '._Windows._Firefox/3.*' zmprov md {domain} +zimbraWebClientLogoutURLAllowedUA '._MSIE._Windows.*' zmprov md {domain} +zimbraWebClientLogoutURLAllowedUA '._Windows._Chrome.*' zmprov md {domain} +zimbraWebClientLogoutURLAllowedUA '._Windows._Safari.*'

Configure Your Browser

With the SPNEGO SSO feature enabled on your domain, you must configure users' browsers to use its Authentication mechanism. Improperly configured browsers exhibit different behaviors depending on the browser.

The following browsers are supported:

For computers running Windows: Internet Explorer 10.0 or later, Edge, Firefox 52 or later, Chrome, Safari
Apple Mac computer: Safari

Configuration steps:

Firefox browser for computers running Windows
1. In the Firefox browser address field, type about:config. The warning — This might void your warranty, is now displayed.
2. Click btn:[I’ll be careful, I promise!]
3. Search in Filters, type network.n. Enter a comma-delimited list of trusted domains or URLs.
  
  Double-click network.negotiate-auth.delegation-uris. Enter http://,https://.
  
  Double-click network.negotiate-auth.trusted-uris. Enter http://,https://.
  
  Or, to set specific URLs,
  
  Double-click network.negotiate-auth.delegation-uris. Enter the domain addresses. For example, http://mail1.example.com,https://mail2.example.com.
  
  Double-click network.negotiate-auth.trusted-uris. Enter the domain addresses. For example, http://mail1.example.com,https://mail2.example.com.
Internet Explorer, Chrome, and Safari for computers running Windows
1. In these browsers, go to Tools → Internet Options → Security → Local Intranet >Sites. In the "Sites" dialog, check all items.
2. Select Advanced. Add the domain server (hostname) URL, both http:// and https://.
3. Click btn:[OK] to close the file.
4. Go to Tools → Options → Advanced → Security. Locate and check Enable Integrated Windows Authentication.
5. Click btn:[OK] and close the browser.
Safari for Apple Mac computers. No configuration is necessary.

Test your setup

On a Windows computer or an Apple Mac computer, log in to the computer as a domain user.

Your domain user token gets saved on the computer. The token gets picked up by the SPNEGO-aware browser and sent to the Zimbra server in the Authorization header.
Browse to the {product-short} {web-client} login page. You should get redirected to your inbox without being prompted for your user name and password.

If SPNEGO auth fails, the user gets redirected to an error URL.

Troubleshooting setup

Make sure the following are true.

The browser is in the Intranet zone.
The user is accessing the server using a Hostname rather than an IP address.
Integrated Windows Authentication has been enabled in Internet Explorer, and the host has been "trusted" in Firefox.
The server is not local to the browser.
The client’s Kerberos system is authenticated to a domain controller.
If the browser displays "401 Unauthorized", it’s most likely that the browser either did not send another request with Authorization in response to the 401 or had sent an Authorization without using the GSS-API/SPNEGO scheme.

Check your browser settings and make sure it is one of the supported browsers/platforms.
If you get redirected to the error URL specified in zimbraSpnegoAuthErrorURL, it means that the SPNEGO authentication sequence does not work.

Take a network trace, make sure the browser sends Authorization header in response to the 401. Make sure the Negotiate is using GSS-API/ SPNEGO, not NTLM (use a network packet decoder like Wireshark).

After verifying that the browser is sending the correct Negotiate, if it still does not work, turn on the following debug and check Zimbra logs:
- Add (do not replace) -DDEBUG=true -Dsun.security.spnego.debug=all to local config key spnego_java_options.
- Add log4j.logger.org.mortbay.log=DEBUG in log4j.
Then restart the mailbox server.

Browse to the debug snoop page (http://{server}:{port}/spnego/snoop.jsp). See if you can access snoop.jsp.

Check zmmailboxd.out and mailox.log for debugging output.
- One of the errors at this stage could be because of clock skew on the jetty server. If this is the case, it should get shown in zmmailboxd.out. Fix the clock skew and try again.

Configure Kerberos Auth with SPNEGO Auth

Kerberos auth and SPNEGO can co-exist on a domain. In this use case, you are using Kerberos as the mechanism for verifying a user’s principal/password against a KDC, instead of the native Zimbra LDAP, when the user cannot get in by SPNEGO.

In a properly configured browser, users are redirected to the Zimbra sign-in page when SPNEGO auth fails. Users can enter their Zimbra username and password on the sign-in page to sign in manually. The Domain attribute zimbraAuthMech controls the mechanism for verifying passwords. If zimbraAuthMech is "kerberos5", the entered user name is used first to identify a valid Zimbra user (users must appear in the Zimbra LDAP). The Zimbra user gets mapped to a Kerberos principal, and then the Kerberos principal + password is validated against a KDC. This KDC could be different from, or the same as, the KDC used by the Active Directory domain controller (for SPNEGO auth).

Note	Every Microsoft Active Directory domain controller acts as Kerberos KDC. For SPNEGO auth, KDC does not get contacted by the mailbox server. The Kerberos token sent from the Authorization HTTP header along with jetty’s keytab file can identify/authenticate the user.

For Kerberos auth (zimbraAuthMech*="kerberos5"), the mailbox server needs to contact KDC to validate principal+password. For the java Kerberos client (i.e., Zimbra mailbox server), the default realm and KDC for the realm get specified in a Kerberos config file. Specify the location of this config file in the optional JVM argument as java.security.krb5.conf. If it is not specified, the default is /etc/krb5.conf. When SPNEGO gets enabled in Zimbra, java.security.krb5.conf for the mailbox server is set to /opt/zimbra/jetty/etc/krb5.ini. Therefore, that is the active file for configuring Kerberos auth.

Note that /opt/zimbra/jetty/etc/krb5.ini gets rewritten from /opt/zimbra/jetty/etc/krb5.ini.in each time the mailbox server restarts. For persistent configuration then, you need to modify the /opt/zimbra/jetty/etc/krb5.ini.in file, not /opt/zimbra/jetty/etc/krb5.ini.

Under the [realms] section, KDC and admin_server get left unset for SPNEGO auth, but Kerberos auth requires them.

To configure:

Edit /opt/zimbra/jetty/etc/krb5.ini.in.

Change:

[realms]
%%zimbraSpnegoAuthRealm%% = {
default_domain = %%zimbraSpnegoAuthRealm%%
}

to

%%zimbraSpnegoAuthRealm%% = {
             kdc = YOUR-KDC
             admin_server = YOUR-ADMIN-SERVER
             default_domain = %%zimbraSpnegoAuthRealm%%
}

Replace YOUR-KDC and YOUR-ADMIN-SERVER to the hostname on which the kdc/admin_server for Kerberos auth is running.
Save the file and restart the mailbox server.

An important restriction is that the realm for SPNEGO and Kerberos auth must be the same. For SPNEGO auth, the Kerberos principal in the Authorization header gets mapped to a unique Zimbra account. For Kerberos auth, the Zimbra account gets mapped to a unique Kerberos principal. The mapping (by domain attribute zimbraAuthKerberos5Realm) is the same for both.

Setting Up Single Sign-On Options for ZCO

Note	To use SSO, SPNEGO must be configured on the {product-abbrev} server to use this option.

The single sign-on option works with a specific server. The server name used in the ZCO profile must match that in the SPNEGO configuration. Make sure that the server name gets incorporated into the .msi file before installation.

To set up the single sign-on option in the .msi customization script:

Set the server name to be the server name configured for SPNEGO, enter -sn <spnegoserver.example.com>.
Set the password rule, enter -pw 0.

cscript ZmCustomizeMsi.js <path/msi-filename> -sn <spnegoserver.example.com> -pw 0

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

spnego.adoc

spnego.adoc

Configuring SPNEGO Single Sign-On

Configuration Process

Create the Kerberos Keytab File

Configure {product-abbrev}

Configure Your Browser

Test your setup

Troubleshooting setup

Configure Kerberos Auth with SPNEGO Auth

Setting Up Single Sign-On Options for ZCO

Files

spnego.adoc

Latest commit

History

spnego.adoc

File metadata and controls

Configuring SPNEGO Single Sign-On

Configuration Process

Create the Kerberos Keytab File

Configure {product-abbrev}

Configure Your Browser

Test your setup

Troubleshooting setup

Configure Kerberos Auth with SPNEGO Auth

Setting Up Single Sign-On Options for ZCO