Identity configuration

Identity configuration enables you to define your own credentials, which are are used to authenticate to other systems.

The following identity configuration types are available:

  • username-password: defines a new PasswordCredentials object

  • token: defines a new TokenCredentials object

  • kerberos: defines the Kerberos identity that uses the service tickets stored in the TokenCredentials object

  • credentials-factory: configures the factory class which creates the Credentials objects

Username-Password identity

The username with password is the most typical type of credentials. This is configured by the <username-password/> XML configuration element as shown below:

  • XML

  • YAML

  • Java

        <realms>
            <realm name="passwordRealm">
                <identity>
                    <username-password username="member1" password="s3crEt" />
                </identity>
            </realm>
        </realms>
        <member-authentication realm="passwordRealm" />
realms:
  name: passwordRealm
    identity:
      username-password:
        username: member1
        password: s3crEt
member-authentication:
  realm: passwordRealm
        RealmConfig realmConfig = new RealmConfig()
                .setUsernamePasswordIdentityConfig("member1", "s3crEt");
        config.getSecurityConfig().setMemberRealmConfig("passwordRealm", realmConfig);

Token identity

Tokens are also configurable for identity representation. The <token/> XML configuration element supports either plain ASCII tokens or Base64 encoded values. The optional encoding argument can have either base64 or none (default) as its value.

The following two realms define the same token value - bytes of the "Hazelcast" string:

  • XML

  • YAML

  • Java

            <realm name="tokenRealm1">
                <identity>
                    <token>Hazelcast</token>
                </identity>
            </realm>
            <realm name="tokenRealm2">
                <identity>
                    <token encoding="base64">SGF6ZWxjYXN0</token>
                </identity>
            </realm>
realms:
  - name: tokenRealm1
      identity:
        token:
          value: Hazelcast
  - name: tokenRealm2
      identity:
        token:
          encoding: base64
          value: SGF6ZWxjYXN0
        TokenIdentityConfig tokenConfig = new TokenIdentityConfig("Hazelcast".getBytes(StandardCharsets.US_ASCII));
        RealmConfig realmConfig = new RealmConfig().setTokenIdentityConfig(tokenConfig);

Hazelcast doesn’t provide an authentication type with direct token identity support. Tokens are usually used together with custom JAAS login modules.

Kerberos identity

The kerberos identity type is used to retrieve Kerberos service tickets to access a member using the kerberos authentication type. For more information on the kerberos identity, see Kerberos authentication.

Credentials factory

The most flexible way to define an identity is via Credentials objects created by a custom credential factory. This is an implementation of the com.hazelcast.security.ICredentialsFactory interface. The newCredentials() method provides the credentials.

The XML configuration uses the <credentials-factory> element to define the factory class.

The behavior of credential factories can be controlled by specifying factory properties. The properties are provided in the init(Properties) method.

See the following sample configuration:

  • XML

  • YAML

            <realm name="credentialsFactoryRealm">
                <identity>
                    <credentials-factory class-name="com.examples.TOTPCredentialsFactory">
                        <properties>
                            <property name="seed">3132333435363738393031323334353637383930</property>
                        </properties>
                    </credentials-factory>
                </identity>
            </realm>
realms:
  name: credentialsFactoryRealm
    identity:
      credentials-factory:
        class-name: com.examples.TOTPCredentialsFactory
        properties:
          seed: 3132333435363738393031323334353637383930

Credentials

One of the key elements in Hazelcast security is the Credentials object, which represents evidence of the identity (member or client). The content of Credentials object is verified during the authentication. Credentials is an interface which extends Serializable.

public interface Credentials extends Serializable {
    String getName();
}

There are two subtype interfaces which simplify Credentials usage. The subtypes reflect data provided in the client authentication messages:

  • Name and password (com.hazelcast.security.PasswordCredentials)

  • Byte array token (com.hazelcast.security.TokenCredentials)

The interfaces have the following forms:

public interface PasswordCredentials extends Credentials {
    String getPassword();
}
public interface TokenCredentials extends Credentials {
  byte[] getToken();

  default Data asData() {
      return new HeapData(getToken());
  }
}

The Credentials instance can be retrieved in the login modules by handling a CredentialsCallback, as shown below:

            CredentialsCallback credcb = new CredentialsCallback();
            try {
                callbackHandler.handle(new Callback[] { credcb });
            } catch (IOException | UnsupportedCallbackException e) {
                throw new LoginException("Unable to retrieve credetials");
            }
            Credentials credentials = credcb.getCredentials();
            if (credentials instanceof PasswordCredentials) {
                PasswordCredentials passwordCredentials = (PasswordCredentials) credentials;
                if (expectedName.equals(credentials.getName())
                        && expectedPassword.equals(passwordCredentials.getPassword())) {
                    name = credentials.getName();
                    addRole(name);
                    return true;
                }
            }
            throw new FailedLoginException("Credentials verification failed.");