Elgato_dark/fleet
1
0
Fork 0
mirror of https://github.com/fleetdm/fleet synced 2026-04-21 13:37:30 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 91
fleet/articles/fleetd-mtls.md
Eric 1930222ecd
Replace mermaid chart in mTLS article (#24608) 
Changes:
- Replaced the Mermaid chart in the "mTLS support in fleetd" article
with an image of the chart. For context: The mermaid chart uses syntax
that is not supported by the version of mermaid the website uses.
2024-12-10 13:42:54 -06:00

5.7 KiB
Raw Permalink Blame History

mTLS support in fleetd

The Fleetd Authentication article shows how Fleet's agent, fleetd, authenticates to Fleet and TUF servers.

Additionally, Fleet Premium admins can configure fleetd to use mTLS on top of the existing authentication scheme to further increase the security of agent to server communication.

The Fleet server itself does not currently provide support for mTLS. Admins that want to use mTLS on their endpoints must setup a load balancer or TLS terminator like AWS's ELB or nginx that support mTLS.

Configuration

Admins can either generate the fleetd installer with the client certificate files included, or, can deploy the client certificate files to devices where fleetd is already installed.

The client certificates must be in PEM format.

Generating fleetd installers with client certificates

When generating the packages, admins can use the following flags to configure the client certificates:

fleetctl package \
  [...]
  # Client certificate to connect to Fleet servers.
  --fleet-tls-client-certificate=/path/to/fleet-client.crt \
  --fleet-tls-client-key=/path/to/fleet-client.key \
  # Client certificates can be provided when connecting to custom TUF servers that require mTLS.
  --update-tls-client-certificate=/path/to/update-client.crt \
  --update-tls-client-key=/path/to/update-client.key \
  --update-url=https://example.tuf.com \
  [...]

When --update-tls-client-certificate and --update-tls-client-key are provided,fleetctl will use them when downloading the fleetd components from the custom TUF server (--update-url).

If you are using fleetd with Fleet Desktop enabled, you may need to specify an alternative host for the "My device" URL (in the Fleet tray icon). Such alternative host should not require client certificates on the TLS connection.

fleetctl package
  [...]
  --fleet-desktop \
  --fleet-desktop-alternative-browser-host=fleet-desktop.example.com \
  [...]

If --fleet-desktop-alternative-browser-host is not used, you will need to configure client TLS certificates on devices' browsers.

Deploying client certificates to devices

Fleet currently does not natively support deploying client certificates to devices. Tooling like Chef, Ansible, or Puppet could be used for this purpose.

Once fleetd is installed, admins can force fleetd to use mTLS to communicate with Fleet and custom TUF servers by deploying the client certificates to the devices on the following locations:

  • macOS and Linux:
    • Connection to Fleet servers:
      • /opt/orbit/fleet_client.crt
      • /opt/orbit/fleet_client.key
    • Connection to custom TUF servers:
      • /opt/orbit/update_client.crt
      • /opt/orbit/update_client.key
  • Windows:
    • Connection to Fleet servers:
      • C:\Program Files\Orbit\fleet_client.crt
      • C:\Program Files\Orbit\fleet_client.key
    • Connection to custom TUF servers:
      • C:\Program Files\Orbit\update_client.crt
      • C:\Program Files\Orbit\update_client.key

If you are using fleetd with Fleet Desktop enabled, you may need to specify an alternative host for the "My device" URL (in the Fleet tray icon). Such alternative host should not require client certificates on the TLS connection. The ORBIT_FLEET_DESKTOP_ALTERNATIVE_BROWSER_HOST environment variable in orbit's configuration can be used to configure the Fleet deskto alternative host. If ORBIT_FLEET_DESKTOP_ALTERNATIVE_BROWSER_HOST is not set, you will need to configure client certificates on devices' browsers.

fleetd components using mTLS

Once configured, fleetd will use the provided client certificates on all components so that all communication from the endpoints to Fleet and TUF servers use mTLS.

  • orbit will use the provided client certificates to connect to Fleet servers.
  • orbit will use (if provided) client certificates to connect to custom TUF servers.
  • orbit will configure osqueryd and Fleet desktop to use the provided client certificate to connect to the Fleet server.

If you have suggestions for how to improve mTLS functionality in Fleet, please share them with us in the osquery Slack #fleet channel or open an issue in Github.