Integrated Windows Authentication configuration

In the examples further we use the following assumptions:

  • SpectX WGUI is accessible by the url http://spectx.int.company.net:8388/. The int.company.net is internal network domain.
  • Active directory domain name is int.company.com
  • Active directory domain controller hostname is dc.int.company.net. It runs LDAPS service at port 689.

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 service account for SpectX

In order to create 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 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>
    

    where

    • spectx-server-hostname refers to 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 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/spectx.int.company.net@INT.COMPANY.COM -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. A setspn utility can be used for ensuring no duplicates exist (e.g. setspn -S HTTP/spectx.int.company.net spectx) prior to 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 IP address!) in URLs.

  • Make sure users access SpectX from systems which 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 password when users access SpectX.

Troubleshooting

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 big size of Kerberos packet wrapped into SPNEGO message sent by user’s browser in response to SPNEGO authentication request. As a matter of fact, Kerberos in Windows uses 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 meaningful value for possible 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 current one does not contain required key. It is very bad sign, as this might happen that current keytab was either altered or substituted. It is recommended to find a root cause for such incident.

Active Directory Group Membership Verification in LDAP

Active Directory Group membership verification using PAC field of a Kerberos packet does not require any additional configuration, as it does not stand in need for any connectivity to Active Directory domain services.

Membership verification over LDAP protocol, however, require the following point to be carefully considered:

  • LDAP service access configuration
  • Kerberos configuration on SpectX machine.

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 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 response, its value is used for a value of full name property for a newly created user account in 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 SpectX machine. If it is not, it must be added to 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 correctly [domain_realm] section in it to specify mapping of hostname of LDAP server to Kerberos realm name. The minimal krb5.conf might look then as follows:

[realms]
  INT.COMPANY.COM = {
      kdc = dc.int.company.net
  }
[domain_realm]
    int.company.net = 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://int.company.com‘ then SPN for it should look like ‘ldap/int.company.com’; however, it might be missing but there is actually correct one ‘ldap/dc.int.company.net’ for accessing with url ‘ldap://dc.int.company.net‘.

Make sure the keytab is always up to date with 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 “javax.security.auth.login.LoginException: No key to store”.

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/spectx.int.company.net@INT.COMPANY.COM

The command may be prepended with “env KRB5_CONFIG=/path/to/krb5.conf ” in order 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 LDAP search tool, you can test if LDAP query can be successfully executed with obtained Kerberos credentials by running the command:

$ ldapsearch -H ldap://dc.int.company.net -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

Locating the krb5.conf Configuration File

The essential Kerberos configuration information is the default realm and the default KDC. If you set wgui.spnegoAuth.kdc in SpectX’s configuration file to indicate KDC location, it is not obtained from a krb5.conf configuration file. Also in this case, value of wgui.spnegoAuth.realm becomes system-wide default Kerberos realm.

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

  • If the configuration property wgui.spnegoAuth.krb5Conf is set, its value is assumed to specify the path and file name.

  • If that configuration property value is not 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 content of krb5.conf file, consult MIT documentation .

The minimal krb5.conf might look as follows:

[realms]
  INT.COMPANY.COM = {
      kdc = dc.int.company.net
  }