LiveView Authentication and Authorization for Kerberos

This article describes how to configure Kerberos Single Sign-on with SPNEGO (hereafter, Kerberos, unless noted) for LiveView server-client communications. Supported clients include:

Kerberos is a network authentication protocol for client-server applications, and SPNEGO provides a mechanism for extending Kerberos to web applications through the HTTP protocol. LiveView servers can be enabled for Kerberos to verify the identity of clients (authentication) and ensure that authenticated clients have permission to access the requested resources on the LiveView server side (authorization).

This article assumes familiarity with LiveView authentication and authorization concepts. Familiarity with Kerberos Single Sign-on with SPNEGO concepts is also assumed.

The LiveView Authentication and Authorization sample provides template liveview.properties, liveview.auth.properties, and sbd.sbconf files that can be used as the basis for adding a Kerberos configuration to your LiveView application. To load and run the project, follow the steps in the sample's README.txt file.

The other required configuration files are assumed to be in place for LiveView-Kerberos configuration. Their formats are described in the Massachusetts Institute of Technology (MIT) Kerberos documentation (krb.conf, keytab) and the Oracle documentation for JAAS login configuration files and the JAAS Krb5LoginModule client login configuration file, respectively.

To configure Kerberos Single Sign-on with SPNEGO, you need the following files:

Add the following properties to the liveview.properties file to enable Kerberos for your specified realm. Replace the values with your site-specific values such as hostname, principal name, and keytab file location. The realm is defined in the krb5.conf file.

Long lines wrap to the next for clarity.

liveview.security.auth.filter = spnego
liveview.internal.client.hostname = thispc.example.com 
liveview.security.auth.spnego.server.principal.name=HTTP/thispc.example.com@realm
liveview.security.auth.spnego.server.keytab.file.name=/etc/kerberos/ldm-server.keytab
liveview.security.auth.spnego.internal.client.principal.name=lvintern@realm
liveview.security.auth.spnego.internal.client.keytab.file.name=/etc/kerberos/
  ldm-internal-client.keytab
liveview.security.auth.spnego.jaas.debug=true|false

Configure a Kerberos-provided JAAS login file as follows. The Kerberos Key Distribution Center (KDC) requires an HTTP service principal entry for the LiveView server. For example, HTTP/lvserv.example.com@REALM.

Depending on how the JAAS login configuration is set up, the client can either use keytabs (if an unattended application, for example), or the kinit command (if controlled by an end user).

For external API clients, you must also set the java.security.krb5.conf and java.security.auth.login.config system properties in the sbd.sbconf file to point to a JAAS login configuration file set with a Kerberos entry.

Internal client configuration does not require a login configuration, as described in the server configuration section. If you do not provide one, the server generates a temporary one and you must provide a client principal name in liveview.properties, for the generated configuration file to reference.

Following is a sample login file using a keytab:

com.sun.security.jgss.krb5.initiate {
  com.sun.security.auth.module.Krb5LoginModule required
  keyTab="/etc/my.keytab"
  principal="lvintern@example.com"
  doNotPrompt=true
  debug=false
  useTicketCache=true
  useKeyTab=true
  storeKey=true
  renewTGT=true
  isInitiator=true
  ;
};

The following shows a login file without a keytab set; the client must run the Kerberos-provided kinit tool to create a Kerberos Ticket-Granting Ticket:

com.sun.security.jgss.krb5.initiate {
  com.sun.security.auth.module.Krb5LoginModule required
  principal="lvintern@example.com"
  doNotPrompt=true
  debug=false
  useTicketCache=true
  useKeyTab=false
  storeKey=false
  renewTGT=true
  isInitiator=true
  ;
};

shellcmd LIVEVIEW_CLIENT_JVM_ARGS=
  -Dliveview.internal.client.hostname=thispc.example.com 
  -Djava.security.krb5.conf=c:/kerberos/krb5.conf 
  -Djava.security.auth.login.config=c:/kerberos/login.conf

The following is a sample sbd.sbconf file where you set system properties. The LiveView Authentication and Authorization sample shipped with TIBCO Live Datamart provides a template in which you can add properties pertaining to Kerberos configuration.

Long lines wrap to the next for clarity.

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<streambase-configuration xmlns:xi="http://www.w3.org/2001/XInclude" 
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
  xsi:noNamespaceSchemaLocation="http://www.streambase.com/schemas/sbconf/">
  <global>
    <module-search directory="lv-interfaces"/>
    <module-search directory="ItemsSalesDataSource"/>
  </global>

  <java-vm>
    <param name="jvm-args" value="-Xms256m -Xmx512m" />
    <sysproperty name="java.security.krb5.conf" value="c:/kerberos/krb5.conf"/>
    <sysproperty name="sun.security.krb5.debug" value="true"/>
    <sysproperty name="sun.security.spnego.debug" value="false"/>
    <sysproperty name="liveview.internal.client.hostname" value="thispc.example.com"/>
 <!-- <sysproperty name="liveview.ssl.hostname" value="myhost.example.com"/> -->

    <sysproperty name="liveview.internal.username" value="sb-test"/>
    <sysproperty name="logback.configurationFile" value="logback.xml"/>        
     
    <!-- 
    <sysproperty name="liveview.internal.username" value="lvintern"/>
    <sysproperty name="liveview.internal.password" value="lvintern"/>  
    -->
    <sysproperty name="liveview.web.pstore.type" value="h2"/>
  </java-vm>
</streambase-configuration>

The following is a krb5.conf file example which is used to configure the LiveView server's use for Kerberos, and identifies the KDC to use.

[libdefaults]
  default_realm = EXAMPLE.COM

[realms]
  EXAMPLE.COM = {
    kdc = example.com
    admin_server = example.com
  }

[domain_realm]
  .example.com = EXAMPLE.COM
  example.com = EXAMPLE.COM

[logging]
  default = FILE:c:\\kerberos\\kdc.log
  kdc = FILE:c:\\kerberos\\kdc.log
  kdc_rotate = {
  period = 1d
  versions = 10
  }

[appdefaults]
  kinit = {
  renewable = true
  forwardable = true
  }

Each defined LiveView user can have one or more roles, which are sets of permissions mapped to the role per user in liveview.auth.properties, and described in LiveView Roles. Define your LiveView users as required.

Sample follows:

# LiveView user-to-role mapping. 
# Any of the passwords below can be enciphered using the sbcipher utility. 
# Refer to the Enciphering Passwords page of the StreamBase Administration 
# Guide for details. 
# user.name = password,role1,role2,...
user.admin = admin,LVAdmin
# user.admin = ,LVAdmin
user.lvintern = lvintern,LVInternal
user.someone = ,LVAdmin

If you use the LiveView Project Viewer to launch your Kerberos-enabled LiveView project, you must set the STREAMBASE_STUDIO_EARLYSTART_SYSPROPS environment variable from the command prompt, and then start Studio from that command prompt by typing sbstudio on Windows, or sbstudio & on macOS or Linux. Run the following as a single command; long lines are shown in parts for clarity:

shellcmd STREAMBASE_STUDIO_EARLYSTART_SYSPROPS=
  liveview.internal.client.hostname=thispc.example.com;
  java.security.krb5.conf=c:/kerberos/krb5.conf;
  java.security.auth.login.config=c:/kerberos/login.conf

where shellcmd is set for Windows or export for the Bash shell on macOS or Linux.

Mozilla Firefox, Google Chrome, and Microsoft Edge can be enabled for use in a Kerberos environment. Once configured, you can launch LiveView Web in a browser as a client connection to a LiveView server that you have also enabled for Kerberos.

The instructions in this section are Windows-specific. Adjust as necessary for macOS and Linux.