Extended Authentication

Extended authentication enables users to utilize their own services for authentication, supporting external databases such as MySQL and Redis as data sources, or connecting to HTTP services for authentication.

Note

Extended authentication is not supported in EMQX Serverless deployments.

Extended Authentication Data Sources

HTTP Authentication

MySQL Authentication

PostgreSQL Authentication

Redis Authentication

JWT Authentication

TIP

A maximum of two extended authentication data sources can be created.

Authentication Order

After adding extended authentication data sources, you can sort the authentication sources. The deployment will authenticate in the order from left to right, with the default authentication chain order being default authentication -> extended authentication.

• If authentication succeeds, the authentication chain is terminated, and the client is allowed to connect.
• If authentication fails, the authentication chain is terminated, and the client is denied access.
• If the current data source does not match, it moves to the next authentication source for authentication.

How to Create an Authentication Chain

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

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

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 authentication results retrieved from external backends, such as MySQL or Redis. This cache is designed to improve the performance of authentication 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 password authentication (default), EMQX Platform does not use this cache.

How External Resource Cache Works

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

1. A client connects and triggers authentication.
2. EMQX Platform 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 -> Authentication -> Extended Authentication page in your deployment. Once an extended authentication 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.