From defe1d03f116930f5dfafc69dc9d32fa44572a98 Mon Sep 17 00:00:00 2001 From: Roberto Dip Date: Wed, 26 Oct 2022 11:51:28 -0300 Subject: [PATCH] add documentation about token rotation (#8435) Related to #6064 and #6993 this adds documentation about token rotation. --- docs/Using-Fleet/Fleet-desktop.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/docs/Using-Fleet/Fleet-desktop.md b/docs/Using-Fleet/Fleet-desktop.md index 38c57df108..47d228c20d 100644 --- a/docs/Using-Fleet/Fleet-desktop.md +++ b/docs/Using-Fleet/Fleet-desktop.md @@ -32,7 +32,28 @@ For information on how to set the custom transparency link via a YAML configurat ## Securing Fleet Desktop +Requests sent by Fleet Desktop and the web page that opens when clicking on the "My Device" tray item use a [Random (Version 4) UUID](https://www.rfc-editor.org/rfc/rfc4122.html#section-4.4) token to uniquely identify each host. + +The server uses this token to authenticate requests that give host information. Fleet uses the following methods to secure access to this information. + +**Rate Limiting** + To prevent brute-forcing, Fleet rate-limits the endpoints used by Fleet Desktop on a per-IP basis. If an IP requests more than 720 invalid UUIDs in a one-hour interval, Fleet will return HTTP error code 429. +**Token Rotation** + +``` +ℹ️ In Fleet v4.22.0, token rotation for Fleet Desktop was introduced. +``` + +Starting with Fleet v4.22.0, the server will reject any token older than one hour since it was issued. This helps Fleet protect against unintentionally leaked or brute-forced tokens. + +As a consequence, Fleet Desktop will issue a new token if the current token is: + +- Rejected by the server +- Older than one hour + +This change is imperceptible to users, as clicking on the "My Device" tray item always uses a valid token. If a user visits an address with an expired token, they will get a message instructing them to click on the tray item again. +