Contents
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:
-
Spotfire LiveView Web
-
LiveView REST API
Kerberos is a network authentication protocol for client-server applications. Kerberos is only supported via the HTTP SPNEGO protocol; non-HTTP communication is not supported. Kerberos only supports authentication and not authorization. Each Kerberos realm configuration specifies a fallback realm that is used for all authorization, and for authentication from clients that are not using SPNEGO over HTTP. That fallback realm must exist when the Kerberos realm is activated or activation will fail.
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.
Note
A given node can have only one active Kerberos authentication realm. This is a restriction unique to Kerberos; you can have as many local, LDAP, or OIDC realms as you want.
StreamBase Studio provides a HOCON Editor, from which you can select a template of type c.t.e.d.c.security.KerberosAuthenticationRealm
as the basis for building your Kerberos configuration in your LiveView application. See HOCON Configuration File Editor for instructions on using the Editor.
To configure Kerberos Single Sign-on with SPNEGO, you need the following files:
- 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 keytab files:
- Server Keytab File
-
The required server keytab file is for the server listener’s use and allows the server to handshake with Kerberos. The server keytab must contain an entry for
HTTP/<your-host-name-FQDN>@<realm>
. The HOCON configuration file of typec.t.e.d.c.security.KerberosAuthenticationRealm
must include aserverKeytabFile
property to specify the server keytab file. - Internal Client Keytab File
-
The optional client keytab file is used for internal client connections if no
internalClientLoginConfigurationFile
property is specified in theKerberosAuthenticationRealm
configuration file. If the client keytab file is present, it 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.
- login.conf
-
Java Authentication and Authorization Service (JAAS) configuration file. Depending on how JAAS login configuration is set up, the client can either use keytab files (since the LiveView server is an unattended application, for example), or the kinit command (if user-controlled).
Spotfire supports
login.conf
for customers with very specific configuration requirements, but it is not the preferred option. Instead, it is a best practice providing aninternalClientPrincipalName
and optionalinternalClientKeytabFile
property, which are used to generate a temporarylogin.conf
. Use ofinternalClientPrincipalName
is exclusive with use of an internalClientLoginConfigurationFile. - com.tibco.ep.dtm.configuration.security
-
A HOCON security configuration file. Include a security file for each security root object shown below. Alternatively, you can include multiple security root objects into one security file:
-
Kerberos authentication realm
-
LDAP authentication realm or local authentication realm (the fallback realm)
-
RoleToPrivilegeMappings
-
- com.tibco.ep.ldm.configuration.ldminternalcredentials
-
A credential file of type HOCON that specifies the credentials of the internal LiveView user configured with the
LVInternal
role. - com.tibco.ep.streambase.configuration.ldmclientapilistener
-
A HOCON configuration file used to define the authentication realm to use for your clients.
Although the login.conf
and krb5.conf
files share the same file extension as the HOCON file type, they are not HOCON-formatted files.
Some Kerberos configurations require the client and server perform JAAS authentication, while others relax this requirement
to obtain necessary credentials. If your organization's Kerberos environment uses the relaxed requirements, you must set javax.security.auth.useSubjectCredsOnly=false
in the engines system property configuration section.
For more on JAAS authentication, see JAAS Authentication page.
For a tutorial on using javax.security.auth.useSubjectCredsOnly
, see Overview of the Client and Server Applications page.
Place the files used in this configuration in the following folder locations:
-
Place all HOCON configuration files (
security
,ldmcredentials
, and so on) in your LiveView project'ssrc/main/configurations
folder.The Kerberos-specific configuration files MUST be placed on the destination node’s machine BEFORE any Kerberos realm configuration is loaded. The system's validation process will test that the files exist.
-
Place the additional files (
krb5.conf
,login.conf
,*.keytab
, and so on) anywhere on the local machine as any configurations that require them can point to a full system path.A keytab is analogous to a user's password. It is a best practice that you store keytab files on the target node file system, and make them readable only by the root user per local practice.
You must define two authentication realms as follows:
-
One Kerberos authentication realm, which among other things defines authentication for SPNEGO.
-
One fallback authentication realm (LDAP or local authentication realm) to provide non-SPNEGO authentication as well as all authorization.
This example defines a Kerberos authentication realm called kerbrealm
using the minimum required properties.
Replace the values with your site-specific values. For details regarding all supported Kerberos properties, see Kerberos Authentication Realm.
name = "kerbrealm" version = "1.0.0" type = "com.tibco.ep.dtm.configuration.security" configuration = { KerberosAuthenticationRealm = { name = "my-realm" fallbackAuthenticationRealmName = "my-ldap-realm" kerberosConfigurationFile = "/a/kerberos/config/file" serverKeytabFile = "/a/keytab/file" serverPrincipalName = "HTTP/my.host.com@example.COM" } }
- KerberosAuthenticationRealm.kerberosConfigurationFile
-
The file, typically called krb5.conf is in a format defined by the MIT Kerberos implementation, and defines the Kerberos realm, KDC ports, and realm-to-DNS-domain bindings.
- KerberosAuthenticationRealm.serverKeytabFile
-
A Kerberos keytab file containing credentials for the Kerberos server principal name that represents an engine API listener to which clients connect, and for which they request Kerberos tickets.
- KerberosAuthenticationRealm.serverPrincipalName
-
A Kerberos server principal name that represents an engine API listener to which clients connect, and for which they request Kerberos tickets.
- KerberosAuthenticationRealm.fallbackAuthenticationRealmName
-
Kerberos realms perform SPNEGO authentication only. This property specifies the name of the (must be LDAP or local authentication) realm used for non-SPNEGO authentication and for all authorization.
- KerberosAuthenticationRealm.ticketCacheFile
-
The location of a Kerberos ticket cache file, defaulting to a system-specific location determined by the JRE's Kerberos implementation.
- KerberosAuthenticationRealm.jaasDebug
-
Enables and disables JAAS debugging.
- KerberosAuthenticationRealm.internalClientKeytabFile
-
A keytab file used for internal client (engines making client connections to themselves or other engines) credentials, used during internal client ticket procuring. If none specified, the server keytab file is used.
- KerberosAuthenticationRealm.internalClientPrincipalName
-
The Kerberos principal name of the client requesting tickets for the
serverPrincipalName's
service. If not specified, then an internal client JAAS login configuration file must be specified. If used, this property is preferred over theinternalClientLoginConfigurationFile
property. - KerberosAuthenticationRealm.internalClientLoginConfigurationFile
-
The JAAS login file that configures internal client use of Kerberos. If no file is specified, then an internal client principal name must be specified, and the realm will generate a login file using that principal and either the client keytab file, or the server keytab file if no client keytab file was specified.
One fallback authentication realm is also required for Kerberos authentication realm configuration. When a fallback authentication is enabled in a HOCON security configuration file of type security, a LiveView client can identify itself to the server with a username and password. The Kerberos realm uses the fallback realm for authorization, and for authentication in cases where incoming requests are not HTTP.
Configure the fallback authentication credentials in one of the following supported realms. The fallback realm name you define
in the Kerberos security HOCON file's fallbackAuthenticationRealmName
property must match the name used in the fallback authentication realm below.
For details regarding each of the following two supported fallback realm's properties, see:
LDAP Authentication Realm Example
name = "ldaprealm" version = "1.0.0" type = "com.tibco.ep.dtm.configuration.security" configuration = { LDAPAuthenticationRealm = { name = "my-ldap-realm" servers = [ { systemPrincipal = "CN=lvintern,OU=Users,dc=example,dc=com" systemPassword = "lvintern" principalSearchRoots = [ "OU=Users,DC=example,DC=com", ] principalSearchFilter="cn={0}" roleSearchFilter = "roleOccupant={1}" } ] } }
Local Authentication Realm Example
name = "localauthrealm" version = "1.0.0" type = "com.tibco.ep.dtm.configuration.security" configuration = { LocalAuthenticationRealm = { name = "authRealm" initialPrincipals = [ { userName = "name" password ="password" roles = [ "role" ] } ] } }
The following is an ldmclientapilistener.conf
example, which includes settings for a LiveView engine's client API listener. For details regarding its properties, see LiveView Client API Listener Configuration.
The authenticationRealmName
value must match the KerberosAuthenticationRealm.name
value from the com.tibco.ep.dtm.configuration.security
HOCON file.
name = "clientApiListener" type = "com.tibco.ep.ldm.configuration.ldmclientapilistener" version = "1.0.0" configuration = { ClientAPIListener = { authenticationRealmName = "kerbRealm" portNumber = 11080 } }
Each LiveView user can have one or more roles, which are sets of privileges mapped to them in a HOCON configuration file of
type com.tibco.ep.dtm.configuration.security
. For details on each property used in this configuration file type, see Role to Privilege Mappings.
LiveView Privilege Settings shows a list of available privileges and how they are mapped to LiveView user roles.
Roles and mappings set in the file apply to any authentication realm that LiveView supports, including the Kerberos authentication realm.
See the LiveView Authentication sample's role.Mappings.conf
file, located in the sample project's src/main/configurations
for additional examples of LiveView user role-to-mapping configurations.
LiveView Roles and Mappings example:
name = "my-role-mappings" version = "1.0.0" type = "com.tibco.ep.dtm.configuration.security" configuration = { RoleToPrivilegeMappings = { roles = { role1 = { privileges = [ { privilege = "privilege_example" } ] } } } }
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. Configure a file of HOCON type com.tibco.ep.ldm.configuration.ldminternalcredentials
to specify the credentials of the internal LiveView user configured with the LVInternal
role. This defines a Kerberos principal that can be used rather than a local user.
See LiveView Internal Credentials Configuration for its security settings details.
name = "my-internal-credentials" type = "com.tibco.ep.ldm.configuration.ldminternalcredentials" version = "1.0.0" configuration = { InternalCredentials = { ldmInternalUserName = "kerbuser" ldmInternalRequestHostName = "example.com" } }
The following describes the configuration requirements for enabling Kerberos for LiveView clients.
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 ldmengine.conf
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 the Kerberos fallback realm 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.
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.
Typically in an enterprise, you would log in using Active Directory. In such cases, your operating system would automatically resolve Kerberos-Single Sign-on negotiation. This section shows how to use MIT Kerberos to log in instead.
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 Kerberos authentication
file. You cannot use LiveView Web's default, http://localhost:11080
. Use, for example: http://lvserv.example.com:11080
.
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:11080
.
-
- 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:11080
.
-
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 Properties 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:11080
.
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:11080
.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:11080
.
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.
An ldmengine
configuration file is not strictly required for Kerberos configuration. However, if used, you can include system properties
for Kerberos-related debugging, as needed. The following example includes the syntax for two such properties and is not intended
to an exhaustive list of Kerberos debugging properties:
name = "myldmengine"
version = "1.0.0"
type = "com.tibco.ep.ldm.configuration.ldmengine"
configuration = {
LDMEngine = {
systemProperties = {
"sun.security.krb5.debug" = "true"
"sun.security.spnego.debug" = "true"
}
}
}