update(authn): Add "Precondition" Dashboard config field

Author: Meggielqk

en_US/access-control/authn/assets/authn-MongoDB_ee.png

@@ -89,7 +89,7 @@ When an authentication chain is configured, EMQX processes authenticators in the
 Here’s how it works, using password-based authentication as an example:
 
 1. **Evaluate Preconditions (if configured):**
-   If the authenticator has a [precondition](#authenticator-preconditions), EMQX first evaluates the expression based on client information (e.g., `listener`, `clientid`, `username`).
+   If the authenticator has a [precondition](#authenticator-preconditions), EMQX first evaluates the expression based on client attributes information (e.g., `listener`, `clientid`, `username`).
    - If the expression evaluates to `true`, the authenticator is invoked.
    - If not, the authenticator is skipped.
 2. **Execute the Authenticator:**
@@ -106,11 +106,23 @@ Here’s how it works, using password-based authentication as an example:
 
 ### Authenticator Preconditions
 
-Starting from EMQX 5.9, you can assign a precondition to each authenticator to control whether it should be invoked for a given client.
+Starting from EMQX 5.9, you can assign a precondition to each authenticator to control whether it should be invoked for a given client. A precondition is a [Variform expression](../../configuration/configuration.md#variform-expressions) that evaluates client attributes (such as `listener`, `username`, `clientid`, etc.). If the expression does not evaluate to `true`, the authenticator is skipped.
 
-A precondition is a [Variform expression](../../configuration/configuration.md#variform-expressions) that evaluates client metadata (such as `listener`, `username`, `clientid`, etc.). If the expression does not evaluate to `true`, the authenticator is skipped.
+This feature enables conditional logic in the authentication chain. It allows for fine-grained control over authentication logic, such as applying different authenticators for clients connecting through different listeners or based on client attributes. EMQX can then invoke authenticators only when appropriate and avoid unnecessary requests to external systems.
 
-This feature enables conditional logic in the authentication chain, allowing EMQX to invoke authenticators only when appropriate and avoid unnecessary requests to external systems.
+#### Supported Client Attributes in Precondition
+
+Supported client attributes in a precondition include:
+
+- `username`: The username of the client
+- `password`: The password of the client
+- `clientid`: The client ID of the client
+- `client_attrs.*`: The client attributes of the client
+- `cert_common_name`: The subject field from the client's TLS certificate
+- `cert_subject`: The Common Name (CN) from the client's TLS certificate
+- `peersni`: The SNI (Server Name Indication) sent by the TLS client
+- `listener`: The listener ID (e.g. `tcp:default`)
+- `zone`: The associated config zone
 
 #### Precondition Examples
 

en_US/access-control/authn/assets/authn-built-in-database.png

@@ -10,18 +10,23 @@ Client-Info authentication (`cinfo` type) is a lightweight authentication mechan
 
 ## Configure Client-Info Authentication via Dashboard
 
-In the EMQX Dashboard, navigate to **Access Control** -> **Authentication** in the left menu to enter the **Authentication** page. 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.
-
-1. 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
-   - Select `allow`, `ignore`, or `deny` from the **Result** dropdown menu.
-2. Click **Create** to complete the authentication configuration.
+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](../../configuration/configuration.md#variform-expressions) 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](./authn.md#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
 

en_US/access-control/authn/assets/authn-http.png

@@ -63,36 +63,36 @@ Due to the lack of expressiveness, it has been redesigned to make use of HTTP bo
 
 You can use EMQX Dashboard to finish the relevant configuration.
 
-On [EMQX Dashboard](http://127.0.0.1:18083/#/authentication), click **Access Control** -> **Authentication** on the left navigation tree to enter the **Authentication** page. Click **Create** at the top right corner, then click to select **Password-Based** as **Mechanism**, and **HTTP Server** as **Backend**, this will lead us to the **Configuration** tab, as shown below.
+1. In the EMQX Dashboard, click **Access Control** -> **Authentication** from the left navigation menu.
+2. On the **Authentication** page, click **Create** in the top right corner.
+3. Click to select **Password-Based** as **Mechanism**, and **HTTP Server** as **Backend** to go to the **Configuration** tab, as shown below. 
 
 <img src="./assets/authn-http.png" alt="HTTP" style="zoom:67%;" />
 
-Follow the instructions below on how to configure the authentication:
+4. Follow the instructions below to configure the authentication backend:
 
-- **Method**: Select HTTP request method, optional values: `get`, `post`
+   - **Method**: Select HTTP request method, optional values: `get`, `post`
 
-  :::tip
+     :::tip
 
-  The `POST` method is recommended. When using the `GET` method, some sensitive information (such as plain text passwords) may be exposed via HTTP server logs. Also, for untrusted environments, please use HTTPS.
-   :::
+     The `POST` method is recommended. When using the `GET` method, some sensitive information (such as plain text passwords) may be exposed via HTTP server logs. Also, for untrusted environments, please use HTTPS.
+      :::
 
-- **URL**: Enter the URL address of the HTTP service.
-- **Headers** (optional): HTTP request header. You can add several headers. Keys and values support using [placeholders](./authn.md#authentication-placeholders).
-- **Enable TLS**: Turn on the toggle switch if you want to enable TLS. For more information on enabling TLS, see [Network and TLS](../../network/overview.md).
+   - **URL**: Enter the URL address of the HTTP service.
+   - **Precondition**: A [Variform expression](../../configuration/configuration.md#variform-expressions) used to control whether this HTTP Server 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](./authn.md#authentication-preconditions).
+   - **Headers** (optional): HTTP request header. You can add several headers. Keys and values support using [placeholders](./authn.md#authentication-placeholders).
+   - **Enable TLS**: Turn on the toggle switch if you want to enable TLS. For more information on enabling TLS, see [Network and TLS](../../network/overview.md).
+   - **Body**: Request template; for `POST` requests, it is sent as a JSON in the request body; for `GET` requests, it is encoded as a Query String in the URL. Mapping keys and values support using [placeholders](./authn.md#authentication-placeholders).
+   - **Advanced Settings**:
+     - **Pool size** (optional): Input an integer value to define the number of concurrent connections from an EMQX node to an HTTP server. Default: `8`. 
 
-- **Body**: Request template; for `POST` requests, it is sent as a JSON in the request body; for `GET` requests, it is encoded as a Query String in the URL. Mapping keys and values support using [placeholders](./authn.md#authentication-placeholders).
+     - **Connect Timeout** (optional): Specify the waiting period before EMQX assumes the connection is timed out. Units supported include milliseconds, second, minute, and hour.
 
-- **Advanced Settings**:
+     - **HTTP Pipelining** (optional): Input a positive integer to specify the maximum number of HTTP requests that can be sent without waiting for a response; default value: `100`.
 
-  - **Pool size** (optional): Input an integer value to define the number of concurrent connections from an EMQX node to an HTTP server. Default: `8`. 
+     - **Request Timeout** (optional): Specify the waiting period before EMQX assumes the request is timed out. Units supported include milliseconds, second, minute, and hour.
 
-  - **Connect Timeout** (optional): Specify the waiting period before EMQX assumes the connection is timed out. Units supported include milliseconds, second, minute, and hour.
-
-  - **HTTP Pipelining** (optional): Input a positive integer to specify the maximum number of HTTP requests that can be sent without waiting for a response; default value: `100`.
-
-  - **Request Timeout** (optional): Specify the waiting period before EMQX assumes the request is timed out. Units supported include milliseconds, second, minute, and hour.
-
-After you finish the settings, click **Create**.
+5. After you finish the settings, click **Create**.
 
 ## Configure with Configuration Items
 

en_US/access-control/authn/assets/authn-jwt.png

@@ -57,7 +57,7 @@ Example:
 
 1. Select **Access Control** -> **Authentication** from the left navigation menu. 
 
-2. On the **Authentication** page, click **Create** at the top right corner. Click to select **JWT** as **Mechanism**, and click **Next**. Skip the Backend selection and go to the **Configuration** tab. 
+2. On the **Authentication** page, click **Create** in the top right corner. Click to select **JWT** as the **Mechanism**, and click **Next**. Skip the Backend selection and go to the **Configuration** tab. 
 
    <img src="./assets/authn-jwt.png" alt="JWT" style="zoom:67%;" />
 
@@ -74,6 +74,7 @@ Example:
      - `public-key`: Uses a private key to generate the JWT's signature and a public key for verification. Supported algorithms are RS256, RS384, RS512, ES256, ES384, and ES512. Configuration must include:
         - `Public Key`: Specify the public key in PEM format used to verify the signature.
 
+   - **Precondition**: A [Variform expression](../../configuration/configuration.md#variform-expressions) used to control whether this JWT 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](./authn.md#authentication-preconditions).
    - **Disconnect After Expiration**: Configures whether to disconnect clients after their JWT expires, enabled by default.
    - **Payload**: Specify additional claims checks that the user wants to perform. Users can define multiple key-value pairs with the **Claim** and **Expacted Value** fields, where the key is used to find the corresponding claim in the JWT, so it needs to have the same name as the JWT claim to be checked, and the value is used to compare with the actual value of the claim. Currently, the placeholders supported are `${clientid}` and `${username}`. 
 

en_US/access-control/authn/assets/authn-ldap.png

@@ -56,23 +56,30 @@ To configure the Kerberos authenticator, you need a running KDC (Key Distributio
 
 EMQX can only support keytab files at the default location. You can configure the system default value by using the environment variable `KRB5_KTNAME` or by setting `default_keytab_name` in `/etc/krb5.conf`.
 
-## Configure via Dashboard
+::: tip Note
 
-In the EMQX Dashboard, navigate to **Access Control** -> **Authentication** in the left menu to enter the **Authentication** page. Click **Create** at the top right corner, then select **GSSAPI** as the **Mechanism**, and **Kerberos** as the **Backend**. Click **Next** to go to the **Configuration** step.
+The keytab file `/etc/krb5.conf` must be located on the EMQX nodes, and the user running the EMQX service must have read permissions for the file.
 
-1. Configure the following fields:
+:::
 
-   - **Principal**: Set Kerberos principal for the server to define the server's identity within the Kerberos authentication system. For example, `mqtt/[email protected]`. 
+## Configure via Dashboard
 
-     Note: The realm in use must be configured in `/etc/krb5.conf` on EMQX nodes.
+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 **GSSAPI** as the **Mechanism**, and **Kerberos** as the **Backend**.
 
-   - **Keytab File**: Specify the path to the Kerberos keytab file.
+3. Click **Next** to go to the **Configuration** step.
 
-     Note: The keytab file must be located on the EMQX nodes, and the user running the EMQX service must have read permissions for the file.
+4. Configure the following fields:
+
+   - **Principal**: Set Kerberos principal for the server to define the server's identity within the Kerberos authentication system. For example, `mqtt/[email protected]`. 
+
+     Note: The realm in use must be configured in `/etc/krb5.conf` on EMQX nodes.
+   
+   - **Precondition**: A [Variform expression](../../configuration/configuration.md#variform-expressions) used to control whether this Kerberos 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](./authn.md#authentication-preconditions).
 
 
-2. Click **Create** to complete the configuration.
+5. Click **Create** to complete the configuration.
 
 ## Configure via Configuration Items