Package com.hivemq.client.mqtt.mqtt5.auth

Interface Mqtt5EnhancedAuthMechanism

public interface Mqtt5EnhancedAuthMechanism

Interface for enhanced authentication and/or authorization (auth) mechanisms.

An enhanced auth mechanism object can be shared by different clients only if it does not store state and is thread-safe.

The enhanced auth has two life cycles:

• Auth when connecting:
  1. onAuth(com.hivemq.client.mqtt.mqtt5.Mqtt5ClientConfig, com.hivemq.client.mqtt.mqtt5.message.connect.Mqtt5Connect, com.hivemq.client.mqtt.mqtt5.message.auth.Mqtt5EnhancedAuthBuilder)
  2. (onContinue(com.hivemq.client.mqtt.mqtt5.Mqtt5ClientConfig, com.hivemq.client.mqtt.mqtt5.message.auth.Mqtt5Auth, com.hivemq.client.mqtt.mqtt5.message.auth.Mqtt5AuthBuilder))*
  3. (onAuthSuccess(com.hivemq.client.mqtt.mqtt5.Mqtt5ClientConfig, com.hivemq.client.mqtt.mqtt5.message.connect.connack.Mqtt5ConnAck) | onAuthRejected(com.hivemq.client.mqtt.mqtt5.Mqtt5ClientConfig, com.hivemq.client.mqtt.mqtt5.message.connect.connack.Mqtt5ConnAck) | onAuthError(com.hivemq.client.mqtt.mqtt5.Mqtt5ClientConfig, java.lang.Throwable))
• Reauth when connected:
  1. (onReAuth(com.hivemq.client.mqtt.mqtt5.Mqtt5ClientConfig, com.hivemq.client.mqtt.mqtt5.message.auth.Mqtt5AuthBuilder) | onServerReAuth(com.hivemq.client.mqtt.mqtt5.Mqtt5ClientConfig, com.hivemq.client.mqtt.mqtt5.message.auth.Mqtt5Auth, com.hivemq.client.mqtt.mqtt5.message.auth.Mqtt5AuthBuilder))
  2. (onContinue(com.hivemq.client.mqtt.mqtt5.Mqtt5ClientConfig, com.hivemq.client.mqtt.mqtt5.message.auth.Mqtt5Auth, com.hivemq.client.mqtt.mqtt5.message.auth.Mqtt5AuthBuilder))*
  3. (onReAuthSuccess(com.hivemq.client.mqtt.mqtt5.Mqtt5ClientConfig, com.hivemq.client.mqtt.mqtt5.message.auth.Mqtt5Auth) | onReAuthRejected(com.hivemq.client.mqtt.mqtt5.Mqtt5ClientConfig, com.hivemq.client.mqtt.mqtt5.message.disconnect.Mqtt5Disconnect) | onReAuthError(com.hivemq.client.mqtt.mqtt5.Mqtt5ClientConfig, java.lang.Throwable))

Since:

1.0

Method Summary

Modifier and Type	Method	Description
@NotNull MqttUtf8String	getMethod()
int	getTimeout()
@NotNull CompletableFuture<Void>	onAuth(@NotNull Mqtt5ClientConfig clientConfig, @NotNull Mqtt5Connect connect, @NotNull Mqtt5EnhancedAuthBuilder authBuilder)	Called when a client connects using this enhanced auth mechanism.
void	onAuthError(@NotNull Mqtt5ClientConfig clientConfig, @NotNull Throwable cause)	Called when an error occurred during auth of a client which used this enhanced auth mechanism during connection.
void	onAuthRejected(@NotNull Mqtt5ClientConfig clientConfig, @NotNull Mqtt5ConnAck connAck)	Called when a server rejected auth of a client which used this enhanced auth mechanism during connection.
@NotNull CompletableFuture<Boolean>	onAuthSuccess(@NotNull Mqtt5ClientConfig clientConfig, @NotNull Mqtt5ConnAck connAck)	Called when a server accepted auth of a client which used this enhanced auth mechanism during connection.
@NotNull CompletableFuture<Boolean>	onContinue(@NotNull Mqtt5ClientConfig clientConfig, @NotNull Mqtt5Auth auth, @NotNull Mqtt5AuthBuilder authBuilder)	Called when a server requires further data for auth from a client which used this enhanced auth mechanism during connection.
@NotNull CompletableFuture<Void>	onReAuth(@NotNull Mqtt5ClientConfig clientConfig, @NotNull Mqtt5AuthBuilder authBuilder)	Called when a client reauthenticates and used this enhanced auth mechanism during connection.
void	onReAuthError(@NotNull Mqtt5ClientConfig clientConfig, @NotNull Throwable cause)	Called when an error occurred during reauth of a client which used this enhanced auth mechanism during connection.
void	onReAuthRejected(@NotNull Mqtt5ClientConfig clientConfig, @NotNull Mqtt5Disconnect disconnect)	Called when a server rejected reauth of a client which used this enhanced auth mechanism during connection.
@NotNull CompletableFuture<Boolean>	onReAuthSuccess(@NotNull Mqtt5ClientConfig clientConfig, @NotNull Mqtt5Auth auth)	Called when a server accepted reauth of a client which used this enhanced auth mechanism during connection.
default @NotNull CompletableFuture<Boolean>	onServerReAuth(@NotNull Mqtt5ClientConfig clientConfig, @NotNull Mqtt5Auth auth, @NotNull Mqtt5AuthBuilder authBuilder)	Called when a server reauthenticates a client and the client used this enhanced auth mechanism during connection.

Method Details

getMethod

@NotNull
@NotNull MqttUtf8String getMethod()

Returns:

the method of this enhanced auth mechanism. This method MUST always return the same name.

getTimeout

int getTimeout()

Returns:

the maximum time interval in seconds between messages of the enhanced auth handshake (Connect, Auth, ConnAck, Disconnect). This method MUST always return the same value.

onAuth

@NotNull
@NotNull CompletableFuture<Void> onAuth(@NotNull
 @NotNull Mqtt5ClientConfig clientConfig,
 @NotNull
 @NotNull Mqtt5Connect connect,
 @NotNull
 @NotNull Mqtt5EnhancedAuthBuilder authBuilder)

Called when a client connects using this enhanced auth mechanism.

Parameters:

clientConfig - the config of the client.

connect - the Connect message.

authBuilder - the builder for the outgoing Auth message.

Returns:

a CompletableFuture succeeding when the required data for auth is added to the builder.

onReAuth

@NotNull
@NotNull CompletableFuture<Void> onReAuth(@NotNull
 @NotNull Mqtt5ClientConfig clientConfig,
 @NotNull
 @NotNull Mqtt5AuthBuilder authBuilder)

Called when a client reauthenticates and used this enhanced auth mechanism during connection.

Parameters:

clientConfig - the config of the client.

authBuilder - the builder for the outgoing Auth message.

Returns:

a CompletableFuture succeeding when the required data for auth is added to the builder.

onServerReAuth

@NotNull
default @NotNull CompletableFuture<Boolean> onServerReAuth(@NotNull
 @NotNull Mqtt5ClientConfig clientConfig,
 @NotNull
 @NotNull Mqtt5Auth auth,
 @NotNull
 @NotNull Mqtt5AuthBuilder authBuilder)

Called when a server reauthenticates a client and the client used this enhanced auth mechanism during connection.

This is an addition to the MQTT 5 specification and so defaults to onReAuth(Mqtt5ClientConfig, Mqtt5AuthBuilder). The feature must be explicitly enabled during client creation.

Parameters:

clientConfig - the config of the client.

auth - the Auth message sent by the server.

authBuilder - the builder for the outgoing Auth message.

Returns:

a CompletableFuture succeeding with a boolean indicating whether the client accepts the auth step and when the required data for auth is added to the builder.

onContinue

@NotNull
@NotNull CompletableFuture<Boolean> onContinue(@NotNull
 @NotNull Mqtt5ClientConfig clientConfig,
 @NotNull
 @NotNull Mqtt5Auth auth,
 @NotNull
 @NotNull Mqtt5AuthBuilder authBuilder)

Called when a server requires further data for auth from a client which used this enhanced auth mechanism during connection.

Parameters:

clientConfig - the config of the client.

auth - the Auth message sent by the server.

authBuilder - the builder for the outgoing Auth message.

Returns:

a CompletableFuture succeeding with a boolean indicating whether the client accepts the auth step and when the required data for auth is added to the builder.

onAuthSuccess

@NotNull
@NotNull CompletableFuture<Boolean> onAuthSuccess(@NotNull
 @NotNull Mqtt5ClientConfig clientConfig,
 @NotNull
 @NotNull Mqtt5ConnAck connAck)

Called when a server accepted auth of a client which used this enhanced auth mechanism during connection.

Parameters:

clientConfig - the config of the client.

connAck - the ConnAck message sent by the server.

Returns:

a CompletableFuture succeeding with a boolean indicating whether the client accepts the auth.

onReAuthSuccess

@NotNull
@NotNull CompletableFuture<Boolean> onReAuthSuccess(@NotNull
 @NotNull Mqtt5ClientConfig clientConfig,
 @NotNull
 @NotNull Mqtt5Auth auth)

Called when a server accepted reauth of a client which used this enhanced auth mechanism during connection.

Parameters:

clientConfig - the config of the client.

auth - the Auth message sent by the server.

Returns:

a CompletableFuture succeeding with a boolean indicating whether the client accepts the reauth.

onAuthRejected

void onAuthRejected(@NotNull
 @NotNull Mqtt5ClientConfig clientConfig,
 @NotNull
 @NotNull Mqtt5ConnAck connAck)

Called when a server rejected auth of a client which used this enhanced auth mechanism during connection.

Parameters:

clientConfig - the config of the client.

connAck - the ConnAck message sent by the server.

onReAuthRejected

void onReAuthRejected(@NotNull
 @NotNull Mqtt5ClientConfig clientConfig,
 @NotNull
 @NotNull Mqtt5Disconnect disconnect)

Called when a server rejected reauth of a client which used this enhanced auth mechanism during connection.

Parameters:

clientConfig - the config of the client.

disconnect - the Disconnect message sent by the server.

onAuthError

void onAuthError(@NotNull
 @NotNull Mqtt5ClientConfig clientConfig,
 @NotNull
 @NotNull Throwable cause)

Called when an error occurred during auth of a client which used this enhanced auth mechanism during connection.

Parameters:

clientConfig - the config of the client.

cause - the error.

onReAuthError

void onReAuthError(@NotNull
 @NotNull Mqtt5ClientConfig clientConfig,
 @NotNull
 @NotNull Throwable cause)

Called when an error occurred during reauth of a client which used this enhanced auth mechanism during connection.

Parameters:

clientConfig - the config of the client.

cause - the error.