Behind a Cloudflare Tunnel¶

How to put IDEN on the internet without opening an inbound port, with nginx in front of the three applications and cloudflared carrying traffic in.

Budget about an hour. Twenty minutes of it is Cloudflare's own settings, and that part is not optional — several of its defaults break an identity provider in ways that look like bugs in IDEN.

The shape of it¶

browser --HTTPS--> Cloudflare edge --tunnel--> cloudflared --HTTP--> nginx --> provider
                                                                           --> auth-ui
                                                                           --> dashboard

Four things follow from that picture, and they are the reasons this page exists.

Your server listens on nothing. cloudflared makes an outbound connection to Cloudflare and traffic comes back down it. There is no port to firewall and no address to scan. This is the main reason to do it this way.

Cloudflare terminates TLS, so nginx does not. No certificates on your host, nothing to renew. cloudflared always speaks plain HTTP to the origin, which is why the nginx config here has no ssl_certificate and no :80 → :443 redirect — that redirect would loop forever, because cloudflared would follow it back out to Cloudflare and in again.

Every request arrives from cloudflared. Left alone, that means IDEN counts the whole internet as one caller and writes one address into every audit row. Three settings fix it, and they have to agree — see Who the caller is.

Cloudflare is now in the request path, and it has opinions. Bot protection, caching and script rewriting are all on by default in ways that break OIDC. See Cloudflare's settings.

One origin, three applications¶

Everything lives on one hostname. That is not only tidiness: the session cookie is SameSite=Lax and set by the provider, and one origin makes it unambiguously first-party for both frontends.

Both frontends are built with a matching Vite base, so their assets are served from /auth/assets/ and /console/assets/ and cannot collide. This is why you cannot simply point a proxy at the images and pick your own paths: change the path and you must change the base and rebuild.

Before you start¶

• A domain on Cloudflare, with the orange cloud enabled.
• Docker with Compose on the host.
• The repository cloned on that host.

Decide the hostname now. IDEN_ISSUER goes into every token and is compared character for character. Changing it later invalidates everything already issued.

Throughout, iden.example.org stands for yours.

The order to do it in¶

This page and Install it for your organization interleave — the tunnel needs a deployment to point at, and the deployment needs its hostname before it is seeded. Follow this sequence and neither doubles back on the other.

Steps 1, 2 and 7 are the install guide's; everything else is here. The install guide's own step 3 and step 4 are replaced by steps 4–6 above, which are the same work with the tunnel in it.

1. Create the tunnel¶

In the Cloudflare dashboard: Zero Trust → Networks → Tunnels → Create a tunnel, choose Cloudflared, name it, and copy the token it shows.

Do not install the connector the way the page suggests — Compose runs it. You only need the token.

Then add a public hostname to the tunnel:

nginx is the Compose service name — cloudflared runs on the same network and resolves it directly. HTTP, not HTTPS: the hop is inside the Docker network, and putting a self-signed certificate on it with noTLSVerify would be encryption without authentication, which is worse than the plaintext it replaces.

Cloudflare creates the DNS record for you.

2. Configure the deployment¶

cp deploy/.env.example deploy/.env

Edit deploy/.env. Every value is explained in the file; these are the ones that matter:

IDEN_ENV=prod
IDEN_ISSUER=https://iden.example.org
IDEN_AUTH_UI_BASE_URL=https://iden.example.org
IDEN_ALLOWED_ADMIN_ORIGINS=[]
IDEN_FORWARDED_ALLOW_IPS=172.31.250.0/24
CLOUDFLARE_TUNNEL_TOKEN=<the token from step 1>

IDEN_ENV=prod marks the session cookie Secure and sends HSTS. It also removes /docs, /redoc and /openapi.json, which would otherwise publish the complete shape of your admin API.

IDEN_ALLOWED_ADMIN_ORIGINS is empty on purpose. One origin means the dashboard's calls to the provider are same-origin, so there is no cross-origin request to allow. Name an origin here only for a browser application on some other host that calls the provider directly.

Then copy the proxy config:

cp deploy/nginx/iden.conf.example deploy/nginx/iden.conf

It works unedited if you keep the default subnet. Read it anyway — it is short, and it is where every routing decision on this page actually lives.

3. Start it¶

docker compose -f deploy/docker-compose.yml \
               -f deploy/docker-compose.tunnel.yml up -d --build

The overlay adds nginx and cloudflared, and pins the project network to 172.31.250.0/24 — a fixed subnet so that the address nginx trusts is knowable in advance rather than looked up after every up.

Check it worked, without going out to Cloudflare and back:

curl -s -H 'Host: iden.example.org' \
     http://127.0.0.1:8080/.well-known/openid-configuration | jq .issuer

"https://iden.example.org"

nginx publishes 127.0.0.1:8080 for exactly this. If the issuer says localhost, deploy/.env is not being read — check that it sits next to docker-compose.yml, not at the repository root.

Then from anywhere:

curl -s https://iden.example.org/.well-known/openid-configuration | jq .issuer

4. Point the dashboard client at the hostname¶

The seeded dashboard client allows only localhost callbacks. Until it names your origin, sign-in loops.

docker compose -f deploy/docker-compose.yml exec -T postgres \
  psql -U iden -d iden -c \
  "update clients set redirect_uris = ARRAY['https://iden.example.org/console/callback']
   where client_id = 'dashboard';"

redirect_uris is a PostgreSQL array (character varying[]), not JSON — hence ARRAY[...] rather than a bracketed string. A JSON literal here fails with malformed array literal.

Note /console/callback: the dashboard's redirect URI moved with the app.

Check it worked, since a wrong value here presents as a sign-in loop rather than an error:

docker compose -f deploy/docker-compose.yml exec -T postgres \
  psql -U iden -d iden -c \
  "select client_id, redirect_uris from clients where client_id = 'dashboard';"

 client_id |                redirect_uris
-----------+--------------------------------------
 dashboard | {https://iden.example.org/console/callback}

Once you can sign in, the Clients screen in the dashboard edits this without SQL. Direct psql is for the bootstrap, when there is no way in yet.

5. Cloudflare's settings¶

This is the part that is easy to skip and expensive to skip.

Turn on¶

Turn off¶

Never turn on¶

Let the protocol through the WAF¶

Bot Fight Mode and managed challenges answer anything that does not look like a browser with an HTML interstitial or a 403. Every one of these is a non-browser caller:

• POST /oauth2/token — every confidential client, every refresh
• POST /oauth2/introspect, POST /oauth2/revoke
• GET /.well-known/jwks.json — fetched by every API validating a token
• GET /.well-known/openid-configuration — fetched by every client library at startup
• /admin/* and /entity/* with a bearer token

A challenged token exchange returns text/html with a 403. The client library tries to parse it as the error object RFC 6749 defines, fails, and reports something opaque about invalid JSON — while your provider never saw the request, so nothing correlates in the audit log.

Add a WAF custom rule, action Skip, skipping Bot Fight Mode and rate limiting:

http.host eq "iden.example.org" and (
  starts_with(http.request.uri.path, "/oauth2/") or
  starts_with(http.request.uri.path, "/.well-known/") or
  starts_with(http.request.uri.path, "/admin/") or
  starts_with(http.request.uri.path, "/entity/")
)

Leave protection on for /auth/* and /console/*, which genuinely are only ever browsers.

Who the caller is¶

IDEN attributes a request to an address in two places that matter: the per-address rate limits, and the ip column of every audit row. Behind a proxy both see the proxy unless three settings agree.

Cloudflare sets     CF-Connecting-IP: 203.0.113.9      one address, always, overwritten at the edge
        │
nginx   real_ip_header CF-Connecting-IP                $remote_addr becomes 203.0.113.9
        set_real_ip_from 172.31.250.0/24               ...but only from this network
        │
        proxy_set_header X-Forwarded-For $remote_addr  one value, not a chain
        │
provider IDEN_FORWARDED_ALLOW_IPS=172.31.250.0/24      believe it, from this network
        │
        scope["client"] = ("203.0.113.9", 0)           what the limiter and the audit log read

All three ranges must name the same network. They are already consistent in the shipped files; if you change the subnet in docker-compose.tunnel.yml, change set_real_ip_from in nginx/iden.conf and IDEN_FORWARDED_ALLOW_IPS in .env with it.

Get it wrong in one direction and every caller looks like the tunnel:

• TOKEN_PER_IP stops being 120 requests a minute per caller and becomes 120 a minute for the whole deployment. At a few hundred active sessions that is an outage, and it looks like one.
• RESET_PER_IP becomes ten password resets an hour, globally.
• Every audit row records 172.31.250.x, so the log can no longer answer where did this administrator sign in from — which is a large part of why it exists.

Get it wrong in the other direction — IDEN_FORWARDED_ALLOW_IPS=*, or a set_real_ip_from covering the internet — and a header anyone can set decides who they are counted as, which is no limit at all. Never *.

Single sign-out needs egress¶

This is the one place IDEN is the HTTP client. When someone signs out, the provider POSTs a logout token to each application's registered backchannelLogoutUri (OIDC Back-Channel Logout 1.0).

A tunnel is inbound only. That traffic goes out over the host's ordinary internet connection and needs no configuration — but if you have locked down outbound egress on the assumption that the tunnel carries everything, single sign-out stops working.

If a relying party is on this same host, register its internal address rather than its public one:

backchannelLogoutUri = http://app:3001/auth/backchannel-logout

Otherwise the provider resolves the public name, goes out to Cloudflare, and comes back down the tunnel to reach a container three hops away — two internet round trips against a five-second budget, through whatever WAF rules apply to that hostname. Plaintext is fine: the logout token is a signed JWT, and the hop never leaves the Docker network.

If it is genuinely remote, add a WAF skip rule on its hostname for its logout path, the same shape as the one above.

Either way the failure is silent. A 403 from a challenge is a valid HTTP response, so nothing is logged; the user is redirected to "you have been signed out" regardless, and the only trace is one audit row:

select detail->>'uri' as uri, status_code, count(*), max(occurred_at)
from audit_events
where action = 'POST backchannel_logout'
group by 1, 2 order by 3 desc;

200/204 delivered. 0 never arrived. Anything else is a sign-out that has been quietly failing.

What is deliberately not exposed¶

Verify it¶

Work through this before anyone else is let in. Then work through Before you expose it, which covers the parts that are not specific to a tunnel.

The routing¶

for p in / /auth/login /console/ /console/admin/users \
         /.well-known/openid-configuration /admin/users /health /docs; do
  printf '%-38s %s\n' "$p" "$(curl -s -o /dev/null -w '%{http_code}' https://iden.example.org$p)"
done

The caller's address¶

Sign in through the browser, then:

select action, status_code, ip from audit_events order by occurred_at desc limit 5;

ip must be your own public address. If it shows 172.31.250.x, the three settings do not agree.

The negative test¶

The one people skip. From the host, bypass nginx and lie:

curl -s -o /dev/null -H 'X-Forwarded-For: 9.9.9.9' \
     -H 'CF-Connecting-IP: 9.9.9.9' http://127.0.0.1:8000/health/live

Nothing in the audit log should ever record 9.9.9.9. If it does, IDEN_FORWARDED_ALLOW_IPS is wider than the network nginx sits on.

Running it day to day¶

Every command needs both files, which gets tedious. Set this once per shell, or in your profile:

export COMPOSE_FILE=deploy/docker-compose.yml:deploy/docker-compose.tunnel.yml

Then docker compose ps, docker compose logs -f cloudflared and the rest work unqualified. The examples below spell the flags out, so they work either way.

docker compose -f deploy/docker-compose.yml \
               -f deploy/docker-compose.tunnel.yml up -d auth-ui dashboard

curl -s https://iden.example.org/console/config.js

One more worth knowing: nginx resolves its upstreams once, at start-up. Recreate provider, auth-ui or dashboard on their own and they come back on new addresses that nginx does not know, which presents as 502 from a stack where everything is running. restart nginx fixes it, and bringing the whole stack up together never hits it because nginx starts last.

When something is wrong¶

docker compose -f deploy/docker-compose.yml -f deploy/docker-compose.tunnel.yml restart nginx

docker compose -f deploy/docker-compose.yml build --no-cache auth-ui dashboard

curl -s https://iden.example.org/console/config.js