Configuration Examples

In the examples we assume:

  • SpectX WUI is accessible by the URL The is internal network domain.
  • The AD domain name is
  • The AD domain controller hostname is It runs LDAPS service at port 636.

User authentication

Below are the steps to configure Integrated Windows Authentication with SpectX Server. These include:

  • Service account creation for SpectX in Active Directory
  • Kerberos principal registration for the account
  • Provisioning it’s credentials to SpectX machine

Creating a service account for SpectX

To create a service account for SpectX in Active Directory and obtain keytab for it, perform the following steps:

  • Use the Active Directory Management tool to create a new user-type service account for SpectX:

    Select the Users folder or any other container designated for service accounts, right-click and select New, then choose User. Complete the New Object – User dialog:

    • Fill in First, Last and Full names
    • User Logon Name: set it to the desired name, for instance spectx
    • User Logon Name (pre-Windows2000): normally it has the same value as above. This name is used for the –mapUser parameter for ktpass command configured below
    • Click Next.
    • Enter and confirm the password. This password is used for the –pass parameter in the ktpass command, configured below.
    • Uncheck User must change password at next logon, check Password never expires and User cannot change password. If you choose This account supports AES 256 bit encryption then depending on java version SpectX is using you might need to install Java Cryptography Extension Unlimited Strength Jurisdiction Policy Files as described in SSL/TLS/Kerberos connectivity problems .
    • Click Next, then click Finish to create the user.
  • Use the ktpass utility on Active Directory controller machine to set the SPN (Service Principal Name) for the service account and create the keytab file which will be used by SpectX when signing into the Active Directory domain. The syntax is:

    ktpass –princ HTTP/<spectx-server-hostname>@<REALM-NAME> -mapuser <spectx-service-account-name>
        -target <REALM-NAME> –pass * -crypto all -ptype KRB5_NT_PRINCIPAL –out <keytab-file-name>


    • spectx-server-hostname refers to the hostname of the SpectX instance (or its frontend) used by clients in URLs for accessing SpectX. The port number must not be included in the SPN.
    • REALM-NAME is the Kerberos realm in the domain controller (the domain name in the Active Directory). Note that this name in service principal name must be set in capital letters.
    • spectx-service-account-name is the SpectX account name, which was set in User Logon Name (pre-Windows2000) during account creation.
    • -pass * instructs the command to ask for the account’s password in Active Directory. Alternatively, the password may be supplied as an argument to the -pass option instead of asterisk.
    • keytab-file-name is the output keytab file to be created.

    Execute the command, and type the account password when prompted:

    ktpass –princ HTTP/ -mapuser spectx
        -target INT.COMPANY.COM –pass * -crypto all -ptype KRB5_NT_PRINCIPAL –out spectx.keytab

    Running the command will modify the account details, changing its user login name to match the service principal name. Note that this command does not check for duplicate SPNs when mapping these to accounts. The setspn utility can be used for ensuring no duplicates exist (e.g. setspn -S HTTP/ spectx) before ktpass execution. Running the command also increments KVNO parameter for issued keys, so should you repeat this operation in the future you have to immediately refresh corresponding keytab file on the SpectX machine.

    Transfer the generated keytab file (spectx.keytab) to SpectX machine and register path to it in configuration option wgui.spnegoAuth.keytab. Make sure it gets proper access permissions and is readable only by the SpectX instance.

Important Points to Consider

  • Make sure users access SpectX using its hostname (not an IP address!) in URLs.
  • Make sure users access SpectX from systems that they are correctly authenticated at to a Windows domain.
  • Make sure users’ browsers are configured to use Integrated Windows Authentication:
    • For Internet Explorer:
      • Configure Local Intranet Domains
        • Select Tools > Internet Options > Security tab > Local intranet and click Sites.
        • In the Local intranet popup, ensure that the Include all sites that bypass the proxy server and Include all local (intranet) sites not listed in other zones options are checked.
        • Click Advanced. In the Local intranet (Advanced) dialog box, add all relative domain names that will be used for SpectX instances.
      • Configure Intranet Authentication
        • Select Tools > Internet Options > Security tab > Local intranet and click Custom Level…*
        • In the Security Settings dialog box, scroll to the User Authentication section.
        • Select Automatic logon only in Intranet zone. This option prevents users from having to re-enter logon credentials
      • Enable Integrated Windows Authentication support
        • Select Tools > Internet Options > Advanced
        • Under Security (in the checkbox list), locate and check Enable Integrated Windows Authentication
    • For Mozilla Firefox:
      • Browse to about:config and agree to the warnings
      • Search through to find the network settings (enter “network.n” in the Filter)
      • Enter a comma-delimited list of SpectX instances URLs into network.negotiate-auth.delegation-uris and network.negotiate-auth.trusted-uris.

Failure to follow these instructions may result in browsers prompting for a password when users access SpectX.


Some users might get “Bad Message 431 reason: Request Header Fields Too Large” error page when logging to SpectX using Integrated Windows Authentication. The most probable reason for this error is the big size of Kerberos packet wrapped into SPNEGO message sent by the user’s browser in response to the SPNEGO authentication request. Kerberos in Windows uses the Privilege Attribute Certificate (PAC) field of the Kerberos packet to transport Active Directory Group membership info. If there are many group memberships for the user, this field can occupy lots of space in the packet, making its overall size big enough to meet default limits. If possible, reduce the number of Active Directory groups that the user is a member of. Alternatively, determine a plausible value for the max size of the initial SPNEGO packet in your environment, multiply it by 4/3 to account Base64 overhead, and get the number of bytes the current headers size limit (8192 bytes by default) must be increased by. Set the result as a value for wgui.maxReqHeaderSize configuration parameter.

If user authentication fails with “KrbApErrException: Ticket not yet valid (33)” or “KrbApErrException: Clock skew too great (37)” messages, Make sure that system clocks on SpectX host are synchronized to the KDC system’s clock.

If user authentication fails with “KrbException: Encryption type AES256 CTS mode with HMAC SHA1-96 is not supported/enabled” or similar messages, then depending on java version SpectX is using you might need to install Java Cryptography Extension Unlimited Strength Jurisdiction Policy Files as described in SSL/TLS/Kerberos connectivity problems .

If user authentication fails with “KrbException: AES256 CTS mode with HMAC SHA1-96 encryption type not in permitted_enctypes list” or similar messages, you should enable specified encryption type by adding it to permitted_enctypes in kerb5.conf.

If user authentication fails with “KrbException: Invalid argument (400) - Cannot find key of appropriate type to decrypt AP REP” message, you have to ask for a new keytab for SpectX from Windows administrators, as the current one does not contain the required key. It is a very bad sign, as it may be caused by the current keytab being altered or substituted. In this case, it is highly recommended to find out the root cause.

AD Group Membership Verification

Verifying Active Directory group SID’s from Kerberos ticket PAC field of a Kerberos packet does not require any additional configuration.

Membership verification using LDAP User Query however, requires configuration of LDAP service access and Kerberos for SpectX.

LDAP service access configuration

To verify AD user membership in an AD Group, SpectX authenticates itself against Active Directory LDAP service using GSS-API SASL mechanism with Kerberos credentials of the same service account as for user authentication. This account in Active Directory must be granted essential privileges to execute LDAP queries specified by filter configuration parameter, within the tree specified by base dn element of url configuration parameter. If automatic user account creation is configured, each query is expected to return an attribute “cn”; if it is present in the response, its value is used for a value of the full name property for a newly created user account in the SpectX database.

This also implies that: - TCP and UDP connectivity from the SpectX machine to KDC port (typically 88) at domain controller is enabled for Kerberos authentication - TCP connectivity from the SpectX machine to the specified LDAP service port (used in url) must be enabled. - LDAP service hostname must be DNS-resolvable to IP address at the SpectX machine. If it is not, it must be added to the local hosts file.

If SpectX is set up without wgui.spnegoAuth.kdc parameter, its Kerberos configuration relies fully on information in krb5.conf. In this case, you would need to fill in correctly the [domain_realm] section specifying the mapping of the hostname of LDAP server to Kerberos realm name. The minimal krb5.conf might look then as follows:

      kdc =
[domain_realm] = INT.COMPANY.COM

Otherwise, SpectX will experience authentication failures with KrbException: Fail to create credential. (63) - No service creds outcome.

Also, make sure the DNS hostname in url configuration parameter has corresponding LDAP SPN in Active directory. Failing to have it correct results SpectX authentication failures with KrbException: Server not found in Kerberos database (7) outcome. For instance, if LDAP URL is like ‘ldap://’ then corresponding SPN should look like ‘ldap/’; however, it might be missing but there is correct one ‘ldap/’ for accessing with URL ‘ldap://’.

Make sure the keytab is always up to date with the current state for the corresponding SpectX service account in Active Directory. Should the KVNO parameter for the account change in Active Directory (i.e. due to ktpass run for the account), SpectX will fail to authenticate with outdated keytab with error “ No key to store”. Invalid keys in the keytab can also cause “org.ietf.jgss.GSSException: Failure unspecified at GSS-API level (Mechanism level: Checksum failed)” error.

If principal for the SpectX account was created properly, you should be able to request a TGT (Ticket Granting Ticket) from Kerberos using that principal. You can test it by running kinit command on SpectX machine as follows:

$ kinit -V –kt spectx.keytab HTTP/

The command may be prepended with “env KRB5_CONFIG=/path/to/krb5.conf ” to specify a path to custom krb5.conf.

After it has run successfully, klist command will display the obtained TGT.

However if it fails with message kinit: KDC has no support for encryption type while getting initial credentials, change the default encryption types in krb5.conf file (default_tgs_enctypes and default_tkt_enctypes parameters in libdefaults section) to ones accepted by KDC. If it fails with message kinit: KDC reply did not match expectations while getting initial credentials then ensure that required realms are registered in krb5.conf with names in upper case letters.

Then, using the LDAP search tool, you can test if LDAP query can be successfully executed with obtained Kerberos credentials by running the command:

$ ldapsearch -H ldap:// -b <base-dn> <filter>

where -H specifies a protocol/host/port part of url configuration parameter and -b specifies its base-dn element, and <filter> is value of filter parameter with {0}/{1} substituted by a username/userPrincipalName of any user belonging to target Active Directory group.

Both kinit and ldapsearch commands might be prepended with “KRB5_TRACE=/dev/stderr ” to enable Kerberos-related diagnostic logging to be printed to stderr.

Finally, destroy your Kerberos ticket by calling kdestroy command:

$ kdestroy

Kerberos Configuration

The essential Kerberos configuration information is the default realm and the default KDC. These may be set either in the SpectX configuration or in the krb5.conf file.

When wgui.spnegoAuth.kdc is set to KDC location in the SpectX’s configuration file then it is not obtained from the krb5.conf configuration file.

Also in this case, value of wgui.spnegoAuth.realm becomes the default Kerberos realm.

However, if KDC location is not set in configuration, or if other Kerberos configuration information is needed, an attempt is made to find the required information in the krb5.conf file. The algorithm to locate the krb5.conf file is the following:

  • If the system property is set, its value is assumed to specify the path and file name.
  • If the configuration property wgui.spnegoAuth.krb5Conf is set, its value is assumed to specify the path and file name. System property is set to this value.
  • If neither that configuration property value nor system property values are set, then krb5.conf file is looked for in the directory <java-home>/lib/security
  • If the file is still not found, then an attempt is made to locate it as follows:
    • c:\\winnt\\krb5.ini (Windows)
    • /etc/krb5.conf (Linux/OSX)
  • If the file is still not found, then implementation-specific defaults are used.

In simple setups, specifying wgui.spnegoAuth.kdc should be enough to allow SpectX to authenticate in Windows domain. Should your environment require Kerberos configuration fine-tuning or customization (for instance when HDFS data sources are used), you have to either edit default krb5.conf on the machine or create your own and register its path in wgui.spnegoAuth.krb5Conf configuration parameter.

For the content of krb5.conf file, consult MIT documentation .

The minimal krb5.conf might look as follows:

      kdc =

Enabling Kerberos debug logging

With setting up Kerberos, many things can go wrong. You might have to enable additional debug logs to determine the root cause of the issue. To understand the problem during SPNEGO GSS context negotiation or look at the Kerberos message exchange, you can enable Kerberos/SPNEGO debug logging on JRE, by adding the following line to environment script


and restarting SpectX. The Kerberos and GSS-API debug log messages will be then printed to stdout.