Global Namespace Settings

In EMQX 6.1, in addition to configuring individual namespace instances, a set of global namespace settings is available to control how namespaces are identified, how isolation behaviors are applied, and how topics and authorization are handled.

These settings apply cluster-wide and affect all namespaces and client connections. They are typically configured before enabling and using namespace-related features.

Global namespace settings can be managed through the Dashboard at: Management -> Namespace -> Settings.

Note

To preserve backward compatibility, most global namespace settings in EMQX 6.1, such as Client ID Isolation, Namespace as Mountpoint, and Mount Prefix for Authorization, are disabled by default.

To enable the corresponding isolation capabilities, you must explicitly turn them on under Namespace Related Configurations.

Allow Only Explicitly Created Namespaces

This setting controls whether clients are allowed to connect only to namespaces that have been explicitly created. It corresponds to multi_tenancy.allow_only_managed_namespaces in the configuration file.

When this setting is enabled, EMQX validates the client’s namespace during the connection process and decides whether to allow or reject the connection.

• Enabled:
  • Clients whose resolved namespace has not been explicitly created via the Dashboard or REST API will be denied connection.
  • Clients whose namespace cannot be resolved (for example, when the namespace source is not configured or does not produce a valid value) will also be denied connection.
• Disabled:
  • Clients are allowed to connect to namespaces that have not been explicitly created.
  • If a namespace source is configured, EMQX may automatically create namespaces as needed.

Note

Before enabling this setting, ensure that Take Namespace From is properly configured and that all valid clients can successfully resolve an explicitly created namespace. Otherwise, clients may be rejected because their namespace cannot be resolved or has not been explicitly created.

When After Authentication mode is selected under When to Resolve Namespace, pre-authentication namespace checks are skipped. The check against explicitly created namespaces runs after authentication completes instead.

Default Max Number of Sessions

This setting defines the default maximum number of concurrent sessions for newly created namespaces.

• Enabled:
  • Newly created namespaces automatically inherit this maximum session limit.
• Disabled:
  • Newly created namespaces have no session limit (infinity) by default.

This setting applies only to namespaces created after the configuration takes effect. Existing namespaces are not affected and must be updated individually if needed.

Denied Namespace Names

Starting from EMQX 6.3.0, multi_tenancy.deny_namespaces specifies names that cannot be used as namespace identifiers. The restriction applies to Dashboard user roles, API keys, namespace creation and bulk imports through the management API, and client namespace assignment through client_attrs.tns.

The default list is ["global", "undefined", "null", "none"]. These names can be confused with internal identifiers in logs and Dashboard output.

To edit the list in the Dashboard:

1. Go to Management -> Namespace -> Settings.
2. In Denied Namespace Names, add or remove names as needed. Clear all entries to disable the name restriction.
3. Click Confirm to apply the changes.

You can also configure the list in etc/base.hocon. The following example shows the default value:

multi_tenancy.deny_namespaces = ["global", "undefined", "null", "none"]

A custom list replaces the default list. Include any default names you still want to deny. Set multi_tenancy.deny_namespaces = [] to disable the name restriction. For configuration file precedence, see Config Override Rules.

EMQX rejects a client connection with not_authorized if its resolved namespace is in the list, even when Allow Only Explicitly Created Namespaces is disabled. This restriction does not prevent clients without a namespace from connecting when multi_tenancy.allow_only_managed_namespaces = false.

Important Notice

The default list rejects names accepted before EMQX 6.3.0. EMQX does not automatically migrate namespaces that use these names. Before upgrading, change the affected namespace names or adjust multi_tenancy.deny_namespaces to allow them.

When to Resolve Namespace

This setting controls at which point in the connection lifecycle EMQX resolves the client’s namespace identifier.

EMQX supports two modes, selectable via the When to Resolve Namespace radio button in the Dashboard:

• Before Authentication (default): The namespace expression is evaluated before the authentication chain runs, using only connection metadata available at that point (such as username, clientid, or cert_common_name). This corresponds to configuring tns via mqtt.client_attrs_init in the configuration file.
• After Authentication: The namespace expression is evaluated after the full authentication chain completes. In addition to the standard connection metadata, client_attrs.* values are available, including any attributes returned by the authentication backend (for example, a tag field from an HTTP auth response). This corresponds to configuring multi_tenancy.post_auth_tns_expression in the configuration file.

TIP

If After Authentication is configured, EMQX uses the post-authentication expression to assign the namespace. A pre-authentication tns value is not used as a fallback if that expression renders empty or fails. See Empty or Failed Post-authentication Expressions.

Interaction with Allow Only Explicitly Created Namespaces

When After Authentication mode is selected, pre-authentication namespace checks are skipped entirely, even if Allow Only Explicitly Created Namespaces is enabled. All enforcement (whether the resolved namespace exists, quota checks) is deferred until after authentication completes and the final namespace value is known.

Take Namespace From

This setting specifies the Variform expression EMQX uses to derive the client’s namespace identifier (client_attrs.tns).

The expression is evaluated at the point in the connection lifecycle determined by the When to Resolve Namespace setting:

• In Before Authentication mode, only standard connection metadata is available: username, clientid, cert_common_name, and other pre-auth attributes.
• In After Authentication mode, client_attrs.* is also available, including attributes merged in from the authentication result.

TIP

The Take Namespace From expression uses Variform syntax. For details on available functions, see Variform Expressions.

This configuration is a prerequisite for the following features:

• Automatic namespace creation
• Namespace-based topic isolation
• Namespace-based Client ID isolation
• Namespace-level session limits and rate limits

If Take Namespace From is not configured, no tns attribute will be generated. In this case, clients will not be associated with any namespace, and all namespace-related isolation and control features will remain inactive.

Examples

Before Authentication

Extract the namespace from the username:

nth(1, tokens(username, '-'))

With this configuration, a client connecting with the username tenantA-user1 has tenantA assigned as its namespace identifier before authentication runs.

After Authentication

Use a tag attribute returned by an HTTP auth backend:

client_attrs.tag

With a fallback in case the auth backend does not return a tag:

coalesce(client_attrs.tag, username)

With this configuration, EMQX waits for the authentication chain to complete, then reads the tag value from the merged client_attrs and assigns it as the namespace identifier.

Empty or Failed Post-authentication Expressions

When multi_tenancy.post_auth_tns_expression is configured but evaluates to an empty string or fails, EMQX handles the connection as follows. Evaluation failures also produce a warning log.

1. If the pre-authentication client_attrs.tns value is in multi_tenancy.deny_namespaces, EMQX rejects the connection with not_authorized.
2. Otherwise, EMQX treats the client as having no namespace:
   • If multi_tenancy.allow_only_managed_namespaces = true, EMQX rejects the connection with not_authorized.
   • If multi_tenancy.allow_only_managed_namespaces = false, EMQX removes any pre-authentication tns value and allows the client to connect without a namespace.

Client ID Isolation

Client ID isolation prevents conflicts when clients in different namespaces use the same Client ID.

EMQX identifies sessions globally by the effective Client ID, not by a combination of namespace and Client ID. Client ID isolation therefore makes the effective Client ID globally unique, typically by adding the namespace as a prefix. Clients continue to send their original Client IDs, while EMQX uses the overridden IDs internally as the effective Client IDs.

Choose a Client ID Override Mechanism

Choose a mechanism based on where the namespace information comes from and whether the effective Client ID must contain it:

• If the namespace is available before authentication, configure mqtt.clientid_override. EMQX evaluates this expression after mqtt.client_attrs_init and before authentication, so it can use attributes initialized by mqtt.client_attrs_init, including client_attrs.tns.
• If the namespace comes from authentication results and the effective Client ID must include it, configure the authentication backend to return clientid_override. The returned value must contain the complete new Client ID. The mqtt.clientid_override expression cannot use attributes returned by an authentication backend or a namespace generated by multi_tenancy.post_auth_tns_expression.
• If multi_tenancy.post_auth_tns_expression sets the namespace but the effective Client ID does not need to include it, no Client ID override is required only when clients already use globally unique Client IDs.

Use only one Client ID override mechanism for a connection. If both mechanisms are configured, an authentication-result override runs later and replaces the Client ID produced by mqtt.clientid_override. In either case, ensure that the resulting Client ID is globally unique.

How EMQX Applies Client ID Overrides

EMQX determines the effective Client ID in the following order:

1. Initialize client attributes with mqtt.client_attrs_init.
2. Evaluate mqtt.clientid_override before authentication.
3. Authenticate the client and apply a non-empty clientid_override returned in the successful authentication result.
4. Evaluate multi_tenancy.post_auth_tns_expression.
5. Open the client session with the effective Client ID.

EMQX does not evaluate mqtt.clientid_override again or automatically add a namespace obtained after authentication to the Client ID. If a successful authentication result omits clientid_override or returns an empty value, EMQX keeps the previously determined Client ID.

Configure Pre-Authentication Client ID Isolation

When Client ID Isolation is enabled in the Dashboard, EMQX configures mqtt.clientid_override and automatically populates a recommended expression:

concat([client_attrs.tns, '-', clientid])

Important Notice

Starting from EMQX 6.3.0, if the mqtt.clientid_override expression raises an error or renders an empty string, EMQX logs an error and rejects the connection. MQTT 5.0 clients receive CONNACK reason code 0x85 (Client Identifier not valid), and MQTT 3.1 and 3.1.1 clients receive return code 2. EMQX does not fall back to the Client ID supplied by the client.

Before upgrading, verify that every connecting client can render the configured expression to a non-empty string. Fix the expression or required client data for any client that cannot do so.

With this configuration:

• Clients in different namespaces can safely use the same Client ID.
• The internally used Client ID always includes the namespace prefix.

This expression is provided as an example for namespaces resolved before authentication. You may customize it to suit your business requirements, as long as the resulting Client ID remains globally unique.

Example Behavior

Assume a namespace source has been configured to extract the namespace from the username:

nth(1, tokens(username, '-'))

Client ID isolation is enabled using the default expression:

concat([client_attrs.tns, '-', clientid])

Client Connection Details

Client	Username	Client ID
A	tenantA-user1	client1
B	tenantB-user2	client1

Internally Used Client IDs

Namespace	Original Client ID	Actual Client ID
tenantA	client1	tenantA-client1
tenantB	client1	tenantB-client1

Namespace as Mountpoint

When enabled, EMQX uses the client’s namespace as a topic mountpoint after the namespace has been successfully resolved. This enables namespace-level topic isolation.

If a listener already has a mountpoint configured, this setting is ignored and the listener-level configuration takes precedence.

Behavior

After Namespace as Mountpoint is enabled, EMQX isolates topics as follows:

• During PUBLISH, SUBSCRIBE, UNSUBSCRIBE, and Will message processing:
  • EMQX automatically prepends {namespace}/ to topics internally.
• When delivering messages to clients:
  • The namespace prefix is automatically stripped.
• From the client’s perspective:
  • Published and subscribed topic names remain unchanged.
  • Clients are not aware of the namespace prefix.

Example

Assume the client belongs to namespace n1 and Namespace as Mountpoint is enabled.

Client-side Behavior

• Client subscribes to: sensors/#
• Client publishes to: sensors/data

Internal Processing in EMQX

• Broker registers the subscription as: n1/sensors/#
• Broker routes messages using: n1/sensors/data
• Message is delivered to the client as: sensors/data

As a result:

• Namespace prefixes are used only internally.
• Clients always interact with original topic names.
• Clients in different namespaces using the same topics do not receive each other’s messages.

Mount Prefix for Authorization

This setting controls whether the topic mountpoint prefix is added to target topics and topic filters before authorization (ACL) checks are performed.

The mountpoint prefix typically comes from the namespace when Namespace as Mountpoint is enabled, and follows the format:

{namespace}/

Behavior

When Mount Prefix for Authorization is enabled:

• EMQX prepends the topic mountpoint to the target topic or topic filter before matching ACL rules or authorization backends.
• Authorization checks are performed using the prefixed topic.

This behavior applies to the following operations:

• PUBLISH
• SUBSCRIBE
• UNSUBSCRIBE
• Will messages

Example

Assume the following configuration is enabled:

• Namespace as Mountpoint
• Mount Prefix for Authorization
• Client namespace: n1

Client Action

The client attempts to subscribe to:

sensors/#

Topic Used for Authorization

During authorization, EMQX evaluates n1/sensors/#. Therefore, the corresponding ACL rule must be defined as n1/sensors/# rather than sensors/#.

Recommendation

When Namespace as Mountpoint is enabled for topic isolation, it is recommended to enable Mount Prefix for Authorization as well. This ensures that authorization checks are performed against the same topic names used internally by the broker, avoiding inconsistencies between authorization results and actual message routing.