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

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:

Although the login.conf and krb5.conf files share the same file extension as the HOCON file type, they are not HOCON-formatted files.

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

You must define two authentication realms as follows:

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

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

name = "localauthrealm"
version = "1.0.0"
type = "com.tibco.ep.dtm.configuration.security"
configuration = {
  LocalAuthenticationRealm = {
    name = "authRealm"
    initialPrincipals = [
      {
        userName = "name"
        password ="password"
        roles = [ "role" ]
      }     
    ]
  }
}

name = "clientApiListener"
type = "com.tibco.ep.ldm.configuration.ldmclientapilistener"
version = "1.0.0"
configuration = {
  ClientAPIListener = {
    authenticationRealmName = "kerbRealm"
    portNumber = 10080
  }
}

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 = {
    privileges = {
      role1 = [
        {
          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
  ;
};

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