HiveMQ Cloud Authentication and Authorization
HiveMQ Cloud provides advanced authentication and authorization mechanisms that help you safeguard your data, prevent unauthorized access, and maintain the overall security and integrity of your application.
Both authentication and authorization play important roles in ensuring secure communication between MQTT clients and the MQTT broker.
You manage authentication and authorization from the Access Management tab of your HiveMQ Cloud console.
HiveMQ Cloud Access Management
HiveMQ Cloud access management offers various ways to authenticate and authorize the MQTT clients that access your cluster. Based on your HiveMQ Cloud plan, you can choose between different available authentication methods and assign fine-grained permissions.
In general, authentication verifies whether a person, device, or application is who they say they are.
Authorization defines which actions the specific person, device, or application is allowed to perform.
Authorization can be split into the concepts of roles and permissions.
HiveMQ Cloud access management gives you the following capabilities:
-
Select an authentication method for your MQTT clients that fits your individual use case
-
Create fine-grained permissions that authorize your MQTT clients to perform specific actions on your cluster
Username and Password Authentication
Username and password authentication is a simple and straightforward way to authenticate MQTT clients.
The MQTT protocol provides username and password fields in the CONNECT packet an MQTT client sends to establish a connection with your HiveMQ Cloud broker.
On HiveMQ Cloud, username and password authentication is the default authentication method.
To manage access to your HiveMQ Cloud cluster, you define access credentials your MQTT clients can use to connect to your cluster.
Each access credential contains a username-password pair to authenticate the MQTT client and permission information that authorizes specific activities on your cluster.
HiveMQ Cloud securely stores each credential you create for you.
When an MQTT client attempts to connect to your cluster, HiveMQ Cloud uses the username and password information in the CONNECT packet to verify the identity of the MQTT client against the username and password in your stored access credentials.
Access Credentials
In HiveMQ Cloud, only MQTT clients that successfully authenticate with known credentials are allowed to connect and perform actions on your cluster.
Create Access Credentials for MQTT Clients
To create a credential, go to the Access Credentials area of the Access Management tab on your running HiveMQ Cloud cluster.
|
To locate the Access Credentials area, go to Your Clusters and select Manage Cluster for the desired cluster. On the Cluster Details page that opens, switch to the Access Management tab. |
When you create an access credential for HiveMQ Cloud, you define a username, a password, and assign a permission or role to the credential.
|
The way permissions are assigned to a credential varies based on your HiveMQ Cloud plan. The Serverless plan ties the permission to a username. The Starter plan ties permissions to roles. To assign multiple roles and associated permissions to a single credential, you need to use the HiveMQ Cloud Starter plan or above. |
-
To create a credential on the Serverless plan, enter a Username and Password, and select the Permission level you want to associate with the credential.
To create the Serverless credential, select Create Credential.
-
To create a credential on the Starter plan, enter a Username and Password, and select the Role you want to associate with the credential.
To create the Starter credential, select Create Credential.
|
The credential username must be unique within the HiveMQ Cloud cluster. Multiple MQTT clients can share the same credential, or you can create dedicated credentials for each MQTT client. |
The permissions or roles that you assign to a credential control the type of actions MQTT clients that connect with the credential can perform.
You can use the predefined default permissions and role that HiveMQ Cloud provides or create custom permissions and roles as needed to fulfill your individual use case.
For more information, see Permission Management.
HiveMQ Cloud has three default permissions:
-
Publish and subscribe
-
Subscribe only
-
Publish only
For more information, see Default Permissions.
HiveMQ Cloud Starter plan and up provides one default role that includes all three default permissions. For more information, see Default Role.
You can add and delete as many MQTT credentials for your HiveMQ Cloud cluster as needed.
When you add or delete a credential, the Access Credentials area automatically adjusts to list only credentials that are currently available for the selected cluster.
|
When you remove credentials, clients that are currently connected with the credentials remain connected. During the next reconnect, the clients will no longer be able to connect to the cluster with the old credentials. |
Permission Management
HiveMQ Cloud access management allows you to limit the amount of access MQTT clients have to your HiveMQ cloud cluster.
In HiveMQ Cloud, you assign different permissions to set the activity level of an MQTT client on your cluster.
A permission is a rule that defines a specific action an MQTT client is allowed to perform at the broker.
Each permission is tied to an MQTT topic filter.
For more information, see Topic Filters.
The available granularity of a permission depends on the HiveMQ Cloud plan.
Default Permissions
For your convenience, HiveMQ Cloud provides several default permissions that you can use to authorize your MQTT clients.
All default permissions use multi-level wildcard topic filters (#).
The multi-level wildcard topic filter specifies that the activity the default permission allows applies to all available MQTT topics.
The default permissions cannot be modified or removed from the system.
|
To limit a permission to specific MQTT topics, create a custom permission. You can create as many custom permissions as your use case requires. For more information, see Custom Permissions. |
| Permission name | Description |
|---|---|
Subscribe Only |
Clients that authenticate with credentials that include Subscribe Only permission are allowed to receive MQTT messages on all MQTT topics but are not allowed to publish MQTT messages. The permission includes a multi-level wildcard topic filter (#) specifies that subscriptions to all MQTT topics are allowed. Publishes are not allowed with this permission. |
Publish Only |
Clients that authenticate with credentials that include Publish Only permission are allowed to publish to available MQTT topics but are not allowed to subscribe to MQTT topics. |
Publish and Subscribe |
Clients that authenticate with credentials that include Publish and Subscribe permission are allowed to publish and subscribe to all available MQTT topics. |
The HiveMQ Cloud Serverless plan supports the selection of one permission per credential.
In the Serverless plan, permissions are tied to a username.
The default permissions are available for selection in the dropdown menu of the Permissions field:
| When you create custom permissions, the new permissions are automatically added to the list of available permissions in the Permissions field of the Access Credentials area. |
In the HiveMQ Cloud Starter plan, permissions are tied to roles. Each role can include one or more permissions, and you can assign multiple roles per credential.
The combination of roles and permissions gives you a structured and flexible way to manage how MQTT clients access and interact with your cluster.
For your convenience, the Starter plan provides one default role that includes all three default permissions:
|
When you create custom permissions in the Starter plan, the new permissions are automatically added to the list of available permissions in the Permissions field of the Roles area. When you create additional roles, the new roles are automatically added to the list of available roles in the Roles field of the Access Credentials area. |
For more information, see Default Role.
Custom Permissions
For some use cases, the default HiveMQ Cloud permissions are too generic. The ability to define custom permissions allows you to implement sophisticated topic-based access rights that match your business needs and facilitate permission management.
Permission Name
HiveMQ Cloud uses the permission name to identify the permission within the system.
Since the name is used as an identifier, each permission on your HiveMQ Cloud cluster must have a unique name.
When you create a custom permission, HiveMQ Cloud alerts you if the permission name is already in use and prevents the creation of a permission with a duplicate name.
In addition to a unique name, each custom permission includes a Description field where you can add information that helps identify the purpose of the permission.
After you create a custom permission, the name of the permission appears in the list of permissions you can assign during access credential creation.
|
Permissions and roles can only be tied to a username. In the Serverless plan, permissions are tied to a username. In the Starter plan, permissions are associated with a role. Currently, the Starter plan does not support mapping permissions to a username. |
Every permission in HiveMQ Cloud specifies an activity that the permission allows and contains an implicit or explicitly defined topic filter.
Permission Topic Filters
In a HiveMQ Cloud permission, the Topic Filter defines to which topics the permission applies.
All valid MQTT topic filters, including wildcards (+,#) are supported.
When you create a custom permission, the activity the permission allows applies only to the topics you define in the Topic Filter field.
| The way you create and assign permissions to your MQTT clients varies based on your HiveMQ Cloud plan. |
Create Permissions (Serverless plan)
In the HiveMQ Cloud Serverless plan, you select permissions in the Permissions field of the Access Credentials area.
To add a permission to the list of permissions that are available to assign to a credential, define a permission in the Permissions area of the Access Management tab:
After you create a permission in the Serverless plan, the name of the permission appears in the list of permissions you can assign to a credential.
Assign Permissions to Clients (Serverless plan)
The HiveMQ Cloud Serverless plan allows you to assign one permission per credential.
In the Serverless plan, permissions are tied to a specific username.
To assign a permission to a credential in the Serverless plan, select the desired permission in the Permissions field of the Access Credentials area.
For more information, see Permission Management.
Create Permissions (Starter plan and up)
In the HiveMQ Cloud Starter plan and above, you can define and attach one or more permissions to a role.
To add permissions to the list of permissions that are available to assign to a role, define a permission in the Permissions area of the Access Management tab:
Permissions in the Starter plan and above include the following options to allow specific actions:
-
Topic Filter: Defines the topic filter to which the permission applies. All valid MQTT topic filters, including wildcards (+,#) are supported. This field is required.
-
Publish/Subscribe: Defines the activity that the permission allows. You can apply the permission for Publishes, Subscriptions, and for both Publishes and Subscriptions. Select the checkboxes for all activities you want the permission to allow.
-
Quality of service level (QoS): Defines the QoS levels to which the permission applies. You can select one or more available QoS levels: QoS 0, QoS 1, and QoS 2. Select the checkboxes for all QoS levels for which you want the permission to apply.
-
Retained messages: Specifies whether the client is allowed to publish a message as a retained message. This option is only applicable in a permission that allows publishing.
-
Shared group: Specifies whether the client is allowed to subscribe to a shared subscription. If this option is selected, you must input a valid shared group name to which the client is allowed to subscribe. Enter the shared group name without
$share/or enter#to match all shared groups.
| The HiveMQ Cloud broker uses explicit whitelisting functionality. If an action is not explicitly allowed, it is denied. |
Each custom permission you create is added to the list of available permissions along with the predefined default permissions.
To delete a custom permission from the list of available permissions, select Delete.
|
A permission can only be deleted if it is not used to authenticate an MQTT client or if it is not used by a role. Before you delete a permission, you must remove all credentials and roles that use the permission. The default HiveMQ Cloud permissions can not be removed from the system. |
Assign Permissions to Clients (Starter plan and above)
The HiveMQ Cloud Starter plan and above allow you to assign one or more roles per credential.
Each role can include one or more permissions.
In the Starter plan, permissions are tied to a role.
To assign a permission to a credential in the Starter plan, you select a role that grants the desired permission in the Roles field of the Access Credentials area.
For more information, see Role-Based Access Control for MQTT Clients,
Role-Based Access Control
HiveMQ Cloud Starter plans and above support Role-Based Access Control (RBAC) for your MQTT client.
RBAC gives you the ability to group permissions into various roles.
When you assign one or more roles to a credential, clients that access your cluster with the credential can perform all activities that permissions associated with the roles allow.
Grouping permissions into roles helps reduce the complexity of managing individual permissions for MQTT clients.
As your use case grows, simplified permission management makes it easier to standardize the access rights of your MQTT clients.
With RBAC, you can ensure that MQTT clients with similar responsibilities have consistent levels of access.
Default Role
For your convenience, the HiveMQ Starter plan provides a default role that you can use to assign permissions to your credentials.
The default role includes all default permissions and several additional MQTT-specific permissions:
Custom Roles
Role-based access control for a HiveMQ Cloud cluster usually requires more roles than the default HiveMQ Cloud role. The ability to define custom roles with specifically selected permissions allows you to implement effective role-based access control for your MQTT clients to match your business needs.
Role Name
HiveMQ Cloud uses the name of the role to identify the role within the system.
Since the name is used as an identifier, each role on your HiveMQ Cloud cluster must have a unique name.
When you create a role, HiveMQ Cloud alerts you if the role name is already in use and prevents the creation of a role with a duplicate name.
In addition to a unique name, each role includes an optional Description field where you can add information that helps identify the purpose of the role.
After you create a role, the name of the role appears in the list of roles you can assign during access credential creation.
Every role in HiveMQ Cloud includes at leaset one permission that is associated with the role.
For more information, see Permission Management.
You can add and delete roles as needed to fit your individual use case.
Create Roles (Starter plan and above only)
In the HiveMQ Cloud Starter plan and above, you define roles to group permissions in ways that match your particular use case.
To add roles to the list of roles that are available to assign to a username when you create an access credential, define a role in the Roles area of the Access Management tab:
Each role can consist of an unlimited number of permissions.
When you create a custom role, you select the permissions that want to group together in the role to perform a specific task.
To create a role, enter a unique name, add a description of the role, and select one or more permissions from the list of available permissions in the Permissions field.
| The list automatically contains the predefined HiveMQ Cloud default permissions and all available custom permissions that you create. To add more permissions to the list of available permissions, see Create Permissions (Starter plan and up). |
To create the defined role, select Create Role.
Each role you create is added to the list of available roles in the Roles field of the Access Credentials area along with the predefined default role.
To delete a role from the list of available roles, select Delete.
|
A role can only be deleted if it is not used to authenticate an MQTT client. Before you delete a role, you must remove all credentials that use the role. |