Package com.hivemq.extension.sdk.api.auth.parameter

Interface EnhancedAuthOutput

All Superinterfaces:

AsyncOutput<EnhancedAuthOutput>, SimpleAsyncOutput<EnhancedAuthOutput>

@DoNotImplement
public interface EnhancedAuthOutput
extends AsyncOutput<EnhancedAuthOutput>

Output parameter provided to the methods of an EnhancedAuthenticator.

It can be used to

• Authenticate the client successfully OR
• Fail the authentication OR
• Continue the authentication OR
• Delegate the decision to the next extension

Exactly one of the decisive methods must be called:

• authenticateSuccessfully()
• authenticateSuccessfully(byte[])
• authenticateSuccessfully(ByteBuffer)
• failAuthentication()
• failAuthentication(DisconnectedReasonCode)
• failAuthentication(String)
• failAuthentication(DisconnectedReasonCode, String)
• continueAuthentication()
• continueAuthentication(byte[])
• continueAuthentication(ByteBuffer)
• nextExtensionOrDefault()

Subsequent calls will fail with an UnsupportedOperationException.

The default topic permissions only apply if the client is authenticated successfully.

In case of a failed authentication a CONNACK packet with the appropriate reason code is sent to the client. In case of a failed re-authentication a DISCONNECT packet with the appropriate reason code is sent to the client.

Since:

4.3.0, CE 2020.1

Method Summary

Modifier and Type	Method	Description
@NotNull Async<EnhancedAuthOutput>	async(@NotNull Duration timeout, @NotNull TimeoutFallback timeoutFallback)	If the timeout is expired before Async.resume() is called then the outcome is handled either as failed or successful, depending on the specified fallback.
@NotNull Async<EnhancedAuthOutput>	async(@NotNull Duration timeout, @NotNull TimeoutFallback timeoutFallback, @NotNull DisconnectedReasonCode reasonCode)	If the timeout is expired before Async.resume() is called then the outcome is handled either as failed or successful, depending on the specified fallback.
@NotNull Async<EnhancedAuthOutput>	async(@NotNull Duration timeout, @NotNull TimeoutFallback timeoutFallback, @NotNull DisconnectedReasonCode reasonCode, @Nullable String reasonString)	If the timeout is expired before Async.resume() is called then the outcome is handled either as failed or successful, depending on the specified fallback.
@NotNull Async<EnhancedAuthOutput>	async(@NotNull Duration timeout, @NotNull TimeoutFallback timeoutFallback, @Nullable String reasonString)	If the timeout is expired before Async.resume() is called then the outcome is handled either as failed or successful, depending on the specified fallback.
void	authenticateSuccessfully()	Successfully authenticates the client.
void	authenticateSuccessfully(@com.hivemq.extension.sdk.api.annotations.NotNull byte[] authenticationData)	Successfully authenticates the client.
void	authenticateSuccessfully(@NotNull ByteBuffer authenticationData)	Successfully authenticates the client.
void	continueAuthentication()	Continues the authentication of the client by sending an AUTH packet to the client and expecting another AUTH packet in response from the client.
void	continueAuthentication(@com.hivemq.extension.sdk.api.annotations.NotNull byte[] authenticationData)	Continues the authentication of the client by sending an AUTH packet to the client and expecting another AUTH packet in response from the client.
void	continueAuthentication(@NotNull ByteBuffer authenticationData)	Continues the authentication of the client by sending an AUTH packet to the client and expecting another AUTH packet in response from the client.
void	failAuthentication()	Fails the authentication of the client.
void	failAuthentication(@NotNull DisconnectedReasonCode reasonCode)	Fails the authentication of the client.
void	failAuthentication(@NotNull DisconnectedReasonCode reasonCode, @Nullable String reasonString)	Fails the authentication of the client.
void	failAuthentication(@Nullable String reasonString)	Fails the authentication of the client.
@NotNull ModifiableClientSettings	getClientSettings()	Provides ModifiableClientSettings to configure client specific parameters and restrictions.
@NotNull ModifiableDefaultPermissions	getDefaultPermissions()	Provides ModifiableDefaultPermissions to configure client specific default permissions.
@NotNull ModifiableUserProperties	getOutboundUserProperties()	Provides ModifiableUserProperties to add or remove user properties to or from the outgoing CONNACK, AUTH or DISCONNECT packet.
void	nextExtensionOrDefault()	The outcome of the authentication is determined by an authenticator of the next extension (with lower priority).
void	setTimeout(int timeout)	Sets the time interval (in seconds) in which a response from the client is expected before the authentication times out.

Methods inherited from interface com.hivemq.extension.sdk.api.async.SimpleAsyncOutput

async

Method Detail

continueAuthentication

void continueAuthentication()

Continues the authentication of the client by sending an AUTH packet to the client and expecting another AUTH packet in response from the client.

Sends an AUTH packet with reason code CONTINUE_AUTHENTICATION and no authentication data to the client.

This is a final decision, authenticators of the next extensions (with lower priority) are not called.

Throws:

UnsupportedOperationException - If the client does not support enhanced authentication (it did not specify a authentication method in the CONNECT packet).

UnsupportedOperationException - When authenticateSuccessfully, failAuthentication, continueAuthentication or nextExtensionOrDefault has already been called.

Since:

4.3.0, CE 2020.1

continueAuthentication

void continueAuthentication(@NotNull ByteBuffer authenticationData)

Continues the authentication of the client by sending an AUTH packet to the client and expecting another AUTH packet in response from the client.

Sends an AUTH packet with reason code CONTINUE_AUTHENTICATION and the specified authentication data to the client.

This is a final decision, authenticators of the next extensions (with lower priority) are not called.

Parameters:

authenticationData - The authentication data of the AUTH packet.

Throws:

UnsupportedOperationException - If the client does not support enhanced authentication (it did not specify a authentication method in the CONNECT packet).

UnsupportedOperationException - When authenticateSuccessfully, failAuthentication, continueAuthentication or nextExtensionOrDefault has already been called.

Since:

4.3.0, CE 2020.1

continueAuthentication

void continueAuthentication(@NotNull
                            @com.hivemq.extension.sdk.api.annotations.NotNull byte[] authenticationData)

Continues the authentication of the client by sending an AUTH packet to the client and expecting another AUTH packet in response from the client.

Sends AUTH packet with reason code CONTINUE_AUTHENTICATION and the specified authentication data to the client.

This is a final decision, authenticators of the next extensions (with lower priority) are not called.

Parameters:

authenticationData - The authentication data of the AUTH packet.

Throws:

UnsupportedOperationException - If the client does not support enhanced authentication (it did not specify a authentication method in the CONNECT packet).

UnsupportedOperationException - When authenticateSuccessfully, failAuthentication, continueAuthentication or nextExtensionOrDefault has already been called.

Since:

4.3.0, CE 2020.1

authenticateSuccessfully

void authenticateSuccessfully()

Successfully authenticates the client.

During authentication a CONNACK packet with reason code SUCCESS and no authentication data is sent to the client.

During re-authentication an AUTH packet with reason code SUCCESS and no authentication data is sent to the client.

This is a final decision, authenticators of the next extensions (with lower priority) are not called.

Throws:

UnsupportedOperationException - When authenticateSuccessfully, failAuthentication, continueAuthentication or nextExtensionOrDefault has already been called.

Since:

4.3.0, CE 2020.1

authenticateSuccessfully

void authenticateSuccessfully(@NotNull ByteBuffer authenticationData)

Successfully authenticates the client.

During authentication a CONNACK packet with reason code SUCCESS and the specified authentication data is sent to the client.

During re-authentication an AUTH packet with reason code SUCCESS and the specified authentication data is sent to the client.

This is a final decision, authenticators of the next extensions (with lower priority) are not called.

Parameters:

authenticationData - The authentication data of the CONNACK or AUTH packet.

Throws:

UnsupportedOperationException - When authenticateSuccessfully, failAuthentication, continueAuthentication or nextExtensionOrDefault has already been called.

Since:

4.3.0, CE 2020.1

authenticateSuccessfully

void authenticateSuccessfully(@NotNull
                              @com.hivemq.extension.sdk.api.annotations.NotNull byte[] authenticationData)

Successfully authenticates the client.

During authentication a CONNACK packet with reason code SUCCESS and the specified authentication data is sent to the client.

During re-authentication an AUTH packet with reason code SUCCESS and the specified authentication data is sent to the client.

This is a final decision, authenticators of the next extensions (with lower priority) are not called.

Parameters:

authenticationData - The authentication data of the CONNACK or AUTH packet.

Throws:

UnsupportedOperationException - When authenticateSuccessfully, failAuthentication, continueAuthentication or nextExtensionOrDefault has already been called.

Since:

4.3.0, CE 2020.1

failAuthentication

void failAuthentication()

Fails the authentication of the client.

During authentication a CONNACK packet with reason code NOT_AUTHORIZED and reason string Authentication failed is sent to the client.

During re-authentication a DISCONNECT packet with reason code NOT_AUTHORIZED and reason string Re-authentication failed is sent to the client.

This is a final decision, authenticators of the next extensions (with lower priority) are not called.

Throws:

UnsupportedOperationException - When authenticateSuccessfully, failAuthentication, continueAuthentication or nextExtensionOrDefault has already been called.

Since:

4.3.0, CE 2020.1

failAuthentication

void failAuthentication(@NotNull DisconnectedReasonCode reasonCode)

Fails the authentication of the client.

During authentication a CONNACK packet with the specified reason code and reason string Authentication failed is sent to the client.

During re-authentication a DISCONNECT packet with the specified reason code and reason string Re-authentication failed is sent to the client.

This is a final decision, authenticators of the next extensions (with lower priority) are not called.

Parameters:

reasonCode - The reason code of the CONNACK or DISCONNECT packet.

Throws:

UnsupportedOperationException - When authenticateSuccessfully, failAuthentication, continueAuthentication or nextExtensionOrDefault has already been called.

IllegalArgumentException - when DisconnectedReasonCode is set to a DISCONNECT only reason code during authentication.

IllegalArgumentException - when DisconnectedReasonCode is set to a CONNACK only reason code during re-authentication.

Since:

4.3.0, CE 2020.1

failAuthentication

void failAuthentication(@Nullable String reasonString)

Fails the authentication of the client.

During authentication a CONNACK packet with reason code NOT_AUTHORIZED and the specified reason string is sent to the client.

During re-authentication a DISCONNECT packet with reason code NOT_AUTHORIZED and the specified reason string is sent to the client.

This is a final decision, authenticators of the next extensions (with lower priority) are not called.

Parameters:

reasonString - The reason string of the CONNACK or DISCONNECT packet.

Throws:

UnsupportedOperationException - When authenticateSuccessfully, failAuthentication, continueAuthentication or nextExtensionOrDefault has already been called.

Since:

4.3.0, CE 2020.1

failAuthentication

void failAuthentication(@NotNull DisconnectedReasonCode reasonCode,
                        @Nullable String reasonString)

Fails the authentication of the client.

During authentication a CONNACK packet with the specified reason code and reason string is sent to the client.

During re-authentication a DISCONNECT packet with the specified reason code and reason string is sent to the client.

This is a final decision, authenticators of the next extensions (with lower priority) are not called.

Parameters:

reasonCode - The reason code of the CONNACK or DISCONNECT packet.

reasonString - The reason string of the CONNACK or DISCONNECT packet.

Throws:

UnsupportedOperationException - When authenticateSuccessfully, failAuthentication, continueAuthentication or nextExtensionOrDefault has already been called.

IllegalArgumentException - when DisconnectedReasonCode is set to a DISCONNECT only reason code during authentication.

IllegalArgumentException - when DisconnectedReasonCode is set to a CONNACK only reason code during re-authentication.

Since:

4.3.0, CE 2020.1

nextExtensionOrDefault

void nextExtensionOrDefault()

The outcome of the authentication is determined by an authenticator of the next extension (with lower priority).

If no extension with an authenticator is left the default behaviour is used. The default behaviour is the same as failAuthentication().

Throws:

UnsupportedOperationException - When authenticateSuccessfully, failAuthentication, continueAuthentication or nextExtensionOrDefault has already been called.

Since:

4.3.0, CE 2020.1

setTimeout

void setTimeout(int timeout)

Sets the time interval (in seconds) in which a response from the client is expected before the authentication times out.

This only applies if continueAuthentication is called.

If the authentication times out a CONNACK packet with reason code NOT_AUTHORIZED and reason string Authentication failed, timeout before the client provided required authentication data is sent to the client.

If the re-authentication times out a DISCONNECT packet with reason code NOT_AUTHORIZED and reason string Re-authentication failed, timeout before the client provided required authentication data is sent to the client.

Parameters:

timeout - The timeout in seconds.

Since:

4.3.0, CE 2020.1

getOutboundUserProperties

@NotNull ModifiableUserProperties getOutboundUserProperties()

Provides ModifiableUserProperties to add or remove user properties to or from the outgoing CONNACK, AUTH or DISCONNECT packet.

Returns:

The ModifiableUserProperties of the CONNACK, AUTH or DISCONNECT packet.

Since:

4.3.0, CE 2020.1

getDefaultPermissions

@NotNull ModifiableDefaultPermissions getDefaultPermissions()

Provides ModifiableDefaultPermissions to configure client specific default permissions.

Default permissions are automatically applied by HiveMQ for every PUBLISH and SUBSCRIBE packet sent by the client.

Returns:

The ModifiableDefaultPermissions for the client.

Since:

4.3.0, CE 2020.1

getClientSettings

@NotNull ModifiableClientSettings getClientSettings()

Provides ModifiableClientSettings to configure client specific parameters and restrictions.

Returns:

The ModifiableClientSettings for the client.

Since:

4.3.0, CE 2020.1

async

@NotNull Async<EnhancedAuthOutput> async(@NotNull Duration timeout,
                                         @NotNull TimeoutFallback timeoutFallback)

If the timeout is expired before Async.resume() is called then the outcome is handled either as failed or successful, depending on the specified fallback.

Do not call this method more than once. If an async method is called multiple times an exception is thrown.

Specified by:

async in interface AsyncOutput<EnhancedAuthOutput>

Parameters:

timeoutFallback - Fallback behaviour if a timeout occurs.

SUCCESS has the same effect as nextExtensionOrDefault().

FAILURE has the same effect as failAuthentication(DisconnectedReasonCode, String) with reason code NOT_AUTHORIZED and reason string Authentication failed, authenticator timed out (or Re-authentication failed, authenticator timed out during re-authentication).

timeout - Timeout that HiveMQ waits for the result of the async operation.

Returns:

An Async object, usually containing the output object.

Since:

4.3.0, CE 2020.1

async

@NotNull Async<EnhancedAuthOutput> async(@NotNull Duration timeout,
                                         @NotNull TimeoutFallback timeoutFallback,
                                         @NotNull DisconnectedReasonCode reasonCode)

If the timeout is expired before Async.resume() is called then the outcome is handled either as failed or successful, depending on the specified fallback.

Do not call this method more than once. If an async method is called multiple times an exception is thrown.

Parameters:

timeout - Timeout that HiveMQ waits for the result of the async operation.

timeoutFallback - Fallback behaviour if a timeout occurs.

SUCCESS has the same effect as nextExtensionOrDefault().

FAILURE has the same effect as failAuthentication(DisconnectedReasonCode, String) with the specified reason code and reason string Authentication failed, authenticator timed out (or Re-authentication failed, authenticator timed out during re-authentication).

reasonCode - The reason code sent in CONNACK or DISCONNECT when timeout occurs.

Returns:

An Async object, usually containing the EnhancedAuthOutput.

Throws:

UnsupportedOperationException - If async is called more than once.

IllegalArgumentException - when DisconnectedReasonCode is set to a DISCONNECT only reason code during authentication.

IllegalArgumentException - when DisconnectedReasonCode is set to a CONNACK only reason code during re-authentication.

Since:

4.3.0, CE 2020.1

async

@NotNull Async<EnhancedAuthOutput> async(@NotNull Duration timeout,
                                         @NotNull TimeoutFallback timeoutFallback,
                                         @Nullable String reasonString)

If the timeout is expired before Async.resume() is called then the outcome is handled either as failed or successful, depending on the specified fallback.

Do not call this method more than once. If an async method is called multiple times an exception is thrown.

Parameters:

timeout - Timeout that HiveMQ waits for the result of the async operation.

timeoutFallback - Fallback behaviour if a timeout occurs.

SUCCESS has the same effect as nextExtensionOrDefault().

FAILURE has the same effect as failAuthentication(DisconnectedReasonCode, String) with reason code NOT_AUTHORIZED and the specified reason string.

reasonString - The reason string sent in CONNACK or DISCONNECT when timeout occurs.

Returns:

An Async object, containing the EnhancedAuthOutput.

Throws:

UnsupportedOperationException - If async is called more than once.

Since:

4.3.0, CE 2020.1

async

@NotNull Async<EnhancedAuthOutput> async(@NotNull Duration timeout,
                                         @NotNull TimeoutFallback timeoutFallback,
                                         @NotNull DisconnectedReasonCode reasonCode,
                                         @Nullable String reasonString)

If the timeout is expired before Async.resume() is called then the outcome is handled either as failed or successful, depending on the specified fallback.

Do not call this method more than once. If an async method is called multiple times an exception is thrown.

Parameters:

timeout - Timeout that HiveMQ waits for the result of the async operation.

timeoutFallback - Fallback behaviour if a timeout occurs.

SUCCESS has the same effect as nextExtensionOrDefault().

FAILURE has the same effect as failAuthentication(DisconnectedReasonCode, String) with the specified reason code and reason string.

reasonCode - The reason code sent in CONNACK or DISCONNECT when timeout occurs.

reasonString - The reason string sent in CONNACK or DISCONNECT when timeout occurs.

Returns:

An Async object, containing the EnhancedAuthOutput.

Throws:

UnsupportedOperationException - If async is called more than once.

IllegalArgumentException - when DisconnectedReasonCode is set to a DISCONNECT only reason code during authentication.

IllegalArgumentException - when DisconnectedReasonCode is set to a CONNACK only reason code during re-authentication.

Since:

4.3.0, CE 2020.1