jsonfile

The JSON file backend allows Radiator to authenticate users against a JSON formatted text file. The JSON file can be queried using the jsonpath filter to extract user credentials and attributes.

The jsonfile JSON parser supports the JSON5 superset of JSON, allowing comments, trailing commas, and other usability improvements.

Here's an example configuration of a JSON file backend with comments explaining each statement:

jsonfile "JSON_FILE" {
    # Path to the JSON file containing user data.
    filename "users.json5";

    # Enable file monitoring for changes. Defaults to true.
    monitor true;

    # Alternatively it is possible to define the JSON content directly in the configuration.
    # Not allowed if filename is used.
    content """
        {
            "users": {
                // Comments are allowed in JSON
                "alice": {
                    "username": "alice",
                    "password": "{argon2}$argon2id$v=19$m=19456,t=2,p=1$56MJ6kkHsbicXkvq6+r5dA$zY5kHLjEfJET8VT7hFV+uHcxgTE8w66Z4dYwwbZtdxw",
                    "groups": ["admin", "user"]
                },
            }, // dangling comma is allowed
        }
    """;

    # At least one query block must be defined
    query "FIND_USER" {
        # Mapping provides access to a single variable, `doc` which is the parsed JSON document.
        mapping {
            user.username = doc | jsonpath("$.users['%{aaa.identity}'].username");
            user.password = doc | jsonpath("$.users['%{aaa.identity}'].password");
            user.group = doc | jsonpath("$.users['%{aaa.identity}'].groups[*]");

            # It is also possible to extract the user data object and filter it further in the policy.
            vars.full_userdata = doc | jsonpath("$.users['%{aaa.identity}']");
        }
    }

    # And inside your backend action you need to give the name and query
    # to use. For example:
    authentication {
        backend {
            name "JSON_FILE";
            query "FIND_USER";
        }
    }
}

Rejecting

The backend rejects when all mapping expressions return none. If at least one expression returns a value, the backend accepts. More fine grained control of rejections should be done in the policy.

Automatic monitoring of changes

When enabling monitor true Radiator checks for changes in the file and reloads it. This happens usually within one second of last change. If the file changes to invalid JSON, the backend will keep serving the last valid content (until a restart).

The JSON file is read into memory resulting in high performance lookups.

On a typical computer read times of of the json file is over 100k lines per second. Processing of requests does not stop while a file is being read in, but one core is consumed for reading the file.

Radiator monitors the whole directory where the file is located to detect addition of a file to be able detect when the file is created and not just modified. Writing logs or editing files in the directory being watched will have a performance impact. It is recommended to separate these activities to different directories and to use mv or move to move the final file to production directory.

Do not modify/replace the file while it is being read. Prefer batching (aggregated) updates at regular intervals over frequent small changes for more consistent and reliable performance.