Skip to content
Menu

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 (app1 in 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. Only assertion (a signed JWT that SESAME's gateway driver verifies) is accepted in 1.0; the header modes (headers, both) were removed.
  • default: what a path with no rule gets: login (the default), deny or public.
  • 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: like protected, 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:

  1. The longest matching path wins, whichever list it is in. /admin/open (public) beats /admin/ (protected), and /telescope/ (deny) beats a login default.
  2. At the same length, an exact rule beats a prefix: /up beats /up/.
  3. No rule matches: the app's default decides.

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_claim names the ID token claim that lists the person's groups. A config with a group rule and no groups_claim is refused, so a rule can never be quietly skipped. For WSU's tenant the claim is wsu_roles; another tenant might send Entra's own groups or roles claim.
  • 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/)