Table of contents

General

Using Kerberos as authentication mechanism to connect to the Studio can be done by using one of the following authentication types:

1. KERBEROS - Uses the credentials of the user running the application server process (when using the LSA as the Windows configuration below) or using fixed credentials stored in a keytab on disk (as the Linux configuration below).
2. KERBEROS_CUSTOM - Uses custom credentials in the form of realm user name and password.

Running the Runtime under Windows

The recommended configuration for Windows setups is using the Local Service Authority to retrieve the credentials for the Kerberos default authentication.

The following steps have to be performed to have a working Kerberos client:

1. Create the JAAS Login Configuration file

Create a file in a secure location (%AQUIMA_HOME%\krb5login.conf for example) with the following contents:

com.sun.security.jgss.initiate {
  com.sun.security.auth.module.Krb5LoginModule required
  client=true
  doNotPrompt=true
  useTicketCache=true;
};
com.sun.security.jgss.login {
  com.sun.security.auth.module.Krb5LoginModule required
  client=true;
};

The com.sun.security.jgss.initiate context is used for the default Kerberos authentication and instructs the authentication and authorization service (JAAS) to use the LSA for retrieving the current credentials.

The com.sun.security.jgss.login context is used for the custom Kerberos authentication.

2. Create the Kerberos configuration file

This file describes the domains that are available and the translation between domains and realms.

Create a file in a secure location (%AQUIMA_HOME%\krb5.conf for example) with the following contents:

[realms]
<for each domain with users that should be able to log in>
  <fqdn in uppercase> = {
    kdc = <domain controller fqdn>
  }
<end for each>
 
[domain_realm]
<for each domain with users that should be able to log in>
  .<fqdn> = <fqdn in uppercase>
  <fqdn> = <fqdn in uppercase>
<end for each>

Assuming there are 2 domains that should allow login (hr.example.com and financial.example.com), the file should look like:

[realms]
  HR.EXAMPLE.COM = {
    kdc = dc.hr.example.com
  }
  FINANCIAL.EXAMPLE.COM = {
    kdc = domain_controller.financial.example.com
  }
 
[domain_realm]
  .hr.example.com = HR.EXAMPLE.COM
  hr.example.com = HR.EXAMPLE.COM
  .financial.example.com = FINANCIAL.EXAMPLE.COM
  financial.example.com = FINANCIAL.EXAMPLE.COM

3. Set the java runtime environment options

The following java options can be set:

Assuming the location of the configuration files as suggested above, the following configuration options would have to be set:

-Djava.security.krb5.conf=%AQUIMA_HOME%\krb5.conf -Djava.security.auth.login.config=%AQUIMA_HOME%\krb5login.conf -Djavax.security.auth.useSubjectCredsOnly=false

set JAVA_OPTS=-Djava.security.krb5.conf=%AQUIMA_HOME%\krb5.conf -Djava.security.auth.login.config=%AQUIMA_HOME%\krb5login.conf -Djava.security.debug=configfile,configfileparser,logincontext -Dsun.security.krb5.debug=true -Djavax.security.auth.useSubjectCredsOnly=false

4. (Optional) Enable debug level logging

A typical example would be setting the following java options:

-Djava.security.krb5.conf=%AQUIMA_HOME%\krb5.conf -Djava.security.auth.login.config=%AQUIMA_HOME%\krb5login.conf -Djava.security.debug=configfile,configfileparser,logincontext -Dsun.security.krb5.debug=true -Djavax.security.auth.useSubjectCredsOnly=false

5. Install the Java Cryptography Extensions

Due to US export laws, the JDK and JRE are shipped with limited cryptography extensions. More importantly, AES256 is not supported by default. If the AD uses AES256 encryption (since Windows Server 2008), then the unlimited Java Cryptography Extension (JCE) Policy must be downloaded and installed. The Unlimited JCE Policy consists of two jar files which must be placed in %JAVA_HOME%/jre/lib/security. The installed JCE must match the JDK/JRE version. The following table provides quick links to these policies:

6. Enable TGT session key retrieval from the LSA

In order for the Java Runtime to be able to use the credentials from the LSA, a Windows Registry setting needs to be enabled in order to allow the session key from the TGT to be read. Under HKEY_LOCAL_MACHINE/SYSTEM/CurrentControlSet/Control/Lsa/Kerberos/Parameters, add the following entry:

• name: AllowTgtSessionKey
• type: dword
• value: 1

Normally, the Runtime should not be running as a Local Administrator user, but in development or testing it may happen that, for reasons outside control, the Runtime will run as such a user. In this case, the registry setting should be enabled and when finished it should be turned off again, as it is a potential security risk. See https://support.microsoft.com/en-us/kb/2627903 for details.

7. Check DNS and reverse DNS entries

Kerberos is very sensitive to DNS configuration because it uses it by default to canonicalize host names. So you have to make sure DNS and reverse DNS entries are available for the machine running the runtime, the machine running the studio and the domain controllers of the domains.

Assuming we have the following:

• A studio running on machine m1 in domain1 with domain controller dc1;
• A runtime running on machine m2 in domain2 with domain controller dc2;
• We try to login with the user user@DOMAIN1.

We should check the following DNS records exist and are accessible on m2:

• A and PTR records for the local machine (m2.domain2);
• A and PTR records for the user's domain controller (dc1.domain1);
• A and PTR records for the service machine (m1.domain1).

If we plan to login with domain2 users as well, we should also check for:

• A and PTR records for the domain2 domain controller (dc2.domain2);

8.  Endpoint Identity Configuration

For HTTP services, the default service identity assumed by browsers is the SPN "HTTP/hostname". For example, if the URL for StudioService is "http://studio-pc:8093/Services/StudioService", then browsers assume the identity of this service is the SPN "HTTP/studio-pc".
The SPN is in essence an alias for a domain account (user account or computer account). In order to create this alias, the setspn.exe command must be used: 

For development mode there is an easier option:

1. download the PsTools Suite from https://technet.microsoft.com/en-us/sysinternals/bb896649.aspx and add it to your %PATH%
2. build the Studio solution as usual (Any CPU)
3. from a command prompt, run psexec -s "full path to StudioServer.exe"
   1. for example: psexec -s "D:\blueriq\Studio\src\Server\StandAlone\StudioServer\bin\Debug\StudioServer.exe"
4. check with task manager that StudioServer is running as System
5. if you want to debug from Visual Studio, use Debug > Attach to Process.., check the "Show processes from all users" checkbox, then attach to StudioServer.exe

Running the Runtime under Linux

The recommended configuration for Linux setups is:

• Application server running with local secured user (no sudo, no suid, no ssh login, etc.);
• Java runtime getting login information from a keytab file.

1. Generate a keytab file

1. Install the krb5-user package - this depends on the operating system (yum install krb5-user for redhat for example).
2. Generate the keytab file:
   1. Run kutil (simply run kutil without arguments in a terminal).

   2. Add an entry for the user that should be used to log in: 

      addent -password -p <user>@<fqdn in uppercase> -k 1 -e rc4-hmac

   3. Write the keytab file 

      wkt <keytab file name>

   4. Exit kutil: 

      quit

3. Check the contents of the keytab file: 

   klist -k -t <path to keytab file>

4. Move the keytab file to a secure location ($AQUIMA_HOME\keytab in our example)

   1. Do not forget to set the owner the user running the application server.

   2. Do not forget to set file permissions allowing read only for the user running the application server and no writes (400).

2. Create the JAAS Login Configuration file

Create a file in a secure location ($AQUIMA_HOME\krb5login.conf for example) with the following contents:

com.sun.security.jgss.initiate {
  com.sun.security.auth.module.Krb5LoginModule required
  doNotPrompt=true
  principal="<user>@<fqdn in uppercase>"
  useKeyTab=true
  keyTab="<path to keytab file>"
  storeKey=true;
};
com.sun.security.jgss.login {
  com.sun.security.auth.module.Krb5LoginModule required
  client=true;
};

4. Set the java runtime environment options

This is identical to setting the properties in Windows.

A tomcat setenv.sh might look like:

export AQUIMA_HOME=<path to aquima home>
export JAVA_OPTS="-Djava.security.krb5.conf=$AQUIMA_HOME\krb5.conf -Djava.security.auth.login.config=$AQUIMA_HOME\krb5login.conf -Djava.security.debug=configfile,configfileparser,logincontext -Dsun.security.krb5.debug=true -Djavax.security.auth.useSubjectCredsOnly=false"

5. (Optional) Enable debug level logging

This is identical to the Windows procedure.

6. Install the Java Cryptography Extensions

This is identical to the Windows procedure.

7. Check DNS and reverse DNS entries

This is identical to the Windows procedure.

8. Endpoint Identity Configuration

This is identical to the Windows procedure.