LiveView Authentication and Authorization for Kerberos

Introduction

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

  • TIBCO LiveView™ Web

  • Java Client API

  • .NET Client API

  • The lv-client command

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.

Encryption Considerations

If your site’s Kerberos server infrastructure uses stronger encryption levels (such as AES-256) than the ones supported by the standard Oracle JDK shipped with StreamBase, you may need to download and install a Java Cryptography Extension. See the JDK Cryptography Features row of the Supported Configurations page for further information.

Required Server Configuration Files

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

liveview.properties

This property file enables LiveView authentication and authorization, and configures both for Kerberos and SPNEGO.

liveview.auth.properties

Use this property file when LiveView authentication is enabled. It must include assignments of LiveView user names and their roles. Roles define a set of permissions to access LiveView resources.

sbd.sbconf

Use then StreamBase Server configuration file to add system properties for the LiveView project, including required and optional properties for Kerberos setup.

login.conf

This is the Java Authentication and Authorization Service (JAAS) configuration file. Depending on how JAAS login configuration is set up, the client can either use keytab files (if for an unattended application, for example), or the kinit command (if user-controlled).

Optionally use the login configuration file to configure the server's internal client connections. If one is provided, TIBCO strongly recommends to use a keytab file because the LiveView server is unattended. If a login configuration file is not provided, then the server generates a temporary one. In this case, the temporary login.conf must find liveview.security.auth.X509.internal.user specified in liveview.properties for that generated file to reference.

keytab

This file holds the Kerberos credentials you can use to request a TGT (Ticket-Granting Ticket) from the Kerberos Key Distribution Center (KDC) to authenticate with the LiveView server.

There are potentially two keytabs. One is for use by the server’s internal client connections. The other is for the server listener’s use, is required, and allows the server to handshake with Kerberos. If a client keytab is not provided, the server keytab is used. The server keytab must contain an entry for HTTP/<your-host-name-FQDN>@<realm> entry. The client keytab (or server keytab if no client keytab is provided) must contain an entry for your-internal-client-name@realm, where realm is defined in the krb5.conf file.

krb5.conf

This file configures the LiveView server’s use of Kerberos, and among other things, identifies the KDC to use.

File Locations

Place the configuration files in the following locations:

  • Place the liveview.properties, liveview.auth.properties, and sbd.sbconf files at the root of your LiveView project folder.

  • Place additional required files (krb5.conf, login.conf, *.keytab, and so on) anywhere on the local machine; any configurations that require them can point to them using a full system path.

  • As noted above, *.keytab files can be stored anywhere and named anything, and do not need to reside in /etc/kerberos, for example. Since they are analogous to a user's password, TIBCO strongly recommendeds that you store keytab files securely on a local disk, and make them readable only by the root user, following your per site's security practices.

LiveView Server Configuration

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

Server Configuration Notes

  • JAAS ignores the liveview.security.auth.spnego.server.principal property in the liveview.properties file if the sun.security.krb5.principal system property is set in the sbd.sbconf file.

  • The internal client keytab file name property can be the same as the server keytab file name; they are separate properties to allow configuration flexibility.

  • The internal client keytab file name property can be omitted entirely. In this case, the server keytab is used.

  • For internal connections made by the LiveView server to itself, the server requires a Java Authentication and Authorization Service (JAAS) login context with a user-specified Kerberos principal and keytab. The principal must map to a LiveView user with sufficient privileges, and will typically be lvintern@realm.

  • If the internal client principal name is not set, then the java.security.auth.login.config system property must be set in the sbd.sbconf file.

  • If LiveView secure communication is already enabled using the system property liveview.ssl.hostname (which LiveView also uses for TLS authentication of server certificates), LiveView uses that property for Kerberos. Otherwise, you must use another system property, liveview.internal.client.hostname, which:

    • Must be set to the value to be used in the outgoing request,

    • And must be set to the FQDN of the LiveView server's Kerberos principal.

Client Configuration

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
  ;
};

Note

The profile name com.sun.security.jgss.krb5.initiate must exist to be able to sign into the LiveView server using Kerberos.

lv-client Configuration

All of the above client configuration requirements also apply to the lv-client command. You must also set the LIVEVIEW_CLIENT_JVM_ARGS environment variable in order to pass the required JVM arguments to lv-client.

Long lines are broken into parts for clarity. Run the following as a single, unbroken command:

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

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

System Property Configuration

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>

System Property Notes

  • If the internal client principal name is not set in the liveview.properties file, then the java.security.auth.login.config system property must be set in the sbd.sbconf file.

    The following is an optional JAAS configuration for an internal client to connect to the LiveView server. If the following property is not set, LiveView server will generate a login configuration for the internal client based on the internal client principal name and optional keytab liveview.properties property values.

    If an external JAAS login configuration file is specified via system property, then the file must contain a Kerberos configuration with a principal that matches what is set in the KDC. That same principal must appear in the local properties realm or LDAP server for role lookup. For example:

    java.security.auth.login.config = path/to/login.conf
  • If you specify the java.security.auth.login.config system property in sbd.sbconf, then no client principal name or client keytab properties are required. If you do not specify the system property, then the server generates a login configuration. In that case, a client principal name property is required and a client keytab property is used if present. Otherwise the server keytab property value is used.

  • For external API clients, you must set the java.security.krb5.conf and java.security.auth.login.config system properties.

  • The sun.security.spnego.debug property is optional.

krb5.conf File Example

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
  }

LiveView Roles and Mappings

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

Configuring Project Viewer to Launch Your Project

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.

Browser Configuration for LiveView Web

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.

Note

All URLs in the browser must be the FQDN of the LiveView Web server that matches the Kerberos properties in the liveview.properties file. You cannot use LiveView Web's default, http://localhost:10080. Use, for example: http://lvserv.example.com:10080.

Firefox Configuration

By default, Firefox does not attempt Kerberos authentication; you must enable this feature. The following two configurations have been tested and are known to work. This may be a non-exhaustive list of possible configurations. Consult your Kerberos administrators for site-specific details.

Configuration 1

Firefox with native Windows Kerberos Authentication (logged-in as a Windows user).

  1. Open Firefox and enter about:config in the address field.

  2. Accept the warning.

  3. In the Search field, filter the results by typing negotiate.

  4. Update the following two properties:

    Name = network.negotiate-auth.delegation-uris 
    Value = example.com
    Name = network.negotiate-auth.trusted-uris    
    Value = example.com
  5. No browser restart should be required. Navigate to your LiveView Web URL. For example, http://lvserv.example.com:10080.

Configuration 2

Firefox with MIT Kerberos Client (uses MIT Kerberos Ticket Manager to handle Kerberos tickets):

  1. Open Firefox and enter about:config in the address field.

  2. Accept the warning.

  3. In the Search field, filter the results by typing negotiate.

  4. Update the following six properties:

    Name = network.negotiate-auth.allow-non-fqdn  
    Value = true
    Name = network.negotiate-auth.allow-proxies   
    Value = false
    Name = network.negotiate-auth.delegation-uris  
    Value = example.com
    Name = network.negotiate-auth.gsslib           
    Value = C:\Program files\MIT\Kerberos\bin\gssapi64.dll 

    (Enter the full path to your MIT Client GSSAPI binary file, specifying 32- or 64-bit to match the browser version)

    Name = network.negotiate-auth.trusted-uris
    Value = example.com
    Name = network.negotiate-auth.using-native-gsslib  
    Value = false
  5. In the Search field, filter the results by typing sspi.

  6. Update the following property:

    Name = network.auth.use-sspi
    Value = false
  7. No browser restart should be required. Navigate to your LiveView Web URL. For example, http://lvserv.example.com:10080.

Chrome Configuration

Chrome inherits security settings from the system's Internet Properties dialog.

  1. Open the Control Panel (Windows 7) or search for "Control Panel" using Windows 10 Start.

  2. In the Control Panel's search search field, type: internet.

  3. Click the Internet Options heading.

  4. This opens the Internet Options dialog.

  5. Select the Security Tab.

  6. Select the Local intranet zone.

  7. Click Sites.

  8. Click Advanced.

  9. Add the URL of your LiveView Web server without the port number. For example: http://lvserv.example.com.

    Also add just the domain name of the same server. For example: example.com.

  10. Close dialogs back to the Security tab.

  11. In the Security level for this zone section, click Custom level.

  12. At the bottom of the list of Settings there is a section called User AuthenticationLogon. Make sure Automatic logon only in Intranet zone is selected.

  13. Close all instances of Internet Explorer, Chrome, and (on Windows 10) Edge.

  14. Open Chrome and navigate to your LiveView Web URL: http://lvserv.example.com:10080.

Edge Configuration

Edge also inherits security settings from the system's Internet Properties dialog. If you already performed this steps for Chrome, you can skip steps 1 to 11.

  1. Open the Control Panel (Windows 7) or search for "Control Panel" using Windows 10 Start.

  2. In the Control Panel's search search field, type: internet.

  3. Click the Internet Options heading.

  4. This opens the Internet Options dialog.

  5. Select the Security Tab.

  6. Select the Local intranet zone.

  7. Click Sites.

  8. Click Advanced.

  9. Add the URL of your LiveView Web server without the port number. For example: http://lvserv.example.com.

    Also add just the domain name of the same server. For example: example.com.

  10. Close dialogs back to the Security tab.

  11. In the Security level for this zone section, click Custom level.

  12. At the bottom of the list of Settings there is a section called User AuthenticationLogon. Make sure Automatic logon only in Intranet zone is selected.

  13. Close all instances of Edge, Internet Explorer, and Chrome.

  14. Open Edge and navigate to your LiveView Web URL: http://lvserv.example.com:10080.

    Note

    If you are using Edge on Windows 10, and you are attempting to use a local instance of LiveView Web on localhost, you may run into a security configuration that prevents access to loopback addresses.

  15. Open a command prompt as Administrator (this requires elevated privileges).

  16. Execute the following command to exempt the Edge browser from the loopback restriction:

    CheckNetIsolation LoopbackExempt -a -n="Microsoft.MicrosoftEdge_8wekyb3d8bbwe"
  17. Open Edge and navigate to your localhost LiveView Web URL: http://localhost:10080.