# Access Control {{since('2026.03.04-bb93ecb1')}} This section describes how Access Control is implemented within KumoMTA. There are three related parts to access control: * Authentication - deciding the identity of a session, which may be based on factors such as the peer address or an explicit credential exchanged as part of SMTP or HTTP authentication. * Authorization - deciding whether the session is allowed to perform some action on a resource based on their identity and the configured Access Control List for that resource. * Accounting - tracking the disposition of each authorization check for later review These three areas are known collectively as **Authentication, Authorization and Accounting**, or more succinctly as **AAA**. ## Authentication Each session into the server has an associated [AuthInfo](kumo.aaa/auth_info.md) object that records the authentication state. It holds at least the following information: * The peer address - the IP address that is connecting to the server * A list of identities - for instance, the SMTP or HTTP auth username if auth was successfully processed. If the list is empty we consider the session to be *Unauthenticated*. If the list has at least one identity we consider the session to be *Authenticated*. * A list of group names - These may be established as part of authenticating the session, and in some cases, may be special pre-set groups assigned based on the peer address being present in the set of *trusted hosts* for the associated listener. ### HTTP Authentication HTTP sessions are authenticated via the [http_server_validate_auth_basic](events/http_server_validate_auth_basic.md) event. If that event returns `true` then the `username` parameter is added to the list of identities in the `AuthInfo`. Alternatively, the event can directly return an `AuthInfo` to provide additional authentication information. ### SMTP Authentication SMTP sessions are authenticated via the [smtp_server_auth_plain](events/smtp_server_auth_plain.md) event. If that event returns `true` then the `authz` AND `authc` identities are both added to the list of identities in the `AuthInfo`. Alternatively, the event can directly return an `AuthInfo` to provide additional authentication information. ## Authorization Authorization is the process of deciding whether a particular type of access is permitted to happen to a particular resource. In KumoMTA we encode authorization rules into an *Access Control List* (ACL) for the resource. To aid in the definition of ACLs, a resource has an associated hierarchy and can inherit ACLs from its parent/lineage in that hierarchy. The following terms apply to authorization: * `resource` - a string that identifies the resource. For example, it may be a string that corresponds to an HTTP API endpoint. * `privilege` - a string describing the nature of access that is desired. For example, it may be `POST` to indicate an HTTP post request is being attempted, but it could be a more abstract privilege defined by the logic that gates access to the resource. * `criteria` - an expression term that is used to define when an ACL rule applies. For example, it might be "members of a specific named group". * `rule` - A combination of `privilege`, `criteria` and an access level that defines the access permitted for that combination of privilege and criteria. * `ACL` - An Access Control List, which is an ordered sequence of rules that apply to a specific resource. When deciding whether access is permitted, the system will determine the resource that is to be accessed and then attempt to resolve the ACL for that resource. This is carried out via the [get_acl_definition](events/get_acl_definition.md) event, with a fall back to a built in default ACL (which you can disable if you wish via [kumo.aaa.set_fall_back_to_acl_map](kumo.aaa/set_fall_back_to_acl_map.md)). Each rule in the returned ACL is considered (in the order in which they were defined in the ACL) and compared against the `AuthInfo` for the session. If the `criteria` and `privilege` in the rule match then the access level defined by the rule is taken as the definitive outcome and authorization checking stops there at the first matching rule. If no rules from the ACL match, then the parent resource of the current resource is determined and its ACL is resolved, again evaluating its rules one by one until a match is found. If no matching rules were found, the parent resource of this resource is resolved and the process is repeated until there are no more parent resources. At that point the disposition is that access is **denied by default**. ### HTTP Resources Access to HTTP API endpoints is decided by an initial authorization check in the HTTP request routing layer based on the endpoint URL, HTTP method (which is mapped to the `privilege`) and auth info in the current HTTP session. When the AuthInfo for the HTTP session is instantiated and if the peer IP address matches the [start_http_listener.trusted_hosts](kumo/start_http_listener/trusted_hosts.md) option then the built-in group `kumomta:http-listener-trusted-ip` is added to the list of groups. Rather than directly taking the HTTP URI from the request as the resource name, the resource name is produced by re-composing the request elements. For a URL like `http://localhost:8080/foo/bar/baz`: * The host portion of the request (`localhost:8080`) is ignored * The *listen* address of the listener (as per [start_http_listener.listen](kumo/start_http_listener/listen.md)) on which the request was received is used to decide which http listener is being accessed. For the sake of this example, let's assume that it is `127.0.0.1:8080`. * The HTTP request path is combined with the listen address to make a resource path of the form `http_listener/127.0.0.1:8080/foo/bar/baz` The inheritance hierarchy for such a resource is shown below, with the first of these being checked first and so on: * `http_listener/127.0.0.1:8080/foo/bar/baz` * `http_listener/127.0.0.1:8080/foo/bar` * `http_listener/127.0.0.1:8080/foo` * `http_listener/127.0.0.1:8080` * `http_listener/*/foo/bar/baz` * `http_listener/*/foo/bar` * `http_listener/*/foo` * `http_listener` Notice that the path is traversed similarly to a filesystem path, but when we reach the listener address (`http_listener/127.0.0.1:8080`) the next step is the full resource path underneath a special `*` resource location (`http_listener/*/foo/bar/baz`) which is consulted regardless of the listener address. Ultimately an HTTP access is checked against the logical `http_listener` resource which can be used to encode a general access rule if required. To illustrate how this works, the product default ACLs allow `GET`, `DELETE` and `POST` access to members of the group `kumomta:http-listener-trusted-ip` for the resource `http_listener/*/api/admin`. Since all admin API endpoints fall under this particular resource path, that one rule definition applies to all admin API endpoints on all http listeners that may have been defined in the product, with the effect being that any IP in the list of trusted hosts for the listener is permitted to make admin API requests. ### Defining ACLs If you wish to define your own ACLs then the recommended way is to deploy an ACL map file to the system and configure it as shown in [Augmenting the default ACL](events/get_acl_definition.md#augmenting-the-default-acl) or [Replacing the default ACL](events/get_acl_definition.md#replacing-the-default-acl). The documentation for [kumo.aaa.load_acl_map](kumo.aaa/load_acl_map.md) describes the syntax of an ACL map file and includes a copy of the default ACL map file. It is also possible to dynamically load ACLs from other data sources, or compute them dynamically, and that is demonstrated in [Advanced ACL Building](events/get_acl_definition.md#advanced-acl-building). ## Accounting You may enable and configure logging to an accounting log using [kumo.aaa.configure_acct_log](kumo.aaa/configure_acct_log.md). The accounting log configuration is similar to the delivery log configuration, except that authentication and authorization events are logged rather than delivery information. You can choose whether to include or exclude successful or failing authentication or authorization events.