Configuration

Learn how to write a Zero Assumptions configuration file in UCL or JSON.

Zero Assumption is set up using a configuration file or multiple configuration files. Configuration enables the control plane to start.

Configuration supports JSON and UCL (Universal Configuration Language).

Zero Assumptions supports both using a single configuration files or multiple files linked to one another.

• When using a single configuration file, specify the file name.
• When using multiple configuration files, specify the configuration folder name. The server handles overlaying files on top of each other in lexicographical order.

Configuration Validation

Configuration files get merged by libucl and are then parsed into the internal representation when the control plane starts.

Configuration Fields

All fields are also configurable via the admin UI, except for services.

• services (required): An object that defines the coordinator and identity. All values within the services object can only be changed through the configuration file, and not through the admin UI.
  • coordinator (required): An object that defines the coordinator service.
    • dsn (required): A string value that defines the database credentials as a connection URI.
    • overlay_subnet (optional): A string value that defines which subnet to use for the overlay network. Default value is 172.24.0.0/16. The default value can be changed, though the application must be restarted when the value is changed. The subnet value can only be 16 or less.
    • public_url (required): A string value that defines the URL where the control plane is exposed. This URL is where the dashboard lives, and where clients and nodes connect.
    • addresses (required): An object value that defines bind addresses where the server is listening.
      • private (required): An object that defines the address that other components of the control plane will use to communicate with the coordinator.
        • base_url (required): A string value that defines the private base URL.
        • bind (required): A string value that defines which address the private HTTP API should listen on.
      • public (required): An object that defines the address that the API gateway should proxy requests to.
        • base_url (required): A string value that defines the pulic base URL.
        • bind (required): A string value that defines which address the public HTTP API should listen on.

services = {
  coordinator = {
    dsn = "sqlite:///opt/zeroassumptions/data/coordinator.sqlite&mode=rwc";
    public_url = "https://vpn.acme.org";
    addresses = {
      private = {
        base_url = "http://127.0.0.1:22470";
        bind = "127.0.0.1:22470";
      }
      public = {
        base_url = "http://127.0.0.1:22471";
        bind = "127.0.0.1:22471";
      }
    }
  }
  identity = {
    dsn = "sqlite:///opt/zeroassumptions/data/identity.sqlite&mode=rwc";
    addresses = {
      private = {
        base_url = "http://127.0.0.1:4434";
        bind = "127.0.0.1:4434";
      }
      public = {
        http = {
          base_url = "http://127.0.0.1:4433";
          bind = "127.0.0.1:4433";
        }
      }
    }
  }
}

• authentication (required): An object that defines user authentication.
  • require_mfa (required): A boolean value that defines whether or not to require multi-factor authentication. If sso_only is set to true and that SSO configuration requires multi-factor authentication, then the require_mfa value is recommended to be set to false, otherwise there will be two instances of multi-factor authentication.
  • sso_only (required): A boolean value that defines whether or not to rely on single sign on. If true, then password authentication will be disabled.
  • webauthn_mode (required): A string value that defines if WebAuth (FaceID, TouchID, Windows Hello) should be used, and what type of WebAuth to use. Accepted values are passwordless (use WebAuth instead of first factor password authentication), mfa (use WebAuth as second factor authentication), or disabled (turn off WebAuth as a form of authentication). The default value is disabled. If this value is changed at a later time, users will be impacted and can be locked out of their accounts.
  • webui_session (required): An object that defines how long before a user and admin needs to authenticate again.
    • lifespan (required): If using JSON, an integer value in seconds. If using UCL, a convenient number such as 1d that converts to seconds. How long until a user is asked to authenticate again.
    • sudo_lifespan (required): If using JSON, an integer value in seconds. If using UCL, a convenient number such as 1d that converts to seconds. How long until an admin is asked to authenticate again.
  • connection_lifespan (required): If using JSON, an integer value in seconds. If using UCL, a convenient number such as 1d that converts to seconds. How long until a user is asked to authenticate again to connect to the network.
  • secret_rotation_interval (required): If using JSON, an integer value in seconds. If using UCL, a convenient number such as 1d that converts to seconds. How often to rotate secrets used for signing and encryption. Rotation should not impact users unless using the "Best Glass Protocol" in the admin UI.
  • oidc_providers (optional): An object that defines an OIDC provider. Multiple OIDC providers can be used at the same time. Label each OIDC provider object with a string name, for example oidc_providers "google_acme_org".
    • provider (required): A string value that defines the style of provider. Supported values are google, okta, auth0 and generic.
    • scopes (required with generic provider only): An array that defines which scopes to request.
    • client_id (required): A string value that defines the provider client ID.
    • client_secret (required): A string value that defines the provider client secret.
    • issuer_url (required): A string value that defines the provider issuer URL.
    • mapper_url (required with generic provider only): A string value that defines the URL path to a jsonnet mapper. - http://acme.org/mymapper.jsonnet - file://path/to/mymapper.jsonnet - base64://<YOUR BASE64 ENCODED FILE>

authentication = {
  require_mfa = false;
  sso_only = false;
  webauthn_mode = "passwordless";
  webui_session = {
    lifespan = 1d;
    sudo_lifespan = 1h;
  };
  oidc_providers "google_acme_org" {
    provider = "google";
    scopes = ["email", "profile"];
    client_id = "";
    client_secret = "";
    issuer_url = "https://accounts.google.com";
    mapper_url = "";
  }
}

• email (required): An object that defines settings related to email delivery.
  • enabled (required): A boolean value that defines whether or not email features are enabled. Email features include sending password recovery and user invitations. If email features are disabled, then admins can still invite a user, but they will need to deliver the invitation link to users by other means.
  • from (required): A string value that defines the "from" field of emails. For example, "Company name <dashboard@company-name.org>".
  • smtp (optional): An object that defines SMTP connection-related settings. If no valid smtp values are defined, then emails cannot be sent to users.
    • host (required): A string value that defines the SMTP hostname. For example, "mail.google.com".
    • username (required): A string value that defines the SMTP username.
    • password (required): A string value that defines the SMTP user password. This value will be a JWT token if xoauth2 is used.
    • authentication_mechanism (required): A string value that defines the authentication mechanism. Accepted values are plain, xoauth2, and login (legacy, still used by Office365).
    • strattls (required): A boolean value that defines whether or not to enable StartTLS.

email = {
  enabled = false;
  from = "My Company <dashboard@company-name.org>"
  smtp = {
    host = "mail.google.com";
    username = "myusername";
    password = "mypassword";
    authentication_mechanism = "xoauth2";
    starttls = true;
  }
}