Client-Info Authentication

Client-Info authentication (cinfo type) is a lightweight authentication mechanism that verifies client properties and attributes against user-defined rules. These rules make use of the Variform expressions to define matching conditions and determine the authentication outcome when a match is found. For example, to quickly block clients without a username, you can use the condition str_eq(username, '') with a result of deny.

Configure Client-Info Authentication via Dashboard

1. In the EMQX Dashboard, navigate to Access Control -> Authentication in the left menu to enter the Authentication page.
2. Click Create at the top right corner, then select Client Info as the Mechanism. Client-Info authentication does not require selecting a backend, so you can proceed by clicking Next to enter the Configure Parameters step.
3. Follow the instructions below to configure the backend:
   • Precondition: A Variform expression used to control whether this Client Info authenticator should be applied to a client connection. The expression is evaluated against attributes from the client (such as username, clientid, listener, etc.). The authenticator will only be invoked if the expression evaluates to the string "true". Otherwise, it will be skipped. For more information about the precondition, see Authentication Preconditions.
   • Click Add in the Checks.
     • In the Match Conditions input box, enter the Variform expression used to match client information. If there are multiple expressions, enter each on a new line. When all expressions return true, the authenticator will return the relevant result; otherwise, the current check will be skipped. The following variables are supported in the expressions:
       • username: Username
       • clientid: Client ID
       • client_attrs.*: Client Attributes
       • peerhost: Client IP
       • cert_subject: TLS Certificate Subject
       • cert_common_name: TLS Certificate Common Name
     • From the Result dropdown menu, select the result to return if the match condition is true:
       • allow: Allow the client to connect.
       • ignore: Defer the authentication to the next authenticator in the chain.
       • deny: Deny the client to connect.
4. Click Create to complete the authentication configuration.

Configure Client-Info Authentication via Configuration Items

Below is a configuration example for the Client-Info authenticator:

authentication = [
  {
    mechanism = cinfo
    checks = [
      # Allow clients with a username starts with 'super-'
      {
        is_match = "regex_match(username, '^super-.+$')"
        result = allow
      },
      # Deny clients with an empty username and client ID starts with 'v1-'
      {
        # when is_match is an array, it returns 'true' if all checks evaluate to 'true'
        is_match = ["str_eq(username, '')", "str_eq(nth(1,tokens(clientid,'-')), 'v1')"]
        result = deny
      }
      # If all checks are exhausted without an 'allow' or a 'deny' result, proceed to the next authenticator
    ]
  },
  # ... more authenticators ...
  # ...
  # If all authenticators are exhausted without an 'allow' or a 'deny' result, the client is rejected
]

More match expression examples:

• Match all clients: true.
• Match clients where the TLS certificate common name matches the username: str_eq(cert_common_name, username)
• Match clients whose password is the sha1 hash of the environment variable EMQXVAR_SECRET concatenated with the client ID:str_eq(password, hash(sha1, concat([clientid, getenv('SECRET')])))
• Match clients whose attribute client_attrs.group is not g0: str_neq(client_attrs.group, 'g0')
• Match client IDs that start with the zone name:regex_match(clientid, concat(['^', zone, '.+$']))