Protecting paths#
This page shows how each app declares its public, protected, api and deny paths in the config file, how a rule can name groups, and how the gateway picks the one rule that applies to a request.
The per-app config#
One YAML (or PHP array) file declares the gateway, the OpenID Connect provider and each app.
config/drawbridge.example.yaml is annotated. The per-app entry from that file, verbatim:
apps:
- id: app1
host: app1.apps.wayne.edu
# Where the app's container listens, as seen from the gateway. No path.
upstream: http://app1:8080
# Only "assertion" (a signed JWT) is accepted in 1.0.
mode: assertion
# What a path with no rule gets. "login" (default) is the safe choice. "deny" refuses every path no rule
# names, so only the paths listed below exist at all. "public" opens them.
default: login
# A path ending in "/" is a prefix ("/assets/" covers /assets and everything under it). Any other path is exact.
# No wildcards or regular expressions. Query strings are never part of the match.
public:
- /up
- /assets/
protected:
- /admin/
# A rule can also need an Entra authentication context (c1 to c99): the gateway asks Entra for it, and lets
# the request through only when the ID token's "acrs" lists it. Conditional Access decides what c1 means.
- path: /admin/payroll/
auth_context: c1
# A rule can also name groups: the person must hold at least one of them in the groups claim (above), or
# the gateway answers 403. A coarse gate in front of the app; the app still decides what each person may do.
- path: /admin/reports/
groups: [app1-reports, app1-admins]
# Like protected, but an unauthenticated caller gets a 401 instead of a redirect to sign in.
api:
- /api/
# Never reaches the app, signed in or not: the gateway answers 403. For tools that must not be on the internet.
# The most specific rule wins, so a deny prefix can still hold a public or protected path under it.
deny:
- /telescope/
What each key does:
id: the app's name in the config (app1in the example).host: the host name of the app the entry fronts; the gateway keeps one session cookie per app host.upstream: where the app's container listens, as seen from the gateway. No path.mode: how the gateway passes the identity on. Onlyassertion(a signed JWT that SESAME'sgatewaydriver verifies) is accepted in 1.0; the header modes (headers,both) were removed.default: what a path with no rule gets:login(the default),denyorpublic.public: the paths that pass through with no identity attached.protected: the paths that need a sign-in. A rule here can also need an Entra authentication context on top (see Step-up sign-in), or groups (below).api: likeprotected, but an unauthenticated caller gets a 401 instead of a redirect to sign in.deny: the paths that never reach the app. The gateway answers 403 with its own page, signed in or not, and asks nobody to sign in first.
A path may appear in only one list. A public or deny rule cannot name an authentication context or groups: there
is nobody signed in to check.
Path rules and precedence#
Path rules are exact (/up) or prefix (a trailing slash, /assets/). There are no wildcards and no regular
expressions. Query strings are never part of the match.
One rule decides each request, and it is the most specific one that matches:
- The longest matching path wins, whichever list it is in.
/admin/open(public) beats/admin/(protected), and/telescope/(deny) beats alogindefault. - At the same length, an exact rule beats a prefix:
/upbeats/up/. - No rule matches: the app's
defaultdecides.
The winning rule is the whole answer. A more specific rule does not inherit anything from a shorter one: if
/admin/ names groups and /admin/reports/ names other groups, /admin/reports/q3 needs the second set only, and a
public path under a deny prefix is open. The gateway renders the rules least specific first, so Apache's own
section merging gives the same answer (the unit tests check both).
Groups#
A protected or api rule can name up to 20 groups. The signed-in person must hold at least one of them, or the
gateway answers 403 with its own page and sends nothing to the app:
oidc:
groups_claim: wsu_roles
apps:
- id: app1
protected:
- path: /admin/reports/
groups: [app1-reports, app1-admins]
oidc.groups_claimnames the ID token claim that lists the person's groups. A config with a group rule and nogroups_claimis refused, so a rule can never be quietly skipped. For WSU's tenant the claim iswsu_roles; another tenant might send Entra's owngroupsorrolesclaim.- A group name is 1 to 64 letters, digits and
.,_,@or-. The match is exact and case-sensitive. - The check happens inside the gateway, after sign-in, on every request. A person who loses a group loses the path when their ID token is next refreshed, which is at the next sign-in.
- Groups are a coarse gate in front of the app, for a tool only a few people should even reach. They do not replace the app's own authorization: the app still decides what each person may do, with the same claim from the assertion.
Deny by default#
default: deny refuses every path that no rule names. Use it for an app where only a few paths should exist on the
internet at all:
apps:
- id: tool
host: tool.apps.wayne.edu
upstream: http://tool:8080
default: deny
public: [/up]
protected: [/app/]
deny: [/app/debug/]
Here /up is open, everything under /app/ needs a sign-in, /app/debug/ and everything under it is refused, and
every other path (/, /.env, /vendor/) is refused without asking anyone to sign in.
Normalization#
A path with an encoded slash, a backslash, a semicolon, a control character or bad UTF-8 is refused: the guard
answers 400 before any rule is read. The gateway matches the normalized path, never the raw one, so /app/x/../debug/
is matched as /app/debug/. /_drawbridge belongs to the gateway.
Check a path with explain#
The explain <host> <path> command says which rule applies to a request, what it needs, and which rule decided:
php bin/drawbridge explain app1.apps.wayne.edu /admin/reports/monthly --config=config/drawbridge.yaml
app1 /admin/reports/monthly => login, needs one of the groups app1-reports, app1-admins in the ID token's wsu_roles claim (403 without) (matched as /admin/reports/monthly, by the rule for /admin/reports/)