---
title: "Add conditions at your proxy | FoxAuth"
description: "Let people into an app or an API behind your proxy only from your network, only in working hours, only from a department, or only after a recent sign-in."
canonical: "https://foxauth.dev/docs/get-started/add-conditions-at-your-proxy/"
lastmod: "2026-11-17T11:19:13+03:00"
---
Add conditions at your proxy

An app behind your proxy decides who may open each path. An API whose tokens your proxy checks decides which tools a
token may call. Both pages are here: Put sign-in in front of a web app
and Protect an MCP server at your proxy. This page adds
conditions on top of that.

A condition says “and only if”. It never lets anyone in who was not let in before. It can only narrow access.

What conditions there areSection titled “What conditions there are”

Condition
What it checks
For

From where
the address is in one of your ranges, or in none of them
apps, APIs

Network facts
the address is not Tor, a VPN or hosting, or is in your country
apps, APIs

When
the moment is inside your hours, in a time zone you choose
apps, APIs

Attribute
the person’s department, title or another field is one of yours
apps, APIs

Groups
the person is in one of your groups
APIs

Ask to sign in again
the person signed in no more than N minutes ago
apps

An app’s groups are already in its rule for each path, so groups are a condition only for an API. Network facts are
a part of From where, not a condition of their own. An API has no Ask to sign in again condition. Instead, its
own Access tab can require a code from an authenticator app or a recent sign-in: see Ask for a code or a recent
sign-in.

Values inside one condition combine with “or”: “from the office or from the VPN”. Different conditions combine with
“and”: “from the office, and in working hours”. A rule holds at most one condition of each kind.

How conditions apply to pathsSection titled “How conditions apply to paths”

The longest matching path still decides who may open it. Conditions add up down the paths: the conditions of /
apply to every path, and a condition on /admin applies to /admin and everything under it, on top of those of /.
A path can add a condition. It cannot drop one from a path above it. Public paths take no conditions.

The project decides in a fixed order:

From where and When, before anyone signs in. Someone in the wrong place or at the wrong hour is turned away
without being asked for a password.

Whether the person has signed in, may sign in, and is in the rule’s groups.

Attribute.

Ask to sign in again, last. Nobody is sent to sign in only to be refused afterwards.

Network facts that ask for a new sign-in instead of refusing are judged with Ask to sign in again, last.

From where: let your proxy pass the addressSection titled “From where: let your proxy pass the address”

The address of the person is something only your proxy knows. A browser can write any address in a header, so the
project believes an address only when your proxy proves it wrote it.

On the app’s or the API’s Connect page, open Your proxy passes people’s addresses and choose Issue a
proxy key. Copy the key. It is shown once. A project has at most two keys, so you can replace one without a
moment when your proxy is refused.

Add the lines from the configuration on that page to your proxy. They overwrite X-Forwarded-For with the address
the connection came from, and add the key. For Caddy, set FOXAUTH_PROXY_KEY in the environment Caddy runs in. For
nginx, put the key where the configuration says <FOXAUTH_PROXY_KEY>.

Run the test the page gives. It sends a forged address through your proxy. The step must not turn red.

A network condition cannot be saved until a check has arrived with the key and a public address. So one save cannot
lock everyone out.

CaddySection titled “Caddy”

Caddyfile

grafana.example.com {

route {

request_header -X-Auth-*

request_header -X-FoxAuth-Proxy-Key

forward_auth https://auth.example.com {

uri /acme/verify/<appId>

header_up Host {upstream_hostport}

header_up X-Forwarded-For {remote_host}

header_up X-FoxAuth-Proxy-Key {$FOXAUTH_PROXY_KEY}

copy_headers X-Auth-User X-Auth-Email X-Auth-Groups X-Auth-Assertion X-Auth-Reason

}

reverse_proxy 127.0.0.1:8080

}

}

nginxSection titled “nginx”

nginx server block

server {

listen 443 ssl;

server_name grafana.example.com;

# ssl_certificate and ssl_certificate_key for grafana.example.com

location / {

auth_request /_foxauth_check;

auth_request_set $foxauth_x_auth_user $upstream_http_x_auth_user;

auth_request_set $foxauth_x_auth_email $upstream_http_x_auth_email;

auth_request_set $foxauth_x_auth_groups $upstream_http_x_auth_groups;

auth_request_set $foxauth_x_auth_assertion $upstream_http_x_auth_assertion;

auth_request_set $foxauth_x_auth_reason $upstream_http_x_auth_reason;

error_page 401 403 = @foxauth;

proxy_set_header X-Auth-User $foxauth_x_auth_user;

proxy_set_header X-Auth-Email $foxauth_x_auth_email;

proxy_set_header X-Auth-Groups $foxauth_x_auth_groups;

proxy_set_header X-Auth-Assertion $foxauth_x_auth_assertion;

proxy_set_header X-Auth-Reason $foxauth_x_auth_reason;

proxy_set_header Host $host;

proxy_set_header X-FoxAuth-Proxy-Key "";

proxy_pass http://127.0.0.1:8080;

}

location = /_foxauth_check {

internal;

proxy_pass https://auth.example.com/acme/verify/<appId>?mode=status;

proxy_set_header X-Forwarded-Host $host;

proxy_set_header X-Forwarded-Uri $request_uri;

proxy_set_header X-Forwarded-Method $request_method;

proxy_set_header Host auth.example.com;

proxy_ssl_server_name on;

proxy_pass_request_body off;

proxy_set_header Content-Length "";

proxy_set_header X-Forwarded-For $remote_addr;

proxy_set_header X-FoxAuth-Proxy-Key "<FOXAUTH_PROXY_KEY>";

}

location /_foxauth/ {

rewrite ^ /acme/verify/<appId>? break;

proxy_pass https://auth.example.com;

proxy_redirect off;

proxy_set_header X-Forwarded-Host $host;

proxy_set_header X-Forwarded-Uri $request_uri;

proxy_set_header X-Forwarded-Method $request_method;

proxy_set_header Host auth.example.com;

proxy_ssl_server_name on;

proxy_pass_request_body off;

proxy_set_header Content-Length "";

proxy_set_header X-Forwarded-For $remote_addr;

proxy_set_header X-FoxAuth-Proxy-Key "<FOXAUTH_PROXY_KEY>";

}

location @foxauth {

rewrite ^ /acme/verify/<appId>? break;

proxy_pass https://auth.example.com;

proxy_redirect off;

proxy_set_header X-Forwarded-Host $host;

proxy_set_header X-Forwarded-Uri $request_uri;

proxy_set_header X-Forwarded-Method $request_method;

proxy_set_header Host auth.example.com;

proxy_ssl_server_name on;

proxy_pass_request_body off;

proxy_set_header Content-Length "";

proxy_set_header X-Forwarded-For $remote_addr;

proxy_set_header X-FoxAuth-Proxy-Key "<FOXAUTH_PROXY_KEY>";

}

}

The key and the address are set in each of the three places that call the check.

TraefikSection titled “Traefik”

Traefik dynamic configuration

http:

middlewares:

foxauth:

forwardAuth:

address: "https://auth.example.com/acme/verify/<appId>"

trustForwardHeader: false

authResponseHeadersRegex: "^X-Auth-"

preserveLocationHeader: true

foxauth-key:

headers:

customRequestHeaders:

X-FoxAuth-Proxy-Key: "<FOXAUTH_PROXY_KEY>"

foxauth-key-drop:

headers:

customRequestHeaders:

X-FoxAuth-Proxy-Key: ""

routers:

app:

rule: "Host(`grafana.example.com`)"

entryPoints:

- websecure

middlewares:

- foxauth-key

- foxauth

- foxauth-key-drop

service: app

tls: {}

services:

app:

loadBalancer:

servers:

- url: "http://127.0.0.1:8080"

Note

Traefik cannot add a header to its check by itself, so the key travels in two
headers middlewares: one adds it before the check and one clears it after,
so your app never receives it.

What the project believesSection titled “What the project believes”

Exactly one address, written plainly. Two addresses, a port, brackets or an unusual spelling make the address
unknown.

An unknown address fails every network condition, “only from” and “not from” alike.

A private address, such as one of a load balancer or a container network, is unknown for “not from”. The Connect
page says when your proxy reports one.

A CDN in front of your proxy is not supported, except Cloudflare when your proxy accepts connections only from
Cloudflare’s addresses.

The address is compared with your ranges and, with network facts, looked up in your server’s own copy of
FoxTrust’s snapshot. The check never writes it to a log line or sends it anywhere. When a path refuses a person or
asks them to sign in again, their Activity tab keeps the address for 90 days, because your proxy proved it with the
project’s key. While Look up network owner and location at FoxTrust is on, which is the default, the server then
sends that kept address to FoxTrust’s API to show its network owner, region and city beside it
(what FoxAuth records about people).

A VPN or a residential proxy can still get around a list of ranges. A network condition slows an attacker down. It
does not stop one. Network facts keep out the VPN services FoxTrust lists, but a residential proxy still gets through.

For an API, the address is the machine that calls it. Hosted assistants call from their own cloud, not from the
person’s network.

Network facts: Tor, VPNs, hosting and countriesSection titled “Network facts: Tor, VPNs, hosting and countries”

A list of ranges names addresses you know. Network facts say what an address is, even one you have never seen: an exit
of the Tor network, a commercial VPN, a data centre, or a country. They are an optional second part of From where,
on a path of an app and on an API. They need the proxy key and the address from the steps above, like a list of
ranges.

Turn on the downloadSection titled “Turn on the download”

Network facts come from FoxTrust, an IP reputation service. FoxTrust publishes a signed snapshot of what it knows about
internet addresses. Your server downloads the snapshot and checks it itself.

A super administrator opens Settings → Integrations and turns on Network facts from FoxTrust. It is off by
default. It is free on every plan.

Each server process then downloads a full file of about 13 MB once a day and an update every hour. It looks for a
new file every 5 minutes. It uses a file only after checking its size, its checksum and FoxTrust’s signature.

The card under the setting shows when the snapshot was built, its age, how many address ranges it holds, and the
last failure, if there was one.

For a condition, people’s addresses are never sent to FoxTrust or anywhere else. Your server only looks them up in
its own copy, and FoxTrust learns only that the file was downloaded. Showing the network owner and location of the
addresses a person’s activity keeps is a separate setting, Look up network owner and location at FoxTrust, which
does send those addresses to FoxTrust’s API.

What you can keep outSection titled “What you can keep out”

Under Network facts from FoxTrust, tick what a path should keep out:

Choice
What it covers

Tor
The exits of the Tor network.

Commercial VPN
Only the VPN services FoxTrust lists. A company’s own VPN is not one of them.

Hosting or a cloud
Data centres and clouds. They also carry content networks and some companies’ own exits to the internet.

iCloud Private Relay is not offered, and its addresses pass. FoxTrust does not count them as a VPN or as hosting.

CountriesSection titled “Countries”

Choose Only from or Not from, then the countries. One condition holds one of the two lists, with up to 250
countries.

An address with no known country fails Only from and passes Not from.

An address of your proxy’s own private network has no country, so Only from refuses it. Not from passes it,
for categories and countries alike.

Region and city are not used.

Countries come from DB-IP. Wherever the console shows a country, it also shows the line the data’s licence asks for:
IP Geolocation by DB-IP, CC BY 4.0.

What a matching address leads toSection titled “What a matching address leads to”

Choose what happens when an address matches:

Refused. Before any sign-in, the person sees a page titled “You can’t open app.example.com from where you are”.
The page names no source, category or country. Your proxy gets 403 with X-Auth-Reason: not_from_network.

Asked to sign in again within N minutes, for an app only. A person whose sign-in is older than N is sent to sign
in again. N is from 5 minutes to a day. Tick with a code from an authenticator app to ask for a code too. The
console then shows the same count of people as for a code on Ask to sign in again.

An address that does not match is never asked. What FoxTrust knows about a network can be wrong, and asking for a new
sign-in is gentler than refusing. On an API checked at the proxy, network facts can only refuse: a token check has no
browser to send to a sign-in. An API can still ask for a code or a recent sign-in, through its own settings: see Ask
for a code or a recent sign-in.

The rule’s line says it in words, for example “not from Tor, a VPN or hosting” or “only from Germany or Austria”.

When the facts are unknownSection titled “When the facts are unknown”

The server cannot say what an address is while the download is off, before the first snapshot loads, and when the
loaded snapshot was built more than 26 hours ago. Then every path with network facts is closed, whatever its outcome.

The person sees a page titled “app.example.com can’t be opened right now”. Your proxy gets 403 with
X-Auth-Reason: network_facts_unknown.

The console marks each such path with the reason.

When a fresh snapshot loads, the paths open again on their own.

A failed download changes nothing at once. The server keeps using the last good snapshot until it is 26 hours old.

Network facts can be added or changed only while the download is on. A condition saved earlier stays saved when the
download is turned off, and closes its path.

Check an addressSection titled “Check an address”

In Check access, type the address from the person’s message. The console looks it up in your server’s own copy and
shows its categories and its country, or says FoxTrust knows nothing about it, with the snapshot’s age. The address is not
sent anywhere. With no address typed, network facts show “?”.

An agent sets network facts with behind_proxy_app_update or resource_update, as facts on a network condition.
It explains a refusal with network_facts_lookup.

When: opening hoursSection titled “When: opening hours”

Choose the days and the hours, in steps of 15 minutes, and the time zone they are read in. The time zone is set once
for the app or the API. Hours that end before they start run past midnight: “Fri 22:00 to 06:00” is Friday night into
Saturday morning.

Someone who arrives outside the hours sees when the app opens again, in its time zone.

AttributeSection titled “Attribute”

Choose an attribute and its values. The attributes are those an administrator or a directory sets on a person:
department, division, organization, cost center, employee number, title, or a claim an administrator sets. Claims a
person’s outside sign-in provider supplies, such as their name or picture, cannot be chosen: the person can change
them.

The console shows how many people in the project match. A condition nobody matches cannot be saved.

Ask to sign in againSection titled “Ask to sign in again”

Choose 15 minutes, an hour, 8 hours, a day, or your own value from 5 minutes. When the person’s sign-in is older, the
browser is sent to sign in again, and the sign-in page says why. A request that is not a page gets 401.

Pages that load data in the background, such as dashboards, stop working until the person reloads. Use this on
admin paths, not on the whole app.

Anyone who set up an authenticator app types a code when signing in again.

A person who signs in through an outside provider is asked to sign in there again. How fresh that sign-in is, the
provider decides.

With a code from an authenticator appSection titled “With a code from an authenticator app”

Tick with a code from an authenticator app under the condition. The path then opens only for a sign-in that
included a code and is not older than the time you chose, at most a day. The rule reads “signed in with a code within
15 min”.

Before it saves, the console shows how many of the people who may open the path have no authenticator app, and how
many can sign in only through a provider. You confirm with those numbers. Only someone who may manage the project’s
people can turn it on.

A person with a code signs in again with the password and the code, even when they typed a code earlier that day.

A person without one sees a page that names your app’s address. If the project lets people set one up, they set it
up there and reach the page they opened, in the same sign-in. Otherwise the page asks them to contact you.

A person who signs in through a provider is told this way of signing in cannot open the page.

Going back without signing in ends on a page that says the page needs a code. It never starts the same sign-in
again.

The console’s Check access has a box for whether the person signed in with a code.

Groups and attributes for an APISection titled “Groups and attributes for an API”

Open the API’s page and its Access tab. Its first section, Who can call it, holds the API’s conditions. They apply
before the tools table.

A condition about the person needs a token that stands for a person. These do not, and are refused:

a token an application got for itself, with no person;

a token for an application that gives people a different identifier in each application (pairwise);

a self-contained token issued before this release, which does not say when the person signed in.

When you save, the console names the applications whose tokens will be turned away. A person who is locked or
deactivated is refused at once. A person removed from a group is refused within a minute.

One tool of an MCP server can carry conditions of its own: groups, From where and When. They are added to the
API’s conditions and never replace them. A call that fails them is refused, never asked to sign in again. See
Conditions on one tool, which also says what
such a condition cannot stop.

Check before you saveSection titled “Check before you save”

Check access on the app’s Access tab takes an address in the app, a person, a network address, a moment and how
long ago the person signed in. It lists every condition in the order the project decides them, each with ✓, ✗ or ?.
An input you leave empty shows “?”. An API’s Access tab has a Check access card of its own: see Check
access.

A change that lets more people in asks first and lists what loosens, path by path. A change that only narrows saves at
once. The FoxAuth console itself is never behind these conditions, so a rule cannot lock you out of it.

Upgrading and rolling backSection titled “Upgrading and rolling back”

The first release with conditions marks the database so that an older release refuses to start against it. An older
release could not enforce conditions, so it must not run. The first release with a code at the proxy marks it again,
for the same reason, and so does the first release with network facts. You cannot roll back below this release. During a rolling
deploy, an older process still running answers an error for an app or an API with conditions until it is replaced. It
never lets a request through.

PreviousProtect an MCP server at your proxyNextRefuse password guessing from known addresses
