Try it without Entra#
Run the container rig to try the real gateway locally, with a mock OpenID Connect provider standing in for Entra, so nothing in the trial reaches Entra.
The rig#
The container rig is the local trial: the real gateway image, a mock OpenID Connect provider standing in for Entra, and a tiny echo app. Nothing in the rig reaches Entra. A plain run (and the keycloak run) ends with drawbridge smoke inside the gateway container, with no options, the way a deployment is checked.
Run it#
sh
sh rig/run.sh # Linux, macOS
PowerShell
rig\run.ps1 # Windows
What it starts#
The rig starts the real gateway image, a mock OpenID Connect provider standing in for Entra, and a tiny echo app.
What it checks#
It signs in synthetic users through the mock and checks protected and public paths, spoofed headers, forged callbacks, logout and step-up to an authentication context.
Opt-in profiles#
The keycloak argument swaps the mock for a pinned Keycloak started from rig/keycloak/realm.json and runs the sign-in, claims and logout tests against it. Unlike the mock, that provider checks the client secret and PKCE, signs in only the realm's two synthetic users, and refuses redirect URIs it was not given, so the run proves the round trip against a strict OpenID Connect implementation.
sh
sh rig/run.sh keycloak # Linux, macOS
PowerShell
rig\run.ps1 keycloak # Windows
The rotation argument walks a crypto passphrase change through the running gateway without recreating it. It signs in, saves the session cookie, re-renders the Apache config with the new passphrase while keeping the old one as mod_auth_openidc's documented previous value, sends Apache a graceful reload, and replays the saved cookie. The run documents what the pinned module actually does: it accepts the two values and starts, but its shared-memory session store is rebuilt empty on every reload, so the saved cookie is refused and the browser is sent to sign in again. The same refusal is then shown with the old passphrase dropped, and after the gateway container is recreated with a fresh sign-in, so the result is not an accident of the reload.
sh
sh rig/run.sh rotation # Linux, macOS
PowerShell
rig\run.ps1 rotation # Windows
The redis argument runs the gateway with gateway.session_store: redis (rig/config/drawbridge-redis.yaml) and a Redis service beside it. It signs in, sends Apache a graceful reload with the same passphrase, and replays the saved cookie, which must still be accepted because the sessions sit in Redis, not in Apache's shared memory (RedisTest::testSessionSurvivesAGatewayReload).
sh
sh rig/run.sh redis # Linux, macOS
PowerShell
rig\run.ps1 redis # Windows
The redis-rotation argument changes the castle password with the sessions in Redis. It signs in under passphrase A, reloads with B current and A previous (DRAWBRIDGE_OIDC_CRYPTO_PASSPHRASE_PREVIOUS), and checks that the saved cookie is still accepted and that a new sign-in works under B. It then reloads with B alone: the cookie from A is sent back to sign in (a redirect, not an error page) while the session from B keeps working. Last, it recreates the gateway from its environment on B, the way an operator finishes a rotation, and the session from B survives that too (RedisRotationTest).
sh
sh rig/run.sh redis-rotation # Linux, macOS
PowerShell
rig\run.ps1 redis-rotation # Windows
The multi argument raises a second gateway on the same Redis and rolls the same passphrase change across both, one at a time (MultiInstanceRotationTest). A session from either instance opens the app on the other once both know the new value, and once the old value is gone from both, both send a session sealed under it to sign in. Mid-roll, the instance still on the old value cannot read a session sealed under the new one and sends that visitor to sign in again, so a real roll should be quick.
sh
sh rig/run.sh multi # Linux, macOS
PowerShell
rig\run.ps1 multi # Windows
The trial argument runs the trial kit (trial/compose.yaml, the operator's two-service deployment of a gateway and the throwaway whoami app) with rig/trial.yaml on top for the mock provider, the keys and a tester. It signs in through whoami and checks the assertion whoami verified, sends whoami a forged assertion directly, around the gateway, and checks that whoami refuses it (TrialTest), and runs the smoke check. Then it drills the rollback in First deployment: the gateway moves to a "previous" image with up -d --no-deps gateway, whoami keeps running untouched, and both checks pass again.
sh
sh rig/run.sh trial # Linux, macOS
PowerShell
rig\run.ps1 trial # Windows
Stop it#
The rig is a single run: it works through its checks and ends, so there is nothing left running to stop. When the rig is green, the next step is the first real sign-in.