General configuration

Citadel can be configured by placing a file called citadel-config.json containing a JSON object, in the directory where the citadel-browser-agent binary lives. The system checks for changes in the configuration every hour, and will automatically detect if you have modified the configuration file, and reload it.

For security reasons, Citadel wll refuse to load configuration that is not owned by root/wheel (macOS) or Administrator / SYSTEM (Windows), or that is world-writable.

overriding attributes

When overriding default settings in the JSON configuration file, the following rules are used:

• any new attribute : attribute is added
• existing value attribute : value is replaced
• existing array attribute : array is replaced
• existing object attribute : merged hierarchically, using the above rules

Note This means that:

• adding an attribute means just stating it
• adding a value to a list / array means restating the entire list

specifying domains

The following attributes specify lists of domains:

• domain.unhash
• company.domains
• company.applications
• session.domains
• session.exceptions
• domain.sensitive
• domain.publicMail
• device.exceptions.domains
• account.exceptions.domains
• account.mfa.required
• account.mfa.exceptions

Where specifying domain.com matches:

• domain.com
• host.domain.com
• host.subdomain.com

It is also possible to specify netmasks, for example:

• 192.168.x.x
• 10.x.x.x Netmasks can only be classful CIDR masks of type A,B or C. So 134.x.50.x is not allowed.

You can use * to specify “any domain”, but not anywhere else, like app-*.domain.com or even *.domain.com.

exceptions

You can override the global configuration for specific domains or netmasks. This is possible for the following configuration elements:

• warningProtocols : ex. allow HTTP on the VPN subnet
• account : ex. specific password policies for one application
• application : ex. specific retention period
• logging : ex. turn off logging for the development instances
• errors : ex. do not log certificate issues for your development web servers

For example, to ignore warnings about HTTP traffic over your VPN, you can override the warningProtocols setting:

    ...
    "exceptions": [
        {
          "description" : "unencrypted traffic is allowed over VPN",
          "domains": ["yourcompany.lan", "yourcompany.local"],
          "config": {
            "warningProtocols": ["ftp:", "ws:"]
          }
        }
    ]
    ...

Or you can disable password policy enforcement of external domains for specific domains. A typical example would be domains that are part of your protected scope but that are shared, such as accounts.google.com or login.microsoftonline.com:

    ...
    "exceptions": [
        {
          "description" : "do not apply password policy to external domains",
          "domains": ["accounts.google.com"],
          "config": {
            "account": {
              "checkOnlyInternal": true
            }
          }
        }
    ]
    ...

Any exceptions you defined are applied “on top of” the default configuration, in the order that they are defined.

For example, if you define a logging.logLevel in two exceptions :

• default : logging.logLevel = DEBUG
• exception 1 :["domain-a.com", "domain-b.com"] = WARN
• exception 2 : ["domain-a.com"] = ERROR

Then resulting logging.logLevel will depend on the domain involved:

• www.randomdomain.com : DEBUG (default)
• www.domain-a.com : ERROR (exception 2)
• www.domain-b.com : WARN (exception 1)