Contents
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.
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.
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 inliveview.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
, whereyour-internal-client-name
@realm
realm
is defined in thekrb5.conf
file. - krb5.conf
-
This file configures the LiveView server’s use of Kerberos, and among other things, identifies the KDC to use.
Place the configuration files in the following locations:
-
Place the
liveview.properties
,liveview.auth.properties
, andsbd.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.
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
-
JAAS ignores the
liveview.security.auth.spnego.server.principal
property in theliveview.properties
file if thesun.security.krb5.principal
system property is set in thesbd.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 thesbd.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.
-
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.
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.
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>
-
If the internal client principal name is not set in the
liveview.properties
file, then thejava.security.auth.login.config
system property must be set in thesbd.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 insbd.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
andjava.security.auth.login.config
system properties. -
The
sun.security.spnego.debug
property is optional.
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.
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
.
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).
-
Open Firefox and enter
about:config
in the address field. -
Accept the warning.
-
In the Search field, filter the results by typing
negotiate
. -
Update the following two properties:
Name = network.negotiate-auth.delegation-uris Value =
example.com
Name = network.negotiate-auth.trusted-uris Value =
example.com
-
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):
-
Open Firefox and enter
about:config
in the address field. -
Accept the warning.
-
In the Search field, filter the results by typing
negotiate
. -
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
-
In the Search field, filter the results by typing
sspi
. -
Update the following property:
Name = network.auth.use-sspi Value = false
-
No browser restart should be required. Navigate to your LiveView Web URL. For example,
http://lvserv.example.com:10080
.
-
Chrome inherits security settings from the system's Internet Properties dialog.
-
Open the Control Panel (Windows 7) or search for "Control Panel" using Windows 10 Start.
-
In the Control Panel's search search field, type:
internet
. -
Click the Internet Options heading.
-
This opens the Internet Options dialog.
-
Select the Security Tab.
-
Select the Local intranet zone.
-
Click
. -
Click
. -
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
. -
Close dialogs back to the Security tab.
-
In the Security level for this zone section, click .
-
At the bottom of the list of Settings there is a section called → . Make sure is selected.
-
Close all instances of Internet Explorer, Chrome, and (on Windows 10) Edge.
-
Open Chrome and navigate to your LiveView Web URL:
http://lvserv.example.com:10080
.
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.
-
Open the Control Panel (Windows 7) or search for "Control Panel" using Windows 10 Start.
-
In the Control Panel's search search field, type:
internet
. -
Click the Internet Options heading.
-
This opens the Internet Options dialog.
-
Select the Security Tab.
-
Select the Local intranet zone.
-
Click
. -
Click
. -
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
. -
Close dialogs back to the Security tab.
-
In the Security level for this zone section, click .
-
At the bottom of the list of Settings there is a section called → . Make sure is selected.
-
Close all instances of Edge, Internet Explorer, and Chrome.
-
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. -
Open a command prompt as Administrator (this requires elevated privileges).
-
Execute the following command to exempt the Edge browser from the loopback restriction:
CheckNetIsolation LoopbackExempt -a -n="Microsoft.MicrosoftEdge_8wekyb3d8bbwe"
-
Open Edge and navigate to your localhost LiveView Web URL:
http://localhost:10080
.