HTTP Authorization

EMQX supports authorization based on HTTP applications. In this scenario, users need to set up an external HTTP application as a data source, and EMQX will make requests to the HTTP service and determine the authorization result based on the data returned by the HTTP API, thereby implementing complex authorization logic.

Note

HTTP authorization is not supported in EMQX Serverless deployments.

How HTTP Authorization Works

The authorization process resembles an HTTP API call, where EMQX, acting as the request client, needs to construct and send a request to the HTTP service according to the "API" requirements. The HTTP service must return results according to the "client's" requirements:

• The response content-type must be application/json.
• The authorization result is indicated by result in the body, with possible values allow, deny.
• If the returned HTTP status code is 204, the authorization result is considered to allow publishing or subscribing.
• If the HTTP status code is 200 but the response body is not in the expected format (for example, the result field is missing or its value is neither allow nor deny), the authorization outcome will be treated as ignore. When whitelist mode is not enabled, the client will be allowed to publish and subscribe to any topics, which may lead to unauthorized access and potential data exposure.
• Any other HTTP status code apart from 200 and 204 is considered as ignore, for example, when the HTTP service is unavailable or the authentication endpoint returns an unexpected response, if whitelist mode is not enabled, clients will be allowed to publish and subscribe to any topics. This may result in unauthorized access and potential data exposure.

Response example:

HTTP/1.1 200 OK
Headers: Content-Type: application/json
...
Body:
{
    "result": "allow" | "deny" 
}

Configure HTTP Authorization

In the deployment, click Access Control -> Authorization -> Extended Authorization, select HTTP Authorization, and click Configure.

For identity authorization, EMQX Cloud will use the current client information to fill in and initiate the authorization query request configured by the user, querying the client's authorization data on the HTTP server side.

You can complete the related configuration according to the following instructions:

• Method: Choose the HTTP request method, options: get, post.

  TIP

  The POST method is recommended. When using the GET method, some sensitive information (such as plaintext passwords) might be exposed through HTTP server logs. Additionally, for untrusted environments, use HTTPS.

• URL: Enter the URL address of the HTTP service.

  • The URL address must start either with http:// or https://.
  • Avoid using placeholders in the domain name.
  • You can use the following placeholders in the URL path:
    • ${clientid}
    • ${username}
    • ${password}
    • ${peerhost}
    • ${cert_subject}
    • ${cert_common_name}

• Headers (optional): Configuration for HTTP request headers. Multiple headers can be added.

• OAuth2 Client Credentials (optional): Enable OAuth2 Client Credentials if the external HTTP authorization service requires EMQX to authenticate before sending authorization requests. This option is available only for deployments running EMQX v6.1.4 or later. For details, see Configure OAuth2 Client Credentials.

• Connection Configurations: Configure concurrent connections, connection timeout waiting time, maximum HTTP request count, and request timeout time in this section.

• Enable TLS: Configure whether to enable TLS.

• Connection Pool size (optional): An integer specifying the concurrent connection count from EMQX nodes to the external HTTP Server; default value: 8.

• Connection Timeout (optional): Enter the connection timeout duration, with units available: hours, minutes, seconds, milliseconds.

• HTTP Pipelining (optional): A positive integer specifying the maximum number of HTTP requests that can be sent without waiting for responses; default value: 100.

• Request Timeout (optional): Enter the connection timeout duration, with units available: hours, minutes, seconds, milliseconds.

• Body: The request template. POST requests are sent in JSON format in the request body. GET requests are encoded as query parameters in the URL. Mapping keys and values can use placeholders.

TIP

• If the current deployment is a Dedicated Flex edition, a VPC Peering Connection needs to be created, and the server address should be the internal network address.
• If the current deployment is a BYOC edition, a VPC Peering Connection needs to be created in your public cloud console, please refer to the Creating BYOC Deployment - VPC Peering Connection Configuration section. The server address should be the internal network address.
• If you encounter an Init resource failure! please check whether the server address is correct and whether the security group is open.

HTTP Request and Response

When the client initiates a subscribing or publishing operation, the HTTP Authorizer constructs and sends a request based on the configured request template. You need to implement authorization logic in the request template and make sure that the checking results are returned in the required format.

Request

The request can use JSON format, with the following placeholders in the URL and request body:

• ${clientid}: The client ID
• ${username}: The username used by the client on login
• ${peerhost}: The source IP address of the client
• ${proto_name}: The protocol name used by the client, e.g. MQTT, CoAP
• ${mountpoint}: The mount point of the gateway listener (topic prefix)
• ${action}: The action being requested, e.g. publish, subscribe
• ${topic}: The topic (or topic filter) to be published or subscribed in the current request
• ${qos}: The QoS of the message to be published or subscribed in the current request
• ${retain}: Whether the message to be published in the current request is a retained message

Response

After checking, the authorization service needs to return a response in the following format:

• Response content-type must be application/json.
• If the HTTP Status Code is 200, the authorization result is granted by the HTTP Body. It depends on the value of the result field:
  • allow: Allow Publish or Subscribe.
  • deny: Deny Publish or Subscribe.
• If the HTTP Status Code is 204, it means that this Publish or Subscribe request is allowed.
• Any HTTP status code other than 200 or 204 will be treated as "ignore". For example, when the HTTP service is unavailable or the authentication endpoint returns an unexpected response, if whitelist mode is not enabled, clients will be allowed to publish and subscribe to any topics. This may result in unauthorized access and potential data exposure. Example response:

HTTP/1.1 200 OK
Headers: Content-Type: application/json
...
Body:
{
    "result": "allow" | "deny" 
}

TIP

It is recommended to use the POST method. When using the GET method, some sensitive information may be exposed through HTTP server logs.

For untrusted environments, HTTPS should be used.

Configure OAuth2 Client Credentials

For deployments running EMQX v6.1.4 or later, HTTP authorization supports OAuth2 Client Credentials. When this option is enabled, EMQX obtains, caches, and automatically refreshes an access token from the configured token endpoint. When EMQX sends a request to the external HTTP authorization service, it adds the token to the request as the Authorization: Bearer <access_token> header.

Enable OAuth2 Client Credentials, and configure the following options:

Field	Description
Token Endpoint	Required. OAuth2 authorization server endpoint used to request an access token. The URL must use HTTP or HTTPS and must not contain user information.
Client ID	Required. OAuth2 client ID used to request an access token.
Client Secret	Required. OAuth2 client secret used to request an access token.
Scope	Optional OAuth2 scope requested for the access token.
Token Request Timeout	Timeout for the HTTP request to the token endpoint. The default is 5 seconds.
Token Endpoint TLS	Enables TLS for the token endpoint. This setting is independent of Enable TLS, which controls the connection to the external HTTP authorization service.

EMQX sends a POST request with the application/x-www-form-urlencoded content type to the token endpoint. The request body contains grant_type, client_id, client_secret, and the optional scope. The token endpoint must return a 200 response with a JSON body that contains an access_token. It can also return token_type and expires_in. If present, token_type must be Bearer, and expires_in must be a positive integer.

Important Notice

• Do not configure an Authorization header for HTTP authorization when OAuth2 is enabled. EMQX rejects the configuration because it conflicts with the automatically generated Bearer authorization header.
• The token endpoint must accept the client ID and client secret as form fields in the request body. Authenticating to the token endpoint with an HTTP Basic Authorization header is not supported.