management

The management clause configures the built-in management interface that exposes operational and configuration management capabilities over HTTP or HTTPS. This includes the REST API and the optional web UI.

management {
    http {
        listen {
            protocol tls;
            port 8443;
            ip 127.0.0.1;

            tls {
                certificate "MGMT_CERT";
                certificate_key "MGMT_KEY";
                require_client_certificate false;
            }
        }
        clients "MGMT_CLIENTS";
        policy "MANAGEMENT";
    }
}

Keep the management interface restricted (bind to 127.0.0.1 or a dedicated administrative network segment, and use TLS in production).

Listener Configuration

The listen block controls where the management interface binds.

IP Access Control

The clients statement inside the http block references a named HTTP client list defined in the top-level clients clause. When set, only connections from matching IP addresses are accepted. Connections from unlisted addresses are rejected at the TCP level — the connection is dropped without sending an HTTP response.

The clients filter is an application-level control and not a substitute for network-level security. Use a firewall rule to restrict access to the management port as the primary defense, and treat clients as an additional layer.

clients {
    http "MGMT_CLIENTS" {
        client "admin-network" {
            source {
                ip 192.168.1.0/24;
                ip 10.0.0.0/8;
            }
        }

        client "localhost" {
            source {
                ip 127.0.0.1;
                ip ::1;
            }
        }
    }
}

management {
    http {
        clients "MGMT_CLIENTS";
        # ...
    }
}

TLS

To serve HTTPS:

1. Set protocol tls in the listen block.
2. Add a tls block inside listen referencing a certificate and key defined in the global certificates clause.

Certificate and key files can be uploaded individually or as part of a configuration package — see Configuration Import and Export.

listen {
    protocol tls;
    port 8443;
    ip 127.0.0.1;

    tls {
        certificate "MGMT_CERT";
        certificate_key "MGMT_KEY";
        require_client_certificate false;
    }
}

Disabling Features

Use no statements inside the management block to disable specific features.

management {
    no ui;
    http {
        # ...
    }
}

Privilege Model

Each authenticated user is assigned a privilege level that determines which API endpoints and UI operations they can access. Privileges are hierarchical -- a higher level includes all capabilities of lower levels.

If an endpoint requires higher privilege than provided, the request is rejected with a 403 response.

For a detailed breakdown of each privilege level and which API endpoints they control, see Management API Privileges.

Management Authentication Policies

Authentication and authorization are handled by an AAA policy referenced with the policy statement inside the http block, see execution pipelines for details.

1. A management HTTP request arrives (API call or web UI login).
2. The policy's conditions block matches on http.management == true.
3. The handler's @execute block runs the authentication logic:
   • Look up the user in a backend (SQL, LDAP, HTTP, JSON file).
   • Set user.privilege based on backend data or custom rules.
   • Call http-management-authentication to verify credentials against an existing session cookie or HTTP Basic Auth header.
4. On success, the request proceeds. On failure, a 401 or 403 response is returned.

http-management-authentication Action

This built-in action handles HTTP Basic Auth and cookie-based sessions:

• If an Authorization: Basic header is present, it verifies the submitted password against user.password in the AAA context. The backend query must have populated user.password before this action runs — the same requirement as pap.
• If no basic auth header is present but a session cookie exists, it validates the session directly against the session store. The stored username is propagated into user.username if it is not already set. No prior backend lookup is required for session validation.
• This action does not create session cookies. Session lifecycle (login, refresh, logout) is handled by the /auth/login and related endpoints.

Use this action inside an any { } block to try session auth before falling back to a backend bind or other authentication method.

Example: JSON File Authentication

Authenticate management users against a JSON file. The backend query maps user.username, user.password, and user.privilege from the file.

backends {
    jsonfile "MGMT_USERS" {
        filename "users.json";

        query "FIND_USER" {
            mapping {
                user.username = doc | jsonpath("$.users[?(@.username == '%{aaa.identity}')].username");
                user.password = doc | jsonpath("$.users[?(@.username == '%{aaa.identity}')].password");
                user.privilege = doc | jsonpath("$.users[?(@.username == '%{aaa.identity}')].privilege");
            }
        }
    }
}

aaa {
    policy "MANAGEMENT" {
        conditions all {
            http.management == true;
        }

        handler "AUTHENTICATION" {
            @execute {
                backend {
                    name "MGMT_USERS";
                    query "FIND_USER";
                }

                http-management-authentication;
            }
        }
    }
}

The JSON file must contain user objects with username, password, and privilege fields. See Password Hashing for supported hash formats.

Example: LDAP Authentication

Authenticate management users against an LDAP directory. A single search retrieves the user's DN and all group memberships in one round-trip. Privilege is then assigned in the policy based on whether the admin group DN appears in vars.member_of.

backends {
    ldap "MGMT_LDAP" {
        server "ldap-server" {
            url "ldaps://ldap.example.com/";
            timeout 3s;
            authentication {
                dn "cn=radiator-svc,ou=service-accounts,dc=example,dc=org";
                password "servicepassword";
            }
        }

        # Find the user and collect all group memberships in a single search.
        search "FIND_USER" {
            base "ou=people,dc=example,dc=org";
            scope sub;
            filter "(&(uid=%{aaa.identity})(objectClass=inetOrgPerson))";

            mapping {
                vars.dn = entry::dn;
                user.username = uid;
                vars.member_of += memberOf;
            }
        }

        bind "BIND_USER" {
            dn vars.dn;
            password http.authorization.password;
        }
    }
}

aaa {
    policy "MANAGEMENT" {
        conditions all {
            http.management == true;
        }

        handler "AUTHENTICATION" {
            @execute {
                backend {
                    name "MGMT_LDAP";
                    query "FIND_USER";
                }

                # Check group membership and assign privilege.
                # vars.member_of is multi-valued; == matches if any item is an exact match.
                # Default to monitor: avoids exposing configurations
                # that may contain credentials to non-admin users.
                if any {
                    vars.member_of == "CN=radiator-admins,OU=groups,DC=example,DC=org";
                } then {
                    modify { user.privilege = "all"; }
                } else {
                    modify { user.privilege = "monitor"; }
                }

                any {
                    # Session auth: validates the cookie directly — no additional LDAP lookup for
                    # validation; earlier LDAP queries may still be used to populate attributes/privileges.
                    http-management-authentication;
                    # Basic auth fallback: bind to LDAP with the submitted password.
                    backend {
                        name "MGMT_LDAP";
                        query "BIND_USER";
                    }
                }
            }
        }
    }
}

vars.member_of += memberOf accumulates all values of the multi-valued memberOf attribute into a list. The == condition checks whether any item in the list matches the admin group DN exactly, including the full OU path. The comparison is case-sensitive, so the DN in the condition must match the case returned by the LDAP server.

Active Directory note: AD does not populate the uid attribute by default. When connecting to an AD domain controller, replace both occurrences of uid with sAMAccountName:

filter "(&(sAMAccountName=%{aaa.identity})(objectClass=user))";
mapping {
    vars.dn = entry::dn;
    user.username = sAMAccountName;
    vars.member_of += memberOf;
}

Without user.username = sAMAccountName, the mapping leaves user.username empty. Login (POST /api/v1/auth/login) will return an error indicating that user.username is empty — check the server log for the exact attribute name to use.

Audit Logging

Add audit logging to management authentication using the @final-execute block.

handler "AUTHENTICATION" {
    @execute {
        # ... authentication logic ...
    }

    @final-execute {
        log "MANAGEMENT" {
            json {
                "User-Name" aaa.identity;
                "Reason" aaa.reason;
                "Result" "%{aaa.result}";
                "Method" http.method;
                "Path" http.path;
                "Code" http.status;
                "Ip" http.client.ip;
            }
        }
    }
}

Legacy: Credentials Block

The credentials block is supported for backward compatibility. For production deployments, use policy-based authentication instead.

When policy is not set, the management interface falls back to the credentials block. It supports static user definitions and backend references directly inside the http block.

management {
    http {
        listen {
            protocol tls;
            port 8443;
            ip 127.0.0.1;

            tls {
                certificate "MGMT_CERT";
                certificate_key "MGMT_KEY";
                require_client_certificate false;
            }
        }

        credentials {
            user "admin" {
                password "{argon2}$argon2id$v=19$m=65536,t=3,p=4$c29tZXNhbHQ$RdescudvJCsgt3ub+b+dWRWJTmaaJObG";
                privilege all;
            }
            user "monitor" {
                password "{argon2}$argon2id$v=19$m=65536,t=3,p=4$c29tZXNhbHQ$RdescudvJCsgt3ub+b+dWRWJTmaaJObG";
                privilege monitor;
            }
        }
    }
}

Each user block requires password and privilege (any privilege level from the Privilege Model above; use all for administrators). Passwords can be plain text or hashed with {argon2} or {crypt-sha256} prefixes — argon2 is recommended. See Password Hashing for how to generate hashes.

Authentication Order

For each incoming request, the credentials block authenticates as follows:

1. Session cookie — if a valid session cookie is present and matches the username, the request is accepted immediately without checking credentials.
2. Static users — the username from the Authorization: Basic header is looked up in the user blocks. If a matching entry is found, the password is verified. If it matches, the request is accepted with that user's privilege.
3. Backends — only reached if no matching static user was found. Backends are queried in alphabetical order by name. The first backend that returns a user with a non-empty username and a password is used to verify the submitted password. Remaining backends are not queried once a match is found.

If none of the above steps succeed, the request is rejected with a 401 response.

Related

• Management API Privileges - Detailed breakdown of privilege levels and which endpoints they control
• Health check /live and /ready - Health check endpoints served by the management interface
• Configuration Import and Export - How to upload certificates and configuration packages
• ui - Web UI customization (sidebar navigation)
• certificates - TLS certificate configuration