SPNEGO/Kerberos

The LumisXP includes an integrated authentication implementation using SPNEGO/Kerberos. To use this form of authentication, it is necessary to perform the appropriate configuration in LumisXP and in the Kerberos authentication server.

For this form of authentication to work, both the portal server and the client browser must have access to the Kerberos authentication server (KDC).

Users authenticated by this functionality must have a login in the format user@mydomain.com.

Configuration in LumisXP

In LumisXP, it is necessary to configure the class lumis.portal.authentication.http.SpnegoAuthenticator in the <httpAuthenticator> element of lumisportalconfig.xml:

<security> <httpAuthenticator className="lumis.portal.authentication.http.SpnegoAuthenticator" ></httpAuthenticator>  </security>

It is also necessary to carry out the proper configuration of the connection to the Kerberos server. For this, uncomment the kerberos/configurationFile element, and if desired, adjust the path to the desired file:

<security> <httpAuthenticator className="lumis.portal.authentication.http.SpnegoAuthenticator" ></httpAuthenticator>  <kerberos> <configurationFile>security/krb5.conf</configurationFile> </kerberos> </security>

In the Kerberos configuration file (with the example configuration above, it would be in lumisdata/config/security/krb5.conf), configure according to the environment of the server that will be used for authentication.

Example of configuration:

[domain_realm] .mydomain.com = MYDOMAIN.COM [libdefaults] default_tkt_enctypes = aes128-cts rc4-hmac des3-cbc-sha1 des-cbc-md5 des-cbc-crc default_tgs_enctypes = aes128-cts rc4-hmac des3-cbc-sha1 des-cbc-md5 des-cbc-crc permitted_enctypes = aes128-cts rc4-hmac des3-cbc-sha1 des-cbc-md5 des-cbc-crc default_realm = MYDOMAIN.COM [realms] MYDOMAIN.COM = { kdc = 10.200.20.12 default_domain = MYDOMAIN.COM }

Configure a LoginModule named LumisPortalSpnego to perform authentication using this Kerberos configuration (The configuration location for the LoginModule depends on your application server. See in the installation instructions of LumisXP on your application server where the LumisPortal LoginModule was installed, and do the equivalent for the example below. In environments without specific instructions, such as in Tomcat, this configuration should be adjusted in lumisdata/config/lumissecuritylogin.config). Example configuration of the LoginModule:

LumisPortalSpnego { com.sun.security.auth.module.Krb5LoginModule required debug=false storeKey=true doNotPrompt=true useKeyTab=true keyTab="${lumis.portal.lumisDataPath}/config/security/lumisportal.keytab" principal="lumisportalservice@MYDOMAIN.COM"; };

In the configuration above, the principal attribute must correspond to the user that the portal will use to access Kerberos. The authentication keys for this user must be present in the specified keyTab.

Configuration in Active Directory

To use SPNEGO/Kerberos with Active Directory, the following steps need to be taken:

Create a user to be used by LumisXP to process authentications. It may be desirable to configure the user so that the password does not expire over time, to avoid manually changing the password and recreating the keytab for the user after expiration. For illustrative purposes, it will be assumed that this user's login is lumisportalservice@MYDOMAIN.COM.
Service Principal Names (SPNs) for the user. For this operation, use setspn.exe from the command line on your Windows server. If your Windows server does not have setspn.exe, obtain it by installing Windows Support Tools.
SPNs must be added to the user in the form of HTTP/<hostname>, where <hostname> corresponds to the possible hosts that can refer to the portal server. For example:

setspn -s HTTP/portalserver lumisportalservice setspn -s HTTP/portalserver.mydomain.com lumisportalservice setspn -s HTTP/intranet.myportal.com lumisportalservice setspn -s HTTP/www.myportal.com lumisportalservice

Note

In older versions of the setspn command, the -s option is not available, and -A should be used instead. In this case, care should be taken not to register the same SPN for more than one user, as this could cause problems during the authentication process.

To view the SPNs associated with the user, you can execute:

setspn -L lumisportalservice
keytab file containing the authentication keys for the user created in item (1). The JDK comes with ktab.exe, found in its bin directory. It should be used to generate the keytab file. It can be executed on any machine and does not have to be on the server.
To create the keytab file, you can run:

ktab -a lumisportalservice@MYDOMAIN.COM -n 0 -k lumisportal.keytab

After executing this command, it will prompt for the user's password. Then the specified file (in the example lumisportal.keytab) will be generated.

The "-n 0" argument indicates that the key should have a version (KVNO) of 0 (zero). When the key has version zero, its version number will not be validated against the version number on the server. You can instead use the correct version number, but in this case it has to match what is stored on the server; otherwise, the key will not work. To find out the key number on the Active Directory server, execute ADSIEdit.msc, go to the user, open its properties, and check the value of the msDS-KeyVersionNumber attribute.

Note

In the ktab distributed with Java 6, the -n <kvno> argument is not available, so it is not possible to specify the version number to be used. It simply uses an incremental number starting from 1. Therefore, if the version number on the server is 6, you would need to execute this command 6 times in succession for the version number in the keytab file to increment to 6. To use the -n <kvno> argument as in the example above, use the ktab distributed with Java 7.

To view information about the keys stored in a keytab file, execute the command as shown in the example below:

C:\Java\jdk1.7.0\bin>ktab -l -e -t -k lumisportal.keytab Keytab name: lumisportal.keytab KVNO Timestamp Principal ---- -------------- ---------------------------------------------------------------------- 0 21/09/12 18:31 lumisportalservice@MYDOMAIN.COM (17:AES128 CTS mode with HMAC SHA1-96) 0 21/09/12 18:31 lumisportalservice@MYDOMAIN.COM (23:RC4 with HMAC) 0 21/09/12 18:31 lumisportalservice@MYDOMAIN.COM (16:DES3 CBC mode with SHA1-KD) 0 21/09/12 18:31 lumisportalservice@MYDOMAIN.COM (3:DES CBC mode with MD5) 0 21/09/12 18:31 lumisportalservice@MYDOMAIN.COM (1:DES CBC mode with CRC-32)

After creating the keytab file, move it to the portal installation and reference it in the keyTab attribute of the LumisPortalSpnego Login Module, as exemplified earlier.

Web Browsers

Once the portal is configured correctly, browsers can automatically perform authentication depending on their characteristics and configurations:

Internet Explorer: By default, it performs automatic authentication if the accessed address is considered an intranet zone. You can use the group policy feature of Active Directory to automatically configure domain machines to consider portal addresses as intranet zone, if that is not already the case.
Google Chrome: Does not have specific configuration but uses the same configuration as Internet Explorer.
Mozilla Firefox: Access about:config and include in the network.negotiate-auth.trusted-uris parameter the addresses, separated by commas, that are trusted for automatic authentication. In corporate environments, you can use the Firefox feature to push configurations in the corporate environment to implement this configuration on client machines in the environment.

Troubleshooting

If automatic authentication is not working as expected, some ways to obtain more information in order to try to resolve the issue are:

Check information present in the LumisXP logs.
If not enabled, in lumislogconfig.yml enable debug logging for the logger lumis.portal.authentication.http.SpnegoAuthenticator.
Enable debug messages for the Login Module, adding the debug=true parameter in the com.sun.security.auth.module.Krb5LoginModule in LumisPortalSpnego. These messages are normally issued to the standard output (System.out) of the application.
Enable debug messages for Kerberos, including a system property sun.security.krb5.debug with the value true in the JVM of the application server. These messages are normally issued to the standard output (System.out) of the application.