Windows Authentication via Kerberos in the LDAP Connector

This feature enables Windows Authentication for Seeq servers running on Linux, or which are not domain-connected. For most use-cases, a simpler and more reliable interface will be the Windows Authentication connector, which runs only on Windows.

Overview

Seeq supports authentication and authorization via the LDAP connector, where a user can provide their username and password to be checked against a central LDAP database, typically Microsoft Active Directory. The benefit of LDAP authentication is that users and group membership are managed centrally, so there is no duplication of that information. When a new hire joins a company, in order to have access to Seeq they only need an Active Directory login and to be assigned to the appropriate group. No Seeq-specific configuration is needed. And, if an existing employee leaves the group or is terminated, their access to Seeq will be revoked similarly.

Windows Authentication has all of the same benefits of LDAP, plus the ability to log in to Seeq without providing a username and password. A user simply has to be logged in to their domain account, and their web browser will provide an encrypted token proving their identity. This allow for "one click" access to Seeq: just click the "Log in" button to get access.

Prerequisites

The current implementation of Windows Authentication is cross-platform, so it can run on a Seeq server that uses Windows or Linux, and that server does not have to be connected to the Active Directory domain. Rather than the Seeq instance connecting to the domain, some data needs to be configured on the domain and exported:

Browsers must consider the Seeq site to be trusted

In order for Seeq to use Windows Authentication, the browser must consider the website for your Seeq instance to be a trusted site.

Chrome and Internet Explorer both respect the settings in Internet Explorer's Internet Options → Security, which should look like the screenshot below. For larger companies, you will likely not be able to change these settings, so instead you will want to make sure that you host the Seeq website where it will be considered part of your intranet.

Create a dedicated Seeq user in the Active Directory domain

To create a user on the Active Directory domain, you will need administrator access. For larger companies, this will likely require working with your IT department.

On Windows Server, you can open Server Manager → Tools → Active Directory Users and Computers.

Create a user, with a meaningful name, set their password, and check the "Password never expires" box. This is not strictly mandatory but makes it easier to maintain the system. Later we will export a Keytab file which is generated based on the password. Whenever the password changes, the Keytab file will have to be updated as well.

Set ServicePrincipalNames (SPN) and export keytab for dedicated Seeq user

In a Windows Command Prompt (cmd.exe) run as Administrator:

setspn -A HTTP/seeq.example.com seeq-ldap-user

replacing seeq.example.com with the hostname where Seeq Server (not the hostname of the Remote Agent running Windows Auth) will be running and seeq-ldap-user with the username created above.

The result should look like the screenshot below, with different values:

The result of "setspn" is a change of configuration on the Active Directory domain controller. Next, you need to export the Keytab, which produces a file that is needed by the Seeq connector. Run the following in the command prompt:

ktpass /out C:\seeq-ldap-user.keytab /mapuser [email protected] /princ HTTP/[email protected] /pass seeq-ldap-user-password /kvno 0 /ptype KRB5_NT_PRINCIPAL

Where you'll have to replace:

C:\seeq-ldap-user.keytab with the location on disk where the keytab should be produced. It can be any directory where you have write permissions, such as your Desktop.
seeq-ldap-user with the Seeq dedicated username
EXAMPLE.COM with the name of the Active Directory domain, in all capitals
seeq.example.com with the hostname of the server where Seeq will run. This is the same as the URL, but with no http:// prefix and no suffix.
seeq-ldap-user-password with the password for the Seeq dedicated user

Now you should have a keytab file. Copy it to the server where Seeq (or the Seeq agent) will run and set the configuration options.

Configuration

Config Key	Notes
CODE `KerberosKeytabLocation`	Required for Windows Authentication. A path on the file system pointing to a Keytab file, for example: CODE `"C:\\ProgramData\\Seeq\\data\\keys\\seeq.keytab"` Note that backslashes as used in the Windows file system must be escaped by using two backslashes.
CODE `KerberosServicePrincipal`	Required for Windows Authentication. The name of the service principal determined when you followed the "Set SPN" instructions above. The value should look like: CODE `"HTTP/[email protected]"`
CODE `LdapSearchUsername`	If using LDAP authorization (group filtering) with Windows Authentication, these properties are required. Seeq needs a set of credentials to use to connect to the LDAP server to search for group members. We recommend using a special username and password for Seeq, not any individual's personal login.
CODE `LdapSearchPassword`

Examples

Windows authentication only: all domain users have access to Seeq, not restricted to group membership

CODE

{
  "Version":"com.seeq.link.connectors.ldap.config.LdapConnectorConfigV1",
  "Connections":[
    {
    "Name":"Windows Auth: members of 'Seeq Access Authorized' have access to Seeq",
    "Id":"598da8e5-8ef9-400e-a864-2e1ca4ec7688",
    "Enabled":true,
    "VerboseLogging":false,
    "KerberosKeytabLocation":"C:\\ProgramData\\Seeq\\data\\keys\\seeq.keytab",
    "KerberosServicePrincipal":"HTTP/[email protected]"
    }
  ],
  "Help":"For examples and documentation, see https://seeq12.atlassian.net/wiki/spaces/KB/pages/112822971"
}

Windows authentication with LDAP authorization: only members of a specific group have access to Seeq

CODE

{
  "Version":"com.seeq.link.connectors.ldap.config.LdapConnectorConfigV1",
  "Connections":[
    {
    "Name":"Windows Auth: members of 'Seeq Access Authorized' have access to Seeq",
    "Id":"598da8e5-8ef9-400e-a864-2e1ca4ec7689",
    "Enabled":true,
    "VerboseLogging":false,
    "KerberosKeytabLocation":"C:\\ProgramData\\Seeq\\data\\keys\\seeq.keytab",
    "KerberosServicePrincipal":"HTTP/[email protected]",
    "Hostname":"ad.example.com",
    "Port":389,
    "BaseDn":"cn=Users,dc=example,dc=com",
    "Filter":"(&(objectCategory=person)(objectClass=user)(memberOf=cn=Seeq Access Authorized,dc=example,dc=com))",
    "LdapSearchUsername":"seeq-ldap-user",
    "LdapSearchPassword":"<seeq-ldap-user's password>"
    }
  ],
  "Help":"For examples and documentation, see https://seeq12.atlassian.net/wiki/spaces/KB/pages/112822971"
}

Known Issues

After upgrading to R56, users may find that Kerberos authentication has suddenly stopped working. The jvm-link.log may contain an error similar to Failure unspecified at GSS-API level (Mechanism level: Encryption type RC4 with HMAC is not supported/enabled). This is due to a Java update that was introduced in R56 in which the less secure encryption types are not enabled by default. The solution is to have the Active Directory admin modify the Seeq Server service account to use more secure encryption methods such as AES 128 and AES 256. If that’s not immediately possible, implement the following workaround:

On the Seeq server, create a file called krb5.conf in the Seeq data folder and paste in the following content:

CODE

[libdefaults]
allow_weak_crypto=true

2. Using the Seeq command prompt, set the -Djava.security.krb5.conf to point to the krb5.conf file:

CODE

seeq config set Process/JvmLink/AdditionalVMOptions -Djava.security.krb5.conf=C:\path\krb5.conf

3. Restart Seeq.