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 against user.username.
• 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. The search operations find the user's DN and the bind operation authenticates by binding to the LDAP server with the submitted password. Privilege is determined by whether the user matches an admin-group filter, not by mapping a memberOf attribute — this ensures all group memberships are evaluated regardless of attribute ordering.

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

        # Find a user who is also a member of the admin group.
        search "FIND_ADMIN_USER" {
            base "ou=people,dc=example,dc=org";
            scope sub;
            filter "(&(uid=%{aaa.identity})(objectClass=inetOrgPerson)(memberOf=cn=radiator-admins,ou=groups,dc=example,dc=org))";

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

        # Fallback: find the user without group restriction.
        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;
            }
        }

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

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

        handler "AUTHENTICATION" {
            @execute {
                any {
                    # Admin path: user matches the admin group filter — grant full access.
                    all {
                        backend {
                            name "MGMT_LDAP";
                            query "FIND_ADMIN_USER";
                        }
                        modify user.privilege = "all";
                    }
                    # Non-admin path: any valid user — grant monitor access.
                    # Default to monitor: avoids exposing configurations
                    # that may contain credentials to non-admin users.
                    all {
                        backend {
                            name "MGMT_LDAP";
                            query "FIND_USER";
                        }
                        modify user.privilege = "monitor";
                    }
                }

                any {
                    http-management-authentication;
                    backend {
                        name "MGMT_LDAP";
                        query "BIND_USER";
                    }
                }
            }
        }
    }
}

Group membership is evaluated server-side via the LDAP filter, which correctly handles multi-valued memberOf attributes. Users not in radiator-admins default to monitor privilege.

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