LiveView Authentication and Authorization for Kerberos

Introduction

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.

Required Server Configuration Files

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 type c.t.e.d.c.security.KerberosAuthenticationRealm must include a serverKeytabFile 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 the KerberosAuthenticationRealm configuration file. If the client keytab file is present, it 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.

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 an internalClientPrincipalName and optional internalClientKeytabFile property, which are used to generate a temporary login.conf. Use of internalClientPrincipalName 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.

File Locations

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's src/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.

Realm Configuration

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.

Kerberos Authentication Realm

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

Required Properties

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.

Optional Properties

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 the internalClientLoginConfigurationFile 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.

Fallback Authentication Realm

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" ]
      }     
    ]
  }
}

API Listener Configuration for the Kerberos Authentication Realm

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

LiveView Roles and Mappings

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"
     } 
 ]
 } 
 }
 }
}

Internal LiveView User and Role

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

Client-Server Communication Scenarios

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.

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.

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.

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:11080.

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:11080.

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 Properties 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 Authentication>Logon. 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:11080.

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 Authentication>Logon. 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: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.

  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:11080.

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.

Kerberos Authentication Realm Debugging

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