Configuring SPNEGO Single Sign-On

Configuring SPNEGO Single Sign On

   KB 21712        Last updated on 2018-03-16  




4.00
(one vote)


The SPNEGO protocol mechanism can be configured on ZCS for single sign-on authentication to the Zimbra Web Client and to the Zimbra Connector for Outlook (ZCO). For ZCO configuration see #Setting Up Single Sign-On Options for ZCO.

How it works

From ZWC, when users log on to their Intranet through Active Directory, they can enter their ZWC mailbox without having to re-authenticate to Zimbra. The ZCS server is configured to redirect users attempting to log on to ZWC to a URL under SPNEGO protection. The server asks for authentication with Kerberos through SPNEGO and users are redirected to their ZWC mailbox. When users log out, they are redirected to a logout URL that displays a Launch button. When users click Launch, they are directed to the ZWC entry page.

Zimbra-SPNEGO-Architecture.png

Note: When users log on to their ZWC accounts from the Internet, the ZWC log in page displays and they must enter their ZWC password to log on. Important: If SPNEGO SSO is enabled on a domain, the browsers must be configured correctly. See Configure Your Browser. Improperly configured browsers may pop up a user/pass dialog and if a user enters his correct AD domain username/password, he can still log into the Zimbra mailbox, and some browsers may display a “401 Unauthorized” error.

How to enable it

Create the Kerberos Keytab File

An Active Directory service account is created in Domain for each mailstore server.

Create the Active Directory account

Create an Active Directory service account. This is the account used to generate the Kerberos keytab file that is added to the Zimbra server.

a. Go to the Active Directory Start > Programs > Administrative Tools > Active Directory Users and Computers console.
b. 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.

Zimbra-spnego-001.png

  • Full name: Enter the user display name for the AC service account. Recommend that the full name be the ZCS mailbox server name. Example:
    zimbraspnego
  • User Logon Name: This name is the value that is set for the zimbraSpnegoAuthTargetName server attribute in LDAP. Write it down. Example:
    HTTP/mail1.example.com
  • User Logon Name (pre-Windows2000): This name is used for the –mapUser parameter in the setspn and ktpass commands. Example:
    mail1.

Zimbra-spnego-002.png

  • Click Next.
c. Enter and confirm the password. This password is used for the –pass {AD-user-password} parameter in the ktpass command, configured below.
d. Check Password never expires and User cannot change password, and click Next.
e. Click Finish to create the user. The service account name displays in the Users directory.

Set the SPN (Service Principal Names)

Use the setspn command to map the mailbox server name as the service Principal Names (SPN) to the user account. The SPN is used in the process of mutual authentication between the client and the server hosting a particular service.

a. From the Windows command prompt, type setspn –a {userlogonname} {serviceaccountname}. Example:
C:\Windows\System32> setspn -a HTTP/zimbraspnego zimbraspnego
Checking domain DC=zimbralab,DC=local

Registering ServicePrincipalNames for CN=Zimbra SPNEGO,CN=Users,DC=zimbralab,DC=local
        HTTP/zimbraspnego
Updated object
b. To verify that the SPN is registered, type
C:\Windows\System32> setspn -L zimbraspnego
Registered ServicePrincipalNames for CN=Zimbra SPNEGO,CN=Users,DC=zimbralab,DC=local:
        HTTP/zimbraspnego
c. Then we need to add our ZCS mail server to the user that we created before.
C:\Windows\System32> setspn -A HTTP/zimbra-sn-u14-01.zimbralab.local zimbraspnego
Checking domain DC=zimbralab,DC=local

Registering ServicePrincipalNames for CN=Zimbra SPNEGO,CN=Users,DC=zimbralab,DC=local
        HTTP/zimbra-sn-u14-01.zimbralab.local
Updated object
d. To verify that the SPN is registered, type
C:\Windows\System32> setspn -L zimbraspnego
Registered ServicePrincipalNames for CN=Zimbra SPNEGO,CN=Users,DC=zimbralab,DC=local:
        HTTP/zimbra-sn-u14-01.zimbralab.local
        HTTP/zimbraspnego
A list of registered SPNs is displayed.

Create the keytab file

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

Attribute Description
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\spnego\jetty.keytab"
-princ "This is the principal name.Enter the service Principal Name as used in Step 2 in Setting up the Microsoft Windows Active Directory Domain Controller section. For example, HTTP/mail1.example.com@COMPANY.COM"
-mapUser "This maps –princ value to this user account.Enter the AD service account user name entered in the User Logon Name (pre-Windows2000) set in Step 1.b in Setting up the Microsoft Windows Active Directory Domain Controller section."
-mapOp "This sets the mapping. The value for this parameter isset"
-pass "This is the password to use.Enter the password entered in the User Logon Name (pre-Windows2000) set in Step 1.c in Setting up the Microsoft Windows Active Directory Domain Controller section."
-crypto "This is the cryptosystem to use.Enter RC4-HMAC-NT"
-pType "EnterKRB5_NT_PRINCIPALTo avoid warning messages from the toolkit enter this value. "

In a temp folder launch the next, this an example:

C:\zimbratemp> ktpass.exe -out jetty.keytab -princ HTTP/zimbra-sn-u14-01.zimbralab.local@zimbralab.local -mapUse
r zimbralab\zimbraspnego -mapOp set -pass Zimbra123 -crypto RC4-HMAC-NT -pType KRB5_NT_PRINCIPAL

The command is confirmed with something similar to the example below.

Targeting domain controller: dc.zimbralab.local
Using legacy password setting method
Successfully mapped HTTP/zimbra-sn-u14-01.zimbralab.local to zimbraspnego.
Key created.
Output keytab to spnegofile.keytab:
Keytab version: 0x502
keysize 88 HTTP/zimbra-sn-u14-01.zimbralab.local@zimbralab.local ptype 1 (KRB5_NT_PRINCIPAL) vno 3 etype 0x17 (RC4-HMAC) 
keylength 16 (0xe9b0fd3c656534343dfdfd342fgds0536da0)

Zimbra-spnego-003.png

Transfer the keytab to the Zimbra Collaboration Server

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. This file name is referenced from various configuration files. Repeat steps 1 to 4 to create an create the keytab file (jetty.keytab) for each Zimbra mailstore server.

Configure ZCS

SPNEGO attributes in Global Config and on each Zimbra server are configured and pre-authentication is set up for the domain. Use the zmprov CLI to modify the Zimbra server. Note: Only one Kerberos REALM is supported per ZCS installation

Modify the Global Config attributes

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

Attribute Description
zimbraSpnegoAuthEnabled Set to TRUE.
zimbraSpnegoAuthErrorURL This is the URL users are redirected to when spnego auth fails. Setting it to /zimbra/?ignoreLoginURL=1 will redirect user to the regular Zimbra login page, where user will be prompted for their zimbra user name and password.
zimbraSpnegoAuthRealm The Kerberos realm in the domain controller. This is the domain name in the Active Directory. (COMPANY.COM)

To modify the global config attributes, type:

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

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

Attribute Description
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@COMPANY.COM

To modify the server global config attributes, type:

zmprov ms zimbra-sn-u14-01.zimbralab.local zimbraSpnegoAuthTargetName HTTP/zimbra-sn-u14-01.zimbralab.local
zmprov ms zimbra-sn-u14-01.zimbralab.local zimbraSpnegoAuthPrincipal HTTP/zimbra-sn-u14-01.zimbralab.local@zimbralab.local
Detailed configuration for zimbraSpnegoAuthErrorURL

You can modify this setting to add your Custom White Label URL, etc.

1. zimbraSpnegoAuthErrorURL is Unset and browser not configured.

It will show customise http 401 error jsp page with link to wiki page for browser configuration.

2. If browser not configured, i.e. after http 401 error, page will automatically redirect to default login page. This will not show any error page:

zmprov mcf zimbraSpnegoAuthErrorURL '/?ignoreLoginURL=1'

3. If browser not configured, i.e. after http 401 error, page will automatically redirect to default login.jsp Make sure to append ?ignoreLoginURL=1 when you add redirect with in application context. This will not show any error page.

zmprov mcf zimbraSpnegoAuthErrorURL '../../zimbra/public/login.jsp?ignoreLoginURL=1'

4. If browser not configured i.e. after http 401 error page will automatically redirect to http://example.com. This will not show any error page.

zmprov mcf zimbraSpnegoAuthErrorURL 'http://example.com'

Modify the domain

This steps needs to be executed per domain.

Kerberos Realm

Set up Kerberos Realm for the domain. This is the same realm set in the global config attribute zimbraSpnegoAuthRealm . Type zmprov md {domain} zimbraAuthKerberos5Realm {kerberosrealm}

For example:

zmprov md zimbralab.local zimbraAuthKerberos5Realm zimbralab.local
Virtual host

Set up the virtual hosts for the domain. Virtual-hostname-* are the hostnames you can browse to for the Zimbra Web Client UI. Type zmprov md example.com +zimbraVirtualHostname {virtual-hostname-1} +zimbraVirtualHostname {virtual-hostname-2} ...

Web client login URL and UAs

Setup the web client log in 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’

For example:

zmprov md zimbralab.local 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 example.com +zimbraWebClientLoginURLAllowedUA '.*Windows.*Firefox/3.*'
zmprov md example.com +zimbraWebClientLoginURLAllowedUA '.*MSIE.*Windows.*'
zmprov md example.com +zimbraWebClientLoginURLAllowedUA '.*Windows.*Chrome.*'
zmprov md example.com +zimbraWebClientLoginURLAllowedUA '.*Windows.*Safari.*'
zmprov md example.com +zimbraWebClientLoginURLAllowedUA '.*Macintosh.*Safari.*'
Web client logout URL and UAs

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 Logout. Zmprov md {domain} zimbraWebClientLogoutURL '../?sso=1’

For example:

zmprov md zimbralab.local zimbraWebClientLogoutURL '../?sso=1'

Honor only supported platforms and browsers. zimbraWebClientLogoutURLAllowedUA 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} +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 example.com +zimbraWebClientLogoutURLAllowedUA '.*Windows.*Firefox/3.*'
zmprov md example.com +zimbraWebClientLogoutURLAllowedUA '.*MSIE.*Windows.*'
zmprov md example.com +zimbraWebClientLogoutURLAllowedUA '.*Windows.*Chrome.*'
zmprov md example.com +zimbraWebClientLogoutURLAllowedUA '.*Windows.*Safari.*'

Configure Your Browser

See the Article Configure_Browser_for_SPNEGO

Test your setup

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

Your ticket as a domain user will be saved on the computer. The token will be picked up by the spnego-aware browser and sent in the Authorization header to the Zimbra server.

2. Browse to the Zimbra Web Client log on page. You should be redirected to your ZWC inbox without being prompted for user name and password.

If spnego auth fails, the user is 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 IP address.
  • Integrated Windows authentication in Internet Explorer is enabled, and the host is 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 display the "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 which is not using the GSS-API/SPNEGO scheme. Check your browser settings, and make sure it is one of the supported browsers/platforms

If you are redirected to the error URL specified in zimbraSpnegoAuthErrorURL, that means 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 "-DDEBUG=true -Dsun.security.spnego.debug=all" (note, not replace) to localconfig 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 the snoop.jsp

Check zmmailboxd.out and mailox.log for debug 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 be shown in zmmailboxd.out. Fix the clock skew and try again.

Quick troubleshooting

First, make sure your SSO configuration is correct by pointing your browser to http://server:port//service/spnego/snoop.jsp. If successful, this will give you all the information about the authentication.

Then, try the follolwing URL: http://server:port//service/spnego/ This should let you enter your Zimbra account.

Finally, the right URL for the zimbraWebClientLoginURL is '../service/spnego' (not '../../service/spnego') you can see this wrong path around Internet, in other not supported documents.

Configure Kerberos Auth with SPNEGO Auth

Kerberos auth and SPNEGO can co-exists on a domain. Use case is using Kerberos as the mechanism for verifying user principal/password against a KDC, instead of the native Zimbra LDAP, when user cannot get in by SPNEGO.

When SPNEGO auth fails, users are redirected to the Zimbra sign in page if the browser is configured properly. 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 set to "kerberos5", The user name the user enters is used to first identify a valid Zimbra user (users must be provisioned in the Zimbra LDAP), then from Zimbra user is mapped to a Kerberos principal, the Kerberos principal + password is then validated against a KDC. This KDC could be different from, or the same as, the KDC that the Active Directory domain controller (for SPNEGO auth) is running as.


Note: Every Microsoft Active Directory domain controller acts as Kerberos KDC. For SPNEGO auth, KDC is not contacted from 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 is specify in a Kerberos config file. The location of this config file can be specified in JVM argument java.security.krb5.conf. If it is not specified, the default is /etc/krb5.conf. When SPNEGO is enabled in Zimbra, java.security.krb5.conf for the mailbox server is set to /opt/zimbra/jetty/etc/krb5.ini. Therefore, that is the effective file for configuring kerberos auth.

/opt/zimbra/jetty/etc/krb5.ini is rewritten from /opt/zimbra/jetty/etc/krb5.ini.in each time when the mailbox server restarts. To configure, you need to modify the /opt/zimbra/jetty/etc/krb5.ini.in file, not /opt/zimbra/jetty/etc/krb5.ini.

Under [realms] section, kdc and admin_server are not set for SPNEGO auth, but they are required for kerberos auth.

To configure: 1. Edit /opt/zimbra/jetty/etc/krb5.ini.in 2. Change:

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

to:

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

3. Replace YOUR-KDC and YOUR-ADMIN-SERVER to the hostname on which the kdc/admin_server for kerberos auth is running. 4. Save the file and restart mailbox server. The restriction is the realm for SPNEGO and Kerberos auth must be the same. For SPNEGO auth, the Kerberos principal in the Authorization header is mapped to a unique Zimbra account. For Kerberos auth, the Zimbra account is 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 ZCS server to use this option.


Up to release 8.8.7

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 is incorporated into the .msi file prior to installation.

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

  1. Set the server name to be the server name configured for SPNEGO, enter -sn
  2. Set the password rule, enter -pw 0.

Example:

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

ref: Setting Up Single Sign-On Options for ZCO (8.6.0)

Beginning with release 8.8.8

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

  1. Set the server name to be the server name configured for SPNEGO, enter -sn
  2. Set the visibility and default tick state of the "Connect using my Windows Logon credentials" checkbox, enter -sso <n>

    <n>

    0: Checkbox is invisible (and unticked)

    1: Checkbox is visible, but unticked by default when a new profile is created

    2: Checkbox is visible, and ticked by default when a new profile is created

    The default for the sso settting is 1.

Example:

cscript ZmCustomizeMsi.js <path/msi-filename> -sn <spnegoserver.example.com> -sso 2

ref: Setting Up Single Sign-On Options for ZCO (8.8.8)

Identified Support Issues

  • Bug 82243 - SPNEGO Authentication not working due Zimbra Ews jetty configuration. Only in Zimbra Collaboration 8.5, fixed in 8.5 Patch 2 and above

Verified Against: Zimbra Collaboration Suite 8.6, 8.5 Date Created: 04/15/2015
Article ID: https://wiki.zimbra.com/index.php?title=Configuring_SPNEGO_Single_Sign-On Date Modified: 2018-03-16



Try Zimbra

Try Zimbra Collaboration with a 60-day free trial.
Get it now »

Want to get involved?

You can contribute in the Community, Wiki, Code, or development of Zimlets.
Find out more. »

Looking for a Video?

Visit our YouTube channel to get the latest webinars, technology news, product overviews, and so much more.
Go to the YouTube channel »


Wiki/KB reviewed by SME1 SME2 Copywriter Last edit by David Bingham
Jump to: navigation, search