From 2b5dcd42cfd7420e1bfbf3848a4863c47a4faa56 Mon Sep 17 00:00:00 2001 From: Tom Elliott Date: Wed, 18 Nov 2026 10:18:35 -0600 Subject: [PATCH] Roles: document Allowed Networks (FOGProject/fogproject#2107) A role can limit the networks its members use the web UI and REST API from, while the iPXE boot menu stays usable from anywhere. Documents what to type, how lists combine across roles, what is and is not limited, the reverse-proxy caveat, and lockout recovery. The 1.6 API page gains the new 403. Co-Authored-By: Claude Opus 5.5 --- docs/1.6/kb/integrations/api.md | 7 +++ docs/management/web/roles.md | 89 ++++++++++++++++++++++++++++++++- 2 files changed, 95 insertions(+), 1 deletion(-) diff --git a/docs/1.6/kb/integrations/api.md b/docs/1.6/kb/integrations/api.md index 849f02b..4652fd4 100644 --- a/docs/1.6/kb/integrations/api.md +++ b/docs/1.6/kb/integrations/api.md @@ -49,6 +49,12 @@ Every method carries the same permissions: the acting user's roles are applied either way, so a user without `user.view` gets `403 Forbidden` from `/fog/user` however they signed in. +A role can also limit the networks its members use FOG from. A request from +outside those networks gets `403 Forbidden` with +`{"error": "Your role does not allow API access from this network."}`, +whichever method it uses. See +[[roles#Limiting where a role can sign in from|Roles & Permissions]]. + ### Bearer token (recommended) An **API token** is issued from the web UI, shown to you once, and sent in the @@ -361,6 +367,7 @@ An error answers with a JSON body of the form `{"error": ""}`. | `400 Bad Request` | A required field is null or blank. | | `400 Bad Request` | An edit sets an empty name. | | `403 Forbidden` | The user does not have the permission that the route needs. | +| `403 Forbidden` | The user's roles do not allow API access from the network the request comes from. | | `404 Not Found` | The id in the URL does not exist, including a cancel for that id. | | `404 Not Found` | No route matches the path, for example `GET /fog/host/abc`. | | `405 Method Not Allowed` | The path exists, but not for this HTTP verb. The `Allow` header lists the verbs that work. | diff --git a/docs/management/web/roles.md b/docs/management/web/roles.md index 3fabb6a..11a64c9 100644 --- a/docs/management/web/roles.md +++ b/docs/management/web/roles.md @@ -108,7 +108,8 @@ menu. 2. Give the role a unique name (and optionally a description), then click **Create**. 3. Open the new role and use its tabs: - - **General** — name and description. + - **General** — name, description, and **Allowed Networks**. See + [Limiting where a role can sign in from](#limiting-where-a-role-can-sign-in-from). - **Permissions** — a grid of areas and actions. Tick the boxes the role should grant, or tick **Administrator (full access)** to grant everything, then click **Update**. @@ -259,6 +260,92 @@ scoped. See [Site Scoping](site-scoping.md) for the full workflow. +## Limiting where a role can sign in from + +A role can limit the networks its members use FOG from. Put the addresses +in the **Allowed Networks** box on the role's **General** tab. + +Members of the role can then sign in to the web UI, and use the +[REST API](../../kb/integrations/api.md), only from those networks. The +iPXE boot menu is not limited. A technician can still sign in at the boot +menu of a computer on any network and start a task. + +For example, a help-desk role with `10.20.0.0/16` in **Allowed Networks** +lets its members use the web UI from the office network only. At a site +on `172.16.5.0/24`, the same technician can still quick-image a computer +from its boot menu. + +### What to type + +- One entry per address or range: `192.168.1.50`, `10.0.0.0/24`, or an + IPv6 range such as `fd00::/8`. +- Separate the entries with commas, spaces, or new lines. FOG saves them + one per line. +- Leave the box empty for no limit. Every role starts empty, so nothing + changes until you fill one in. +- FOG refuses to save an entry that is not a valid address or range, and + names the bad entry. + +### Users with more than one role + +FOG combines the lists of all the roles a user holds, including roles that +reach the user through a user group. The user can sign in from any network +on any of those lists. + +A role with an empty list does not lift the limit. If one of a user's +roles has a list, the user is limited to the lists, whatever other roles +they hold. Otherwise any harmless role without a list would undo the limit. + +### What is limited, and what is not + +| Way in | Limited? | +| --- | --- | +| Web UI sign-in: the password form, or a single sign-on provider | Yes | +| A web UI session that is already open | Yes, on its next page load | +| **Remember me** | Yes | +| REST API: Bearer token, token pair, or HTTP Basic | Yes. The API answers `403 Forbidden` | +| iPXE boot menu sign-in, and the advanced menu | No | +| Full registration and the FOS credential check | No | +| The FOG Client and the FOG agent | No. They do not sign in as a user | + +A change to **Allowed Networks** takes effect for signed-in members on +their next page load. A member outside the new list goes back to the +sign-in page. The sign-in then says "Your role does not allow sign-in from +this network." + +### Which address FOG checks + +FOG checks the address the connection comes from. It never reads +`X-Forwarded-For`, because the caller writes that header and could name +any address. + +>[!warning] Reverse proxies +> +>If a reverse proxy sits in front of FOG, every request arrives from the +>proxy's address. FOG then cannot tell users apart, and the limit does not +>work as intended: +> +>- If the proxy's address is on the list, every member passes, from +> anywhere. +>- If it is not on the list, no member can sign in. +> +>This includes a proxy on the FOG server itself, where every request +>arrives from `127.0.0.1`. FOG gives `127.0.0.1` no special treatment. +>To allow sign-in from the server itself, add `127.0.0.1` to the list. + +### Lockout protection + +FOG refuses to save a change to **Allowed Networks** that would lock out +the user who makes it. This applies in the web UI and through the API. + +Adding yourself to a limited role while you are outside its networks is +not checked. If a limit locks everyone out: + +- sign in as an administrator whose roles have no list, and clear the + box, or +- clear the `rAllowedNetworks` column of the `roles` table in the + database. + ## API tokens follow roles A user API token inherits that user's role permissions: API requests