Skip to content

Latest commit

 

History

History
545 lines (444 loc) · 19.3 KB

spnego.adoc

File metadata and controls

545 lines (444 loc) · 19.3 KB

Configuring SPNEGO Single Sign-On

The SPNEGO protocol mechanism can be configured on {product-abbrev} 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.

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 {product-abbrev} 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.

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.

Configuration Process

  1. Create the Kerberos keytab file.

    • Create an Active Directory service account. This account is used to generate the Kerberos keytab file.

    • Add the service Principal Names (SPN) directory property for an Active Directory service account.

    • Create the keytab file.

  2. Enable and configure the SPNEGO protocol on the {product-abbrev} server.

  3. Configure browsers

Create the Kerberos Keytab File

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

  1. Create an Active Directory service account. This is the account used to generate the Kerberos keytab file that is added 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 AC service account. Recommend that the full name be the {product-abbrev} mailbox server name.
        Example: mail1

      • User Logon Name: This name is the value that is set for the zimbraSpnegoAuthTargetName server attribute in LDAP. Write itdown.
        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

      • Click Next.

    3. Enter and confirm the password. This password is used 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 Next.

    5. Click Finish to create the user. The service account name displays in the Users directory.

  2. 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 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.

  3. 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

    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/[email protected]

    -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 is set

    -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

    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/[email protected] -mapUser mail1 -mapOp set - pass password123 -crypto RC4-HMAC-NT -pType KRB5_NT_PRINCIPAL

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

    Targeting domain controller: …

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

    keysize 71 HTTP HTTP/[email protected] ptype 1 (KRB5_NT_PRINCIPAL) vno3 etype 0x17 (RC4-HMAC) keylength 16 (0xc383f6a25f1e195d5aef495c980c2bfe)

  4. 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 {product-abbrev}

SPNEGO attributes in Global Config and on each Zimbra server are configured and pre-authentication is set up for the domain. Use the zmprov commands to modify the Zimbra server.

Note
 Only one Kerberos REALM is supported per {product-abbrev} installation.

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

    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:

    1. zmprov mcf zimbraSpnegoAuthEnabled TRUE

    2. zmprov mcf zimbraSpnegoAuthErrorURL '/zimbra/?ignoreLoginURL=1'

    3. zmprov mcf zimbraSpnegoAuthRealm <COMPANY.COM>

  2. 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/[email protected]

    To modify the server global config attributes, type:

    1. zmprov ms mail1.example.com zimbraSpnegoAuthTargetName HTTP/mail1.example.com

    2. zmprov ms mail1.example.com zimbraSpnegoAuthPrincipal HTTP/[email protected]

  3. The following is set up on the domain.

    • Kerberos Realm

    • Virtual host

    • Web client login URL and UAs

    • Web client logout URL and UAs

      1. 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}

      2. 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 {domain} +zimbraVirtualHostname {virtual-hostname-1} +zimbraVirtualHostname {virtual-hostname-2}
...

      3. 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'

        • 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 Logout.

          zmprov md {domain} 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 {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

When the SPNEGO SSO feature is enabled on your domain, user’s browsers must be configured properly. Improperly configured browsers will behave differently depending on the browser.

The following browsers are supported:

  • For computers running Windows: Internet Explorer 6.0 or later, Firefox 3.0 or later, Chrome, Safari

  • Apple Mac computer: Safari

    1. Firefox browser for computers running Windows

      1. In Firefox browse to about:config. In the Firefox browser address field, type about:config. The warning — This might void your warranty, is now displayed.

      2. Click 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

    2. Internet Explorer, Chrome, and Safari for computers running Windows

      1. In these browsers, go to Tools > Internet Options > Security > Local Intranet >Sites. On the Sites dialog make sure all items are checked.

      2. Select Advanced. Add the domain server (hostname) URL, both http:// and https://

      3. Click OK to close the file.

      4. Go to Tools > Options > Advanced > Security. Locate and check Enable Integrated Windows Authentication.

      5. Click OK and close the browser.

    3. Safari for Apple Mac computers. No configuration is necessary.

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 thejetty server. If this is the case, it should be shown in zmmailboxd.out. Fix the clock skew and try again.

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 usedto 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

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

  1. Replace YOUR-KDC and YOUR-ADMIN-SERVER to the hostname on which the kdc/admin_server for kerberos auth is running.

  2. 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 {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 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 <spnegoserver.example.com>.

  2. Set the password rule, enter -pw 0

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