Extended Authorization

Extended authorization enables users to authorize using their own services, supporting external databases such as MySQL and Redis as data sources, or connecting to an HTTP service for authorization.

Note

Extended authorization is not supported in EMQX Serverless deployments.

Extended Authorization Data Sources

Authorize with HTTP

Authorize with MySQL

Authorize with PostgreSQL

Authorize with Redis

Note

Although a maximum of two extended authorizations is supported, it is recommended not to use multiple extended authorizations simultaneously for performance reasons.

Authorization Order

After adding extended authorization data sources, you can sort the authorization sources. The deployment will perform authorization checks in the order from left to right. By default, the most recently added authorization is placed first, and the default authorization is placed last.

• Actions are matched with permissions, allowing or denying client operations based on permissions.

• If actions do not match with permissions, the check is passed to the next authorization checker.

How to Create an Authorization Chain

You can create an authorization chain on the Access Control -> Authorization -> Extended Authorization page in your deployment. Once an extended authorization data source is configured and connected, you can see the Order Setting section on the page.

1. Click the Authorization Order to enter the Authorization Order page.
2. Arrange the order of authorization by dragging the icons of the authorization data sources left and right.
3. When you finish, click Confirm to save the order.

Authorization Chain Requirements for Whitelist Mode

When the whitelist mode is enabled, clients are denied all subscription and publishing actions by default. You must explicitly grant permissions for each allowed operation. For step-by-step instructions, see Enable Authorization Whitelist Mode.

To enable whitelist mode, make sure that the "Default Authorization" source is positioned at the end of the authorization chain. You can manage this on the Authorization Order page under the Order Setting section.

External Resource Cache

TIP

The external resource cache feature is available for EMQX version 5.9 and later in the Dedicated edition.

EMQX Platform provides a caching mechanism for authorization results retrieved from external backends, such as MySQL or Redis. This cache is designed to improve the performance of authorization result lookups and reduce repeated access to external resources, especially in high-throughput environments.

Note

The external resource cache applies only to the extended data sources. For default authorization, EMQX Platform does not use this cache.

How External Resource Cache Works

The external resource cache stores authorization results. These results are shared across all client sessions in the cluster and help avoid redundant queries to external authorization backends.

When a publish/subscribe operation triggers an external backend query:

1. EMQX checks the external resource cache (shared across all clients).
2. EMQX checks the cache for a previously stored result:
   • If a valid result is found, it counts as a Cache Hit, and no call to the external backend is made.
   • If no result is found, it counts as a Cache Miss, and EMQX queries the external backend.
3. The result returned from the backend is stored in the cache for future use, incrementing the Cache Insert metric.

This mechanism helps reduce latency, minimize backend usage, and maintain system responsiveness under load.

Enable and Configure External Resource Cache

You can enable and configure the external resource cache on the Access Control -> Authorization -> Extended Authorization page in your deployment. Once an extended authorization data source is configured and connected, you can see the Cache Setting section on the page.

1. Click the External Resource Cache Settings to open a side panel.
2. In the panel, use the Enable Cache button to turn the caching feature on or off. Once enabled, configure the following cache settings:
   • Max Cached Items: Maximum number of cached entries per node. Default: 1,000,000.
   • Max Memory: Limit on cache memory usage. Default: 100 MB.
   • Cache TTL: Duration a cached entry remains valid. Default: 1 minute.
3. Click Update to apply the settings.

Monitor External Resource Cache Status

To view cache metrics and monitor usage in real-time, hover over the arrow next to External Resource Cache Settings and select External Resource Cache Status. A side panel will appear showing cache metrics.

The metrics include the following:

• Memory Usage: Total memory currently used by the cache.
• Cache Entries: Total number of stored cache results.
• Cache Hits: Number of times EMQX found a valid result in the cache, avoiding a call to the external backend.
  • Metrics shown: Current rate, 5-minute average, Maximum rate
• Cache Misses: Number of times EMQX looked for a result in the cache but didn’t find one, resulting in a backend query.
  • Metrics shown: Current rate, 5-minute average, Maximum rate
• Cache Inserts: Number of new results added to the cache after a miss.
  • Metrics shown: Current rate, 5-minute average, Maximum rate

You can refresh or reset the statistics using the buttons in the top-right corner of the panel.