Version: 6.0-SNAPSHOT

Enterprise Edition

Kerberos Authentication

The Kerberos authentication protocol is one of the standard solutions for single sign-on (SSO). Hazelcast supports Kerberos authentication as an Enterprise Edition feature and also provides Kerberos integration to LDAP-based authorizations.

The Kerberos support in Hazelcast has 2 configuration parts: identity and authentication. The identity part is responsible for retrieving the service ticket from Kerberos KDC (Key Distribution Center). The authentication part verifies the service tickets.

Default Service principal names for Hazelcast members are in the form hz/address@REALM, for example hz/[email protected].

Before a service ticket is issued, the client side of the connection has to be authenticated, which means the TGT (Ticket Granting Ticket) is present in the Subject.

Simplified Kerberos configuration

Both Hazelcast kerberos identity, and kerberos authentication delegate the ticket related tasks (such as TGT retrieval) to vendor-specific Krb5LoginModule implementations. It normally uses the com.sun.security.auth.module.Krb5LoginModule class. The security-ream property in kerberos configurations allows referencing another realm with Krb5LoginModule configured.

To simplify the Kerberos configuration process for new users, Hazelcast allows skipping Krb5LoginModule JAAS configuration within separate security realms. Instead, it's possible to define the principal and keytab-file options in the kerberos identity and authentication configurations. If these options are used instead of the security-realm, then a new temporary realm is generated on the fly during authentication.

XML
YAML

xml
<hz:realm name="simpleKerberosRealm">
    <hz:authentication>
        <hz:kerberos>
            <hz:principal>hz/[email protected]</hz:principal>
            <hz:keytab-file>/opt/localhost.keytab</hz:keytab-file>
        </hz:kerberos>
    </hz:authentication>
    <hz:identity>
        <hz:kerberos>
            <hz:realm>HAZELCAST.COM</hz:realm>
            <hz:principal>hz/[email protected]</hz:principal>
            <hz:keytab-file>/opt/localhost.keytab</hz:keytab-file>
        </hz:kerberos>
    </hz:identity>
</hz:realm>

yaml
    realms:
      - name: simpleKerberosRealm
        authentication:
          kerberos:
            principal: hz/[email protected]
            keytab-file: /opt/localhost.keytab
        identity:
          kerberos:
            realm: HAZELCAST.COM
            principal: hz/[email protected]
            keytab-file: /opt/localhost.keytab

A warning is logged during the first use of the simplified configuration form. It includes the generated configuration, so you can use it as a starting point to define the full Kerberos configuration. An example warning log is shown below:

12:37:41,187  WARN [KerberosCredentialsFactory] Using generated Kerberos initiator
realm configuration is not intended for production use. It's recommended
to properly configure the Krb5LoginModule manually to fit your needs.
Following configuration was generated from provided keytab and principal properties:
<realm name="krb5Initiator">
  <authentication>
    <jaas>
      <login-module class-name="com.sun.security.auth.module.Krb5LoginModule" usage="REQUIRED">
        <properties>
          <property name="isInitiator">true</property>
          <property name="useKeyTab">true</property>
          <property name="refreshKrb5Config">true</property>
          <property name="doNotPrompt">true</property>
          <property name="storeKey">true</property>
          <property name="keyTab">/opt/localhost.keytab</property>
          <property name="principal">hz/[email protected]</property>
        </properties>
      </login-module>
    </jaas>
  </authentication>
</realm>

Identity configuration

The full Kerberos identity configuration references a security realm with Krb5LoginModule configured as an initiator:

Sample Kerberos Identity Configuration XML
YAML

xml
<realm name="kerberosRealm">
    <identity>
        <kerberos>
            <realm>ACME.COM</realm>
            <security-realm>krb5Initiator</security-realm>
        </kerberos>
    </identity>
</realm>
<realm name="krb5Initiator">
    <authentication>
        <jaas>
            <login-module class-name="com.sun.security.auth.module.Krb5LoginModule" usage="REQUIRED">
                <properties>
                    <property name="useTicketCache">true</property>
                    <property name="doNotPrompt">true</property>
                </properties>
            </login-module>
        </jaas>
    </authentication>
</realm>

yaml
  realms:
    - name: kerberosRealm
        identity:
          kerberos:
            realm: ACME.COM
            security-realm: krb5Initiator
    - name: krb5Initiator
        authentication:
          jaas:
            class-name: com.sun.security.auth.module.Krb5LoginModule
              properties:
                useTicketCache: true
                doNotPrompt: true

The <kerberos> identity configuration has the following properties:

Property name	Default value	Description
`spn`		Allows configuring static Service Principal Name (SPN). It's meant for use cases where all the members share a single Kerberos identity.
`service-name-prefix`	`"hz/"`	Defines the prefix of SPN. By default the member's principal name (for which this credentials factory asks the service ticket) is in the form `"[servicePrefix][memberIpAddress]@[REALM]"`, e.g., `"hz/192.168.1.1@ACME.COM"`.
`realm`		Kerberos realm name, e.g., `"ACME.COM"`.
`security-realm`		Security realm name in the Hazelcast configuration used for Kerberos authentication. The authentication configuration in the referenced security realm will be used to fill the Subject with the Kerberos credentials, e.g. TGT.
`use-canonical-hostname`	`false`	Flag which controls if canonical hostnames should be used instead of IP addresses in generated Service Principal names. This property is only used when the Service Principal name is not static, i.e. when `spn` option isn't configured).
`principal`		Kerberos principal name. This is a helper option which can be used together with the `keytab-file` to replace the `security-realm` configuration. We don't recommend using this property in production!
`keytab-file`		Path to a keytab file with the current principal's secrets. This is a helper option which can be used together with the `principal` to replace the `security-realm` configuration. We don't recommend using this property in production!

Kerberos authentication

The authenticating part on the server side is able to accept Kerberos tickets and verify them. The Kerberos authentication is delegated to another realm with the Kerberos login module configured.

XML
YAML

xml
<realm name="kerberosRealm">
    <authentication>
        <kerberos>
            <security-realm>krb5Acceptor</security-realm>
        </kerberos>
    </authentication>
</realm>
<realm name="krb5Acceptor">
    <authentication>
        <jaas>
            <login-module class-name="com.sun.security.auth.module.Krb5LoginModule" usage="REQUIRED">
                <properties>
                    <property name="isInitiator">false</property>
                    <property name="useTicketCache">false</property>
                    <property name="doNotPrompt">true</property>
                    <property name="useKeyTab">true</property>
                    <property name="storeKey">true</property>
                    <property name="principal">hz/[email protected]</property>
                    <property name="keyTab">/opt/member1.keytab</property>
                </properties>
            </login-module>
        </jaas>
    </authentication>
</realm>

yaml
    realms:
      name: kerberosRealm
        authentication:
          kerberos:
            security-realm: krb5Acceptor
      name: krb5Acceptor
        authentication:
          jaas:
            - class-name: com.sun.security.auth.module.Krb5LoginModule
              usage: REQUIRED
              properties:
                isInitiator: false
                useTicketCache: false
                doNotPrompt: true
                useKeyTab: true
                storeKey: true
                principal: hz/[email protected]
                keyTab: /opt/member1.keytab

The krb5Acceptor realm configuration in the snippet only loads the Kerberos secrets from a keytab file and it doesn't authenticate against a KDC.

Property name	Default value	Description
`relax-flags-check`	`false`	Allows disabling some of the checks on the incoming token, e.g. passes authentication even if the mutual authentication is required by the token.
`use-name-without-realm`	`false`	When set to `true`, then the Kerberos realm part is removed from the authenticated name, e.g. `"jduke@ACME.COM"` becomes just `"jduke"`.
`security-realm`		Security realm name in the Hazelcast configuration used for Kerberos authentication. The authentication configuration in the referenced security realm will be used to fill the Subject with the Kerberos credentials, e.g. Keytab.
`principal`		Kerberos principal name. This is a helper option which can be used together with the `keytab-file` to replace the `security-realm` configuration. We don't recommend using this property in production!
`keytab-file`		Path to a keytab file with the current principal's secrets. This is a helper option which can be used together with the `principal` to replace the `security-realm` configuration. We don't recommend using this property in production!

The GssApiLoginModule (implementing Kerberos authentication) derives from the abstract ClusterLoginModule. As a result the <kerberos> configuration supports the common options, too: skip-identity, skip-endpoint and skip-role.

note

Kerberos authentication in Hazelcast is only able to validate connections on the server side. It doesn't support mutual authentication.
The Generic Security Services API (GSS-API) isn't used for protecting (wrapping) the messages after authentication, e.g. encryption, integrity checks. It's only used for accepting tokens.
The token itself is not protected against Man-in-the-Middle (MITM) attacks. If an attacker is able to eavesdrop the token and use it before the original sender, then the attacker succeeds with the authentication but the original sender won't.
- There is a replay protection in Java which caches the already used tokens.
- Java Kerberos implementation accepts the token for 5 minutes (by default) from its creation.
Time has to be synchronized on machines where Kerberos is used.

If you are running Hazelcast in an untrusted network with a MITM attack risk, then enable encryption on Hazelcast protocols to prevent stealing the token.

Kerberos and LDAP integration

Kerberos authentication allows loading role mapping information from an LDAP server (usually the one backing the Kerberos KDC server, too). Therefore, the <ldap> authentication configuration is also available as a sub-configuration of <kerberos> authentication.

Sample Kerberos Identity Configuration XML
YAML

xml
<realm name="kerberosRealm">
    <authentication>
        <kerberos>
            <skip-role>true</skip-role>
            <security-realm>krb5Acceptor</security-realm>
            <ldap>
                <url>ldap://ldap.hazelcast.com</url>
                <system-authentication>GSSAPI</system-authentication>
                <role-mapping-attribute>memberOf</role-mapping-attribute>
                <security-realm>krb5Initiator</security-realm>
                <user-filter>(krb5PrincipalName=\{login})</user-filter>
                <skip-authentication>true</skip-authentication>
            </ldap>
        </kerberos>
    </authentication>
</realm>

yaml
    realms:
      - name: kerberosRealm
        authentication:
          kerberos:
            skip-role: true
            security-realm: krb5Acceptor
            ldap:
              url: ldap://ldap.hazelcast.com
              system-authentication: GSSAPI
              security-realm: krb5Initiator
              skip-authentication: true
              user-filter: "(krb5PrincipalName=\{login})"
              role-mapping-attribute: memberOf

note

The Kerberos LDAP integration doesn't support credential delegation, i.e. reusing client tickets for accessing the LDAP. It only allows using the member's Kerberos credentials to authenticate into LDAP.

Troubleshooting

Usually Krb5LoginModule implementations provided by JVMs have a debug option allowing you to print details related to authentication. Please refer your JVM documentation to find more details or see Security debugging to find out how to increase debug output for Kerberos in your JVM.

canceled

Simplified Kerberos configuration​

Identity configuration​

Kerberos authentication​

Kerberos and LDAP integration​

Troubleshooting​

Simplified Kerberos configuration

Identity configuration

Kerberos authentication

Kerberos and LDAP integration

Troubleshooting