---
title: "Protecting paths | DRAWBRIDGE docs"
description: "How each app declares its public, protected, api and deny paths and its groups in one config file, how the most specific rule wins with no wildcards, and how a deny default keeps unlisted paths closed."
url: https://drawbridge.apps.wayne.edu/docs/guides/protecting-paths.html
llms: https://drawbridge.apps.wayne.edu/llms.txt
generator: Squire agent-ready
---

# Protecting paths [#](https://drawbridge.apps.wayne.edu/docs/guides/protecting-paths.html#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 [#](https://drawbridge.apps.wayne.edu/docs/guides/protecting-paths.html#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:

```yaml
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](https://drawbridge.apps.wayne.edu/docs/guides/step-up.html)), 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 [#](https://drawbridge.apps.wayne.edu/docs/guides/protecting-paths.html#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 [#](https://drawbridge.apps.wayne.edu/docs/guides/protecting-paths.html#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:

```yaml
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 [#](https://drawbridge.apps.wayne.edu/docs/guides/protecting-paths.html#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:

```yaml
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.

Note

Public is a decision, not a default. A path with no rule gets `login` unless the app says `deny` or `public`. Public paths carry no identity at all. The gateway's own error pages stay readable whatever the default is.

## Normalization [#](https://drawbridge.apps.wayne.edu/docs/guides/protecting-paths.html#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 [#](https://drawbridge.apps.wayne.edu/docs/guides/protecting-paths.html#check-a-path-with-explain)

The `explain <host> <path>` command says which rule applies to a request, what it needs, and which rule decided:

```sh
php bin/drawbridge explain app1.apps.wayne.edu /admin/reports/monthly --config=config/drawbridge.yaml
```

```text
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/)
```

## Related [#](https://drawbridge.apps.wayne.edu/docs/guides/protecting-paths.html#related)

- [How it works](https://drawbridge.apps.wayne.edu/docs/guides/how-it-works.html)
- [Step-up sign-in](https://drawbridge.apps.wayne.edu/docs/guides/step-up.html)
- [Log events](https://drawbridge.apps.wayne.edu/docs/reference/log-events.html)
- [Commands](https://drawbridge.apps.wayne.edu/docs/reference/commands.html)
