Configuring SPNEGO Single Sign-On: Difference between revisions
No edit summary |
|||
(2 intermediate revisions by 2 users not shown) | |||
Line 5: | Line 5: | ||
{{KB|{{ZC}}|{{ZCS 8.6}}|{{ZCS 8.5}}|{{ZCS 8.0}}}} | {{KB|{{ZC}}|{{ZCS 8.6}}|{{ZCS 8.5}}|{{ZCS 8.0}}}} | ||
{{WIP}} | {{WIP}} | ||
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 [ | 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== | ==How it works== | ||
Line 23: | Line 23: | ||
====Create the Active Directory account==== | ====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. | 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'''. | |||
[[File:Zimbra-spnego-001.png|800px]] | [[File:Zimbra-spnego-001.png|800px]] | ||
::* '''Full name''': Enter the user display name for the AC service account. Recommend that the full name be the ZCS mailbox server name. Example: <pre>zimbraspnego</pre> | |||
Full name: Enter the user display name for the AC service account. Recommend that the full name be the ZCS mailbox server name. | ::* '''User Logon Name''': This name is the value that is set for the zimbraSpnegoAuthTargetName server attribute in LDAP. Write it down. Example: <pre>HTTP/mail1.example.com</pre> | ||
Example: zimbraspnego | ::* '''User Logon Name (pre-Windows2000)''': This name is used for the '''–mapUser''' parameter in the '''setspn''' and '''ktpass''' commands. Example: <pre>mail1.</pre> | ||
* | |||
* | |||
[[File:Zimbra-spnego-002.png]] | [[File: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)==== | ====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. | 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: | |||
Example: | |||
<pre>C:\Windows\System32> setspn -a HTTP/zimbraspnego zimbraspnego | <pre>C:\Windows\System32> setspn -a HTTP/zimbraspnego zimbraspnego | ||
Checking domain DC=zimbralab,DC=local | Checking domain DC=zimbralab,DC=local | ||
Line 51: | Line 45: | ||
Updated object | Updated object | ||
</pre> | </pre> | ||
:b. To verify that the SPN is registered, type | |||
<pre>C:\Windows\System32> setspn -L zimbraspnego | <pre>C:\Windows\System32> setspn -L zimbraspnego | ||
Registered ServicePrincipalNames for CN=Zimbra SPNEGO,CN=Users,DC=zimbralab,DC=local: | Registered ServicePrincipalNames for CN=Zimbra SPNEGO,CN=Users,DC=zimbralab,DC=local: | ||
HTTP/zimbraspnego</pre> | HTTP/zimbraspnego | ||
</pre> | |||
:c. Then we need to add our ZCS mail server to the user that we created before. | |||
<pre>C:\Windows\System32> setspn -A HTTP/zimbra-sn-u14-01.zimbralab.local zimbraspnego | <pre>C:\Windows\System32> setspn -A HTTP/zimbra-sn-u14-01.zimbralab.local zimbraspnego | ||
Checking domain DC=zimbralab,DC=local | Checking domain DC=zimbralab,DC=local | ||
Line 62: | Line 56: | ||
Registering ServicePrincipalNames for CN=Zimbra SPNEGO,CN=Users,DC=zimbralab,DC=local | Registering ServicePrincipalNames for CN=Zimbra SPNEGO,CN=Users,DC=zimbralab,DC=local | ||
HTTP/zimbra-sn-u14-01.zimbralab.local | HTTP/zimbra-sn-u14-01.zimbralab.local | ||
Updated object</pre> | Updated object | ||
</pre> | |||
:d. To verify that the SPN is registered, type | |||
<pre>C:\Windows\System32> setspn -L zimbraspnego | <pre>C:\Windows\System32> setspn -L zimbraspnego | ||
Registered ServicePrincipalNames for CN=Zimbra SPNEGO,CN=Users,DC=zimbralab,DC=local: | Registered ServicePrincipalNames for CN=Zimbra SPNEGO,CN=Users,DC=zimbralab,DC=local: | ||
Line 71: | Line 65: | ||
A list of registered SPNs is displayed. | A list of registered SPNs is displayed. | ||
</pre> | </pre> | ||
====Create the keytab file==== | ====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. | 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. | ||
Line 106: | Line 101: | ||
<pre>C:\zimbratemp> ktpass.exe -out jetty.keytab -princ HTTP/zimbra-sn-u14-01.zimbralab.local@zimbralab.local -mapUse | <pre>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 | r zimbralab\zimbraspnego -mapOp set -pass Zimbra123 -crypto RC4-HMAC-NT -pType KRB5_NT_PRINCIPAL | ||
</pre> | |||
The command is confirmed with something similar to the example below. | The command is confirmed with something similar to the example below. | ||
<pre>Targeting domain controller: dc.zimbralab.local | <pre>Targeting domain controller: dc.zimbralab.local | ||
Line 115: | Line 110: | ||
Keytab version: 0x502 | 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) | 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)</pre> | keylength 16 (0xe9b0fd3c656534343dfdfd342fgds0536da0) | ||
</pre> | |||
[[File:Zimbra-spnego-003.png]] | [[File:Zimbra-spnego-003.png]] | ||
Line 130: | Line 126: | ||
====Modify the Global Config attributes==== | ====Modify the Global Config attributes==== | ||
1. Modify the following global config attributes, with the zmprov mcf command. | |||
{| class="wikitable" width=100% border=1 | {| class="wikitable" width=100% border=1 | ||
! align="left" style="color:white;" bgcolor="#0087c3" |Attribute | ! align="left" style="color:white;" bgcolor="#0087c3" |Attribute | ||
Line 139: | Line 135: | ||
|- | |- | ||
| zimbraSpnegoAuthErrorURL | | zimbraSpnegoAuthErrorURL | ||
| This is the URL users are redirected to when | | 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 | | zimbraSpnegoAuthRealm | ||
| The | | 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: | To modify the global config attributes, type: | ||
zmprov mcf zimbraSpnegoAuthEnabled TRUE | zmprov mcf zimbraSpnegoAuthEnabled TRUE | ||
zmprov mcf zimbraSpnegoAuthErrorURL '/zimbra/?ignoreLoginURL= | zmprov mcf zimbraSpnegoAuthErrorURL '/zimbra/?ignoreLoginURL=1' | ||
zmprov mcf zimbraSpnegoAuthRealm <COMPANY.COM> | zmprov mcf zimbraSpnegoAuthRealm <COMPANY.COM> | ||
2. On each Zimbra server, modify the following global config attributes with the zmprov ms command. | |||
{| class="wikitable" width=100% border=1 | {| class="wikitable" width=100% border=1 | ||
Line 168: | Line 164: | ||
=====Detailed configuration for zimbraSpnegoAuthErrorURL===== | =====Detailed configuration for zimbraSpnegoAuthErrorURL===== | ||
You can modify this setting to add your Custom White Label URL, etc | 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. | |||
This will not show any error page | 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: | ||
:<pre>zmprov mcf zimbraSpnegoAuthErrorURL '/?ignoreLoginURL=1'</pre> | |||
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. | |||
:<pre>zmprov mcf zimbraSpnegoAuthErrorURL '../../zimbra/public/login.jsp?ignoreLoginURL=1'</pre> | |||
If browser not configured i.e. after http 401 error page will automatically redirect to | 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. | ||
:<pre>zmprov mcf zimbraSpnegoAuthErrorURL 'http://example.com'</pre> | |||
This will not show any error page. | |||
====Modify the domain==== | ====Modify the domain==== | ||
Line 203: | Line 190: | ||
Set up the virtual hosts for the domain. Virtual-hostname-* are the hostnames you can browse to for the Zimbra Web Client UI. Type | 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} ... | zmprov md example.com +zimbraVirtualHostname {virtual-hostname-1} +zimbraVirtualHostname {virtual-hostname-2} ... | ||
=====Web client login URL and UAs===== | =====Web client login URL and UAs===== | ||
Setup the web client log in URL and UAs allowed for the login URL on the domain. | Setup the web client log in URL and UAs allowed for the login URL on the domain. | ||
Line 238: | Line 226: | ||
===Test your setup=== | ===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. | : 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. | |||
If spnego auth fails, the user is redirected to an error URL. | |||
===Troubleshooting setup=== | ===Troubleshooting setup=== | ||
Make sure the following are true. | 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. | 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. | ||
Line 259: | Line 246: | ||
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) . | 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: | 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. | Then restart the mailbox server. | ||
Line 276: | Line 263: | ||
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. | 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: | |||
# Set the server name to be the server name configured for SPNEGO, enter <code>-sn</code> | |||
# Set the password rule, enter <code>-pw 0</code>. | |||
Example: | |||
cscript ZmCustomizeMsi.js <path/msi-filename> -sn <spnegoserver.example.com> -pw 0 | |||
ref: [https://www.zimbra.com/docs/ne/8.6.0/zcs_connector_for_outlook_guide/wwhelp/wwhimpl/js/html/wwhelp.htm#href=860_ZCO_AdminGuide.Setting_Up_the_Single_Sign-On_Option_%28SSO%29.html 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: | |||
# Set the server name to be the server name configured for SPNEGO, enter <code>-sn</code> | |||
# Set the visibility and default tick state of the "Connect using my Windows Logon credentials" checkbox, enter <code>-sso <n></code><!-- | |||
--><p></p><!-- | |||
--><p><n></p><!-- | |||
--><p></p><!-- | |||
--><p>0: Checkbox is invisible (and unticked)</p><!-- | |||
--><p>1: Checkbox is visible, but unticked by default when a new profile is created</p><!-- | |||
--><p>2: Checkbox is visible, and ticked by default when a new profile is created</p><!-- | |||
--><p></p><!-- | |||
--><p>The default for the sso settting is 1.</p> | |||
Example: | |||
cscript ZmCustomizeMsi.js <path/msi-filename> -sn <spnegoserver.example.com> -sso 2 | |||
ref: [https://www.zimbra.com/docs/ne/8.6.0/zcs_connector_for_outlook_guide/wwhelp/wwhimpl/js/html/wwhelp.htm#href=860_ZCO_AdminGuide.Setting_Up_the_Single_Sign-On_Option_%28SSO%29.html Setting Up Single Sign-On Options for ZCO (8.8.8)] | |||
==Identified Support Issues== | ==Identified Support Issues== | ||
* [https://bugzilla.zimbra.com/show_bug.cgi?id=82243 '''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 | * [https://bugzilla.zimbra.com/show_bug.cgi?id=82243 '''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 | ||
---- | ---- |
Latest revision as of 18:48, 16 March 2018
Configuring SPNEGO Single Sign On
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.
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.
- 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.
- Full name: Enter the user display name for the AC service account. Recommend that the full name be the ZCS mailbox server name. Example:
- 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)
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:
- Set the server name to be the server name configured for SPNEGO, enter
-sn
- 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:
- Set the server name to be the server name configured for SPNEGO, enter
-sn
- 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