---
title: "Put sign-in in front of a web app | FoxAuth"
description: "Protect a web app that has no sign-in of its own, such as Grafana, with your Caddy, Traefik or nginx proxy and a FoxAuth project. No change to the app."
canonical: "https://foxauth.dev/docs/get-started/put-sign-in-in-front-of-a-web-app/"
lastmod: "2026-11-06T22:50:09+03:00"
---
Put sign-in in front of a web app

Some web apps have no sign-in of their own: a dashboard, an internal tool, an admin page someone wrote in an
afternoon. Anyone who finds the address can open them. You can fix that without touching the app. Put it behind your
proxy, and let the proxy ask FoxAuth about every request before the request reaches the app.

This way of working is called forward auth. Your reverse proxy (Caddy, Traefik or nginx) stands in front of the
app. For each request, it asks your FoxAuth project whether the request may go through. A person who has not signed
in is sent to the project’s sign-in page. A person who may open the page is let through, and the app is told who
they are. A person who may not open it sees a page that says so.

This page takes about ten minutes if your proxy already serves the app.

What you need first

A running instance with an administrator account (Create the first
administrator), a project with people in it,
and at least one group of those people. The app must be served over https by
a proxy you can configure.

1. Create the app in the consoleSection titled “1. Create the app in the console”

Open your project and choose its Applications tab, then New application.

Choose A web app with no sign-in of its own.

Fill in four things:

Name: how the console names the app.

Address: the app’s own https address, such as https://grafana.example.com. Only the scheme, the host and
a port are kept. If you paste an address with a path or a query, the form drops them and says so.

Who can open it: one or more groups. Only their members may open the app at all. You can open parts of it to
other people later.

Proxy: Caddy, Traefik or nginx. This only chooses which configuration the next step shows first.

The app appears in its own table on the Applications tab. Its page has three parts: Connect, Access and
Settings.

2. Configure your proxySection titled “2. Configure your proxy”

Connect shows the configuration for your proxy, with your project’s address and your app’s id filled in. Copy
it from there. The examples below are the same text, built by the same code, for an app at
https://grafana.example.com in a project at https://auth.example.com/acme. Your app’s id takes the place of
<appId>.

Each configuration does three things:

It sends every request to the check at https://auth.example.com/acme/verify/<appId> first, with the request’s
original method, host and path. The check refuses a request that does not say all three.

It removes any X-Auth-* header the browser sent, so nobody can pretend to be someone else.

It passes the request to the app, with the headers the check answered.

The app itself is assumed to listen on 127.0.0.1:8080. Replace that with its real address.

CaddySection titled “Caddy”

Caddyfile

grafana.example.com {

route {

request_header -X-Auth-*

forward_auth https://auth.example.com {

uri /acme/verify/<appId>

header_up Host {upstream_hostport}

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

}

reverse_proxy 127.0.0.1:8080

}

}

The route block keeps the order as written. Without it, Caddy would remove the X-Auth-* headers after the check
had set them.

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

routers:

app:

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

entryPoints:

- websecure

middlewares:

- foxauth

service: app

tls: {}

services:

app:

loadBalancer:

servers:

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

This is a dynamic configuration for the file provider. authResponseHeadersRegex removes every X-Auth-* header
the browser sent and copies the ones the check answered. preserveLocationHeader keeps the sign-in redirect
pointing at the project.

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_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 "";

}

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 "";

}

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 "";

}

}

nginx’s auth_request understands only three answers: allowed, not signed in and refused. So the check is asked for
a status only, and the sign-in redirect and the denial page come from a second call. That call is made for the error
page and for the paths under /_foxauth/, which belong to the sign-in. Add your certificate lines where the comment
says.

3. Keep the app reachable only through your proxySection titled “3. Keep the app reachable only through your proxy”

The check protects only the requests that pass through your proxy. A request that reaches the app another way skips
it, and the app would trust any X-Auth-* header it carried.

So make the app listen only where the proxy can reach it: on 127.0.0.1, on a private network, or behind a firewall
rule that admits only the proxy. Connect repeats this, because it is the one part FoxAuth cannot do for you.

If the app can check a signature, it can also stop depending on this. See X-Auth-Assertion below.

4. What your app receivesSection titled “4. What your app receives”

When a request is let through, the proxy adds these headers:

Header
What it holds

X-Auth-User
The person’s identifier in the project. It never changes, so use it as the key for the person.

X-Auth-Email
The person’s email address.

X-Auth-Groups
The identifiers of the person’s groups, separated by commas. Match on these, not on group names: a name can change.

X-Auth-Assertion
The same facts, signed with the project’s key. It is a JWT whose audience is your app’s address and which is valid for 60 seconds. It also carries the group names.

X-Auth-Reason
A short code for the decision, such as allowed. Refusals carry one too, for example not_in_group or no_session, so your proxy’s access log shows why someone was turned away.

On a path that is open to anyone, the first four headers are present but empty.

An app that verifies X-Auth-Assertion against the keys the project publishes at its jwks_uri knows the facts came
from the project. It no longer has to trust that every request came through the proxy.

5. Check that it worksSection titled “5. Check that it works”

Connect shows four steps, each with the time it first happened:

The app was created.

The proxy asked this project about the app.

Someone signed in through the proxy.

Someone got through.

Open the app in a private browser window. You should land on the project’s sign-in page, and after signing in, back
on the page you asked for. If step 2 stays empty, the proxy is not sending the check. If Connect names a host that is
not your app’s address, the proxy is not passing the original host.

To sign out of the app, open /_foxauth/sign_out on the app’s own address.

Choose who opens which partSection titled “Choose who opens which part”

Access lists one rule per path, as a tree. A rule says who may open its path and everything under it:

the members of one or more groups;

everyone the project lets sign in;

anyone, without signing in (only for GET and HEAD, and only for that exact path unless you also open
everything under it);

no one.

The longest path that matches decides, so the order of the rules never matters. A rule for /admin covers
/admin/users too, and /Admin/users as well. Before a save that lets more people in anywhere, the console lists
what widens and asks you to confirm. The access check on the same tab tells you whether a person would get in at a
given address, now and after you save.

A path can also ask for more than a group: only from your network, only in your hours, only a department, or a recent
sign-in. See Add conditions at your proxy.

Tip

Running FoxAuth itself behind a proxy is a different task. That is covered in
Behind a reverse proxy.

PreviousProtect your MCP server with OAuthNextProtect an MCP server at your proxy
