Kerberos Authentication Realm

Overview

A Kerberos realm performs Kerberos SSO authentication against one or more Kerberos KDCs. Unlike other realm types, Kerberos realm types are limited by the JVM to be singletons, because the JRE's Kerberos implementation uses JVM system properties for configuration. A given node engine can therefore use only one Kerberos realm. If there are multiple engines on a node, each engine can use a different Kerberos realm.

A Kerberos realm configuration is specified in the KerberosAuthenticationRealm root object of the security configuration type.

The JRE's Kerberos implementation uses file-based configuration. The various Kerberos file properties must exist on the node's file system or the Kerberos configuration does not activate.

Kerberos is only supported via the HTTP SPNEGO protocol; non-HTTP communication is not supported. Kerberos only supports authentication, not authorization. To support authorization a fallback realm must be specified to provide authorization services. Each Kerberos realm configuration must specify 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 fails.

The following Kerberos Key Distribution Centers (KDC) are supported:

  • Apache DS minimum version 2.0.0 M22

  • Red Hat Enterprise Linux Server and CentOS version 7

  • Red Hat Enterprise Linux Server and CentOS version 8

  • Windows Server 2019

The following Kerberos clients are supported:

  • Red Hat Enterprise Linux Server version 7 and 8

  • Windows 7 and 10

Required Properties

kerberosConfigurationFile

The file, typically named 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.

serverKeytabFile

A Kerberos keytab file that contains credentials for the Kerberos server principal name that represents an engine API listener to which clients connect, and for which they request Kerberos tickets.

serverPrincipalName

A Kerberos server principal name that represents an engine API listener to which clients connect, and for which they request Kerberos tickets.

Optional Properties

ticketCacheFile

The location of a Kerberos ticket cache file, defaulting to a system-specific location determined by the JRE's Kerberos implementation.

jaasDebug

Enable and disable JAAS debugging.

internalClientKeytabFile

A keytab file used for internal client credentials, used during internal client ticket procuring. If none is specified, the server keytab file is used. Internal credentials are needed by engines making client connections to themselves or to other engines in a node.

internalClientPrincipalName

The Kerberos principal name of the client requesting tickets for the serverPrincipalName's service. If not specified, an internal client JAAS login configuration file must be specified.

internalClientLoginConfigurationFile

A 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 generates a login file using that principal and either the client keytab file, or the server keytab file if no client keytab file was specified.

Configuration of Kerberos Authentication Realm

The KerberosAuthenticationRealm root configuration object defines Kerberos authentication for a node. There can only be a single KerberosAuthenticationRealm defined on a node.

Warning

Kerberos requires the local machine to be identified by a fully qualified domain name (FQDN). Ensure that the local machine is set up to use a FQDN, instead of a simple host name, by default. If that is not possible, ensure that the FQDN of the local machine is configured in the Administration.address property of the node deployment configuration (see Administration). For example:

name = "my.application"
version = "1.0.0"
type = "com.tibco.ep.dtm.configuration.node"
configuration =
{
    NodeDeploy =
    {
        nodes = 
        {
            "A.X" =
            {
                communication =
                {
                    administration =
                    {
                        address = "myhost.com" // FQDN
                        webServiceBindings =
                        {
                            admin =
                            {
                                authenticationRealmName = "kerberos-realm"
                            }
                        }
                    }
                }
            } 
        }
    }
}

Figure 1, “KerberosAuthenticationRealm relationships” shows the relationships to other configuration objects.

KerberosAuthenticationRealm relationships

KerberosAuthenticationRealm relationships

A detailed description of the configuration object properties is in KerberosAuthenticationRealm object properties and a snippet for these properties is in Example 1, “KerberosAuthenticationRealm object snippet”.

KerberosAuthenticationRealm object properties

Name Type Description
fallbackAuthenticationRealmName String The name of the realm used for all authorization. This must be the name of an active LDAPAuthenticationRealm or LocalAuthenticationRealm. If the fallback realm is not defined, configuration activation will fail. Required.
internalClientLoginConfigurationFile String The Java Authentication and Authorization Service (JAAS) login configuration file that configures internal client use of Kerberos. If specified, file must be valid on the machine where the node is running. If not specified, then the internalClientPrincipalName configuration property must be specified. A login file will be generated using that principal and the internalClientKeytabFile if specified, or the serverKeytabFile if internalClientKeytabFile is not specified. Optional. No default value.
internalClientKeytabFile String The internal client Kerberos keytab file name, used for internal client login without kinit. The file must be valid on the machine where the node is running. Optional. Default value is the value of the serverKeytabFile configuration property.
internalClientPrincipalName String The internal client Kerberos principal name specified as <user-name>@<fully-qualified-domain-name>, as it is known to the Kerberos Key Distribution Center (KDC) specified in the Kerberos system configuration file. If not specified, then an internal client JAAS login configuration file containing a principal name must be specified in internalClientLoginConfigurationFile. Optional. No default.
jaasDebug Boolean The JAAS debugging flag. Set to true to enable JAAS debug logging, false to disable. Optional. Default value is false.
kerberosConfigurationFile String The location of the Kerberos system configuration file, specifying among other things the location of the KDC. This file must be valid on the machine where the node is running. Required.
name String Name of the authentication realm. This name must be unique across all authentication realms. Required.
requireTrustedHostMembership Boolean A value of true only allows users to connect from a trusted host, a value of false allows users to connect from any host. Optional. Default value is false.
serverKeytabFile String The server Kerberos keytab file name, used for principal login without kinit. This file must be valid on the machine where the node is running. Required.
serverPrincipalName String The server Kerberos principal name, as it is known to the KDC specified in the Kerberos system configuration file. The fully qualified domain name must be used when specifying the machine name. Required.
ticketCacheFile String The location of a Kerberos ticket cache file. The file must be valid on the machine where the node is running. Optional. Default is a system default location.

Example 1. KerberosAuthenticationRealm object snippet

name = "kerberos-authentication-realm"
version = "1.0.0"
type = "com.tibco.ep.dtm.configuration.security"
configuration =
{
    KerberosAuthenticationRealm =
    {
        name = "my-kerberos-authentication-realm"
        requireTrustedHostMembership = false
        fallbackAuthenticationRealmName = "my-local-realm"
        internalClientLoginConfigurationFile = "/opt/kerberos/client-configuration"
        internalClientKeytabFile = "/opt/kerberos/keytab/client"
        internalClientPrincipalName = "client-principal@ACME.COM"
        jaasDebug = false
        kerberosConfigurationFile = "/opt/kerberos/kerberos-configuration"
        serverKeytabFile = "/opt/kerberos/keytab/server"
        serverPrincipalName = "HTTP/my.host.com@ACME.COM"
        ticketCacheFile = "/opt/kerberos/ticket/cache/file"
    }
}