LiveView Authentication and Authorization for Kerberos

This article describes how to configure Kerberos Single Sign-on with SPNEGO for your LiveView server and communicate to it via a client. 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 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 basic LiveView Authentication and Authorization concepts. See LiveView Authentication and Authorization for more information. Familiarity with Kerberos concepts is also assumed.

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

Place the files used in this configuration in the following folder locations:

When local or LDAP LiveView authentication is enabled, a LiveView client identifies itself to the server with a username and password. These credentials can be included in a LiveView URI by placing them between the protocol field and server name in the URI. For example:

lv://username:password@localhost:port

Note that a colon (:) delimits the username and password, while an at sign (@) delimits the username and password from the server name.

Passwords in the liveview.properties and liveview.auth.properties files can be stored as either clear text or enciphered text. Encipher a password as follows:

sbcipher -c "secret1ve"
MeQxOjzFAR2MRKoyrA5x8pQYRwrGWc7FkOw2/+AMltwstrNSLbGUmA1YBvEq+UUkJ/Sxe5jOLUO2oax1KypNRw==

Replace the clear text password in liveview.properties, liveview.auth.properties, or sbd.sbconf with the enciphered text returned by sbcipher. For example:

liveview.security.auth.active.dir.password=MeQxOjzFAR2MRKoyrA5x8pQYRwrGWc7F
kOw2/+AMltwstrNSLbGUmA1YBvEq+UUkJ/Sxe5jOLUO2oax1KypNRw==

The example above is broken into two lines for clarity.

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.

This example defines a realm called STREAMBASE.COM:

SPNEGO/Kerberos Configuration

liveview.security.auth.filter = spnego
liveview.security.auth.realm=properties
liveview.security.auth.properties.file=liveview.auth.properties
liveview.internal.client.hostname = qa35.lab.streambase.com
liveview.security.auth.spnego.server.principal.name=HTTP/qa35.lab.streambase.com@STREAMBASE.COM
liveview.security.auth.spnego.server.keytab.file.name=c:/kerberos/ldm-server.keytab
liveview.security.auth.spnego.internal.client.principal.name=sb-test@STREAMBASE.COM
#liveview.security.auth.spnego.internal.client.principal.name=HTTP/qa35.lab.streambase.com@STREAMBASE.COM
liveview.security.auth.spnego.jaas.debug=true

Each LiveView user can have one or more role, which are sets of permissions mapped to them in liveview.auth.properties and described in LiveView Privilege Settings. Once defined, they can be mapped. Here is an example:

# LiveView user-to-role mapping
#user.<name> = <password>,<role1>,<role2>,...
user.lvmanager = lvmanager,LVAdmin
user.lvguest = lvguest,LVUser
user.lvinternal = lvinternal,LVIntern

LiveView Privilege Settings shows a list of available permissions and how they are mapped to LiveView user roles.

The following is a portion of the LiveView Auth sample's liveview.auth.properties file. Add LiveView users and roles as required for your Kerberos configuration. The following example defines the following users

Each is used for... purposes.

Long lines wrap to the next, for clarity.

# LiveView user-to-role mapping. Any/all of the password below can be enciphered using the 
# sbcipher utility. 
# Refer to the Enciphered Passwords of the LiveView Server System Configuration document for 
# details. 
#user.<name> = <password>,<role1>,<role2>,...
user.admin = admin,LVAdmin
#user.admin = ,LVAdmin
user.lvintern = lvintern,LVInternal
#user.lvintern@STREAMBASE.COM = ,LVAdmin
user.sb-test = ,LVAdmin
user.sb-test@STREAMBASE.COM = ,LVAdmin
user.jstinton = ,LVAdmin

# Add your users here. Any/all of the password below can be enciphered using the sbcipher 
# utility. 
# Refer to the Enciphered Passwords of the LiveView Server System Configuration document for 
# details.
#user.<name> = <password>,<role1>,<role2>,..
user.guest = guest,LVGuest 
user.guest@STREAMBASE.COM = ,LVGuest
user.tester= tester, LVUser
user.tester@STREAMBASE.COM = ,LVUser

# IMPORTANT: In this sample, the LVAdmin role is used to control the LiveView server
# and the LVInternal role is used to perform internal server functions.
# Removing permissions from these roles can result in the LiveView server not functioning as 
# expected.  

# LiveView role-to-permission mapping
#role.<name> = <permission1>,<permission2>,...
role.LVAdmin = *
role.LVInternal = connect, table:query:*, table:publish:LVAlerts, table:list, table:delete:ItemsSales, 
  table:manage, shutdown

# add more roles, or modify the LVUser role here.
role.LVUser = connect, table:list, table:manage, table:*:ItemsSales, table:query, alert:list, 
  alert:set:ItemsSales, alert:delete, alertaction:publish:ItemsSales, alertaction:email:ItemsSales, 
  alertaction:sendtuple:ItemsSales, tuple:info:ItemsSales.DataIn, tuple:send:ItemsSales.DataIn, 
  workspace:get:Auth Sample, dashboard:create, page:create, card:create, linkage:create

role.LVGuest = connect, table:list, table:manage, table:*:ItemsSales, table:query, alert:list, 
  alert:set:ItemsSales, alert:delete, alertaction:publish:ItemsSales, alertaction:email:ItemsSales, 
  alertaction:sendtuple:ItemsSales, tuple:info:ItemsSales.DataIn, tuple:send:ItemsSales.DataIn, 
  workspace:get:Auth Sample 

Several internal LiveView components are required to make requests to access LiveView server resources. When authentication is enabled, these internal requests must be made in the context of a valid LiveView user name configured with the appropriate permissions. A special role, LVInternal, is available to satisfy this requirement. Two system properties, liveview.internal.username and liveview.internal.password, specify the credentials of the internal LiveView user configured with the LVInternal role. The LiveView Authentication and Authorization Sample sets the internal user's credentials in a StreamBase configuration file, sbd.sbconf. Enciphered Passwords describes how to encipher passwords, including the one for the internal user, for added security.

LiveView uses its own API internally to talk to itself, generating URLs whose host name is by default, localhost. SPNEGO uses HTTP/<serverFQDN>@<REALM> as the Kerberos service principal, and localhost is not a valid server fully qualified domain name. Therefore, two liveview.properties properties must be set for the FQDN.

If LiveView secure communication is enabled, there is already a system property "liveview.ssl.hostname" which is also used for TLS authentication of the server certificate. If that property is set, LiveView uses it for Kerberos. Otherwise, you must use a second system property, liveview.internal.client.hostname which must be set to the value to be used in the outgoing request, and which needs to be set to the FQDN of the LiveView server's Kerberos principal.

Preamble

com.sun.security.jgss.krb5.initiate {
  com.sun.security.auth.module.Krb5LoginModule required
  keyTab="c:/kerberos/ldm-server.keytab"
  principal="sb-test@STREAMBASE.COM"
  doNotPrompt=true
  debug=true
  useTicketCache=true
  useKeyTab=true
  storeKey=true
  renewTGT=true
  isInitiator=true
  proxiable=true
  ;
};

set LIVEVIEW_CLIENT_JVM_ARGS=-Dliveview.internal.client.hostname=qa35.lab.streambase.com 
  -Djava.security.krb5.conf=c:/kerberos/krb5.conf -Djava.security.auth.login.config=c:/kerber
  os/login.conf